Add a forgotten file to Modules.am
[vlc.git] / bindings / cil / src / instance.cs
1 /**
2  * @file instance.cs
3  * @brief LibVLC instance class
4  * @ingroup API
5  *
6  * @defgroup API Managed interface to LibVLC
7  *
8  * This is the primary class library for .NET applications
9  * to embed and control LibVLC.
10  */
11
12 /**********************************************************************
13  *  Copyright (C) 2007-2009 RĂ©mi Denis-Courmont.                      *
14  *  This program is free software; you can redistribute and/or modify *
15  *  it under the terms of the GNU General Public License as published *
16  *  by the Free Software Foundation; version 2 of the license, or (at *
17  *  your option) any later version.                                   *
18  *                                                                    *
19  *  This program is distributed in the hope that it will be useful,   *
20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of    *
21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.              *
22  *  See the GNU General Public License for more details.              *
23  *                                                                    *
24  *  You should have received a copy of the GNU General Public License *
25  *  along with this program; if not, you can get it from:             *
26  *  http://www.gnu.org/copyleft/gpl.html                              *
27  **********************************************************************/
28
29 using System;
30 using System.Runtime.InteropServices;
31
32 /**
33  * @brief VideoLAN.LibVLC: VideoLAN project's LibVLC .Net bindings
34  * @ingroup API
35  *
36  * This namespace provides a set of managed APIs around the native LibVLC
37  * for the .Net Common Language Runtime.
38  */
39 namespace VideoLAN.LibVLC
40 {
41     /**
42      * @brief InstanceHandle: unmanaged LibVLC instance pointer
43      * @ingroup Internals
44      */
45     internal sealed class InstanceHandle : NonNullHandle
46     {
47         /**
48          * NonNullHandle.Destroy
49          */
50         protected override void Destroy ()
51         {
52             LibVLC.Release (handle, null);
53         }
54     };
55
56     /**
57      * @brief VLC: VLC media player instance
58      * @ingroup API
59      *
60      * The VLC class provides represent a run-time instance of a media player.
61      * An instance can spawn multiple independent medias, however
62      * configuration settings, message logging, etc are common to all medias
63      * from the same instance.
64      */
65     public class VLC : BaseObject
66     {
67         internal InstanceHandle Handle
68         {
69             get
70             {
71                 return handle as InstanceHandle;
72             }
73         }
74
75         /**
76          * Loads the native LibVLC and creates a LibVLC instance.
77          *
78          * @param args VLC command line parameters for the LibVLC Instance.
79          */
80         public VLC (string[] args)
81         {
82             U8String[] argv = new U8String[args.Length];
83             for (int i = 0; i < args.Length; i++)
84                 argv[i] = new U8String (args[i]);
85
86             handle = LibVLC.Create (argv.Length, argv, ex);
87             Raise ();
88         }
89
90         /**
91          * Starts a VLC interface plugin.
92          *
93          * @param name name of the interface plugin (e.g. "http", "qt4", ...)
94          */
95         public void AddInterface (string name)
96         {
97             U8String uname = new U8String (name);
98
99             LibVLC.AddIntf (Handle, uname, ex);
100             Raise ();
101         }
102
103         /**
104          * Waits until VLC instance exits. This can happen if a fatal error
105          * occurs (e.g. cannot parse the arguments), if the user has quit
106          * through an interface, or if the special vlc://quit item was played.
107          */
108         public void Run ()
109         {
110             LibVLC.Wait (Handle);
111         }
112
113         /**
114          * The human-readable LibVLC version number.
115          */
116         public static string Version
117         {
118             get
119             {
120                 return U8String.FromNative (LibVLC.GetVersion ());
121             }
122         }
123
124         /**
125          * The human-readable LibVLC C compiler infos.
126          */
127         public static string Compiler
128         {
129             get
130             {
131                 return U8String.FromNative (LibVLC.GetCompiler ());
132             }
133         }
134
135         /**
136          * The unique commit identifier from the LibVLC source control system,
137          * or "exported" if unknown.
138          */
139         public static string ChangeSet
140         {
141             get
142             {
143                 return U8String.FromNative (LibVLC.GetChangeset ());
144             }
145         }
146
147         /**
148          * The unmanaged VLC-internal instance object.
149          * Do not use this unless you really know what you are doing.
150          * @version VLC 1.0
151          */
152         public SafeHandle Object
153         {
154             get
155             {
156                 return LibVLC.GetVLCInstance (Handle);
157             }
158         }
159     };
160 };
161
162 /**
163  * @mainpage libvlc-cil documentation
164  *
165  * @section Introduction
166  *
167  * libvlc-cil is a thin API layer around LibVLC,
168  * the VideoLAN's project media framework C library.
169  * LibVLC comes built-in the VLC media player.
170  *
171  * With libvlc-cil, you can use LibVLC
172  * from within the .Net Common Language Runtime,
173  * with the CIL programming language of your preference.
174  * However, libvlc-cil and the code sample in this documentation
175  * are written is C#.
176  *
177  * @section Installation
178  *
179  * libvlc-cil does <b>not</b> include the underlying LibVLC by default.
180  * Make sure VLC, or at least LibVLC and the relevant VLC plugins are present.
181  * The LibVLC runtime library needs to be in the library search path for the
182  * Common Language Runtime. Check the documentation for your CLR for details.
183  *
184  * On Windows, libvlc.dll needs to be in the current directory, the DLL path
185  * of the running process, or the system search path (but the latter is
186  * uncommon and not supported by the official LibVLC installer).
187  *
188  * On Linux, libvlc.so should be in /usr/lib; if it is in another directory,
189  * such as /usr/local/lib, you might need to add that directory to the
190  * LD_LIBRARY_PATH environment variable.
191  *
192  * @section Usage
193  *
194  * First, you need to create a VLC instance. This will load and setup the
195  * native VLC runtime, the VLC configuration, the list of available plugins,
196  * the platform adaptation and the VLC log messages and objects subsystems
197  * @code
198  * using System;
199  * using VideoLAN.LibVLC;
200  * ...
201  *
202  * try {
203  *     Console.WriteLine("Running on VLC version {0}", VLC.Version);
204  * }
205  * catch (Exception e) {
206  *     Console.WriteLine("VLC is not available on your system.");
207  *     throw e;
208  * }
209  *
210  * string[] args = new string[]{ "-v", "--ignore-config" };
211  * VLC vlc = new VLC(args);
212  * @endcode
213  * @see VideoLAN::LibVLC::VLC
214  *
215  * To play media, you need a media and a player.
216  * @code
217  * Media media = new Media(vlc, "http://www.example.com/video.ogv");
218  * Player player = new Player(media);
219  * player.Play();
220  * @endcode
221  * @see VideoLAN::LibVLC::Media @see VideoLAN::LibVLC::Player
222  *
223  * All these objects use unmanaged resources.
224  * They all implement the IDisposeable interface.
225  * You should dispose them when you do not need them anymore:
226  * @code
227  * player.Dispose();
228  * media.Dispose();
229  * vlc.Dispose();
230  * @endcode
231  */