Use @see instead of @ref
[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          */
151         public SafeHandle Object
152         {
153             get
154             {
155                 return LibVLC.GetVLCInstance (Handle);
156             }
157         }
158     };
159 };
160
161 /**
162  * @mainpage libvlc-cil documentation
163  *
164  * @section Introduction
165  *
166  * libvlc-cil is a thin API layer around LibVLC,
167  * the VideoLAN's project media framework C library.
168  * LibVLC comes built-in the VLC media player.
169  *
170  * With libvlc-cil, you can use LibVLC
171  * from within the .Net Common Language Runtime,
172  * with the CIL programming language of your preference.
173  * However, libvlc-cil and the code sample in this documentation
174  * are written is C#.
175  *
176  * @section Installation
177  *
178  * libvlc-cil does <b>not</b> include the underlying LibVLC by default.
179  * Make sure VLC, or at least LibVLC and the relevant VLC plugins are present.
180  * The LibVLC runtime library needs to be in the library search path for the
181  * Common Language Runtime. Check the documentation for your CLR for details.
182  *
183  * On Windows, libvlc.dll needs to be in the current directory, the DLL path
184  * of the running process, or the system search path (but the latter is
185  * uncommon and not supported by the official LibVLC installer).
186  *
187  * On Linux, libvlc.so should be in /usr/lib; if it is in another directory,
188  * such as /usr/local/lib, you might need to add that directory to the
189  * LD_LIBRARY_PATH environment variable.
190  *
191  * @section Usage
192  *
193  * First, you need to create a VLC instance. This will load and setup the
194  * native VLC runtime, the VLC configuration, the list of available plugins,
195  * the platform adaptation and the VLC log messages and objects subsystems
196  * @code
197  * using System;
198  * using VideoLAN.LibVLC;
199  * ...
200  *
201  * try {
202  *     Console.WriteLine("Running on VLC version {0}", VLC.Version);
203  * }
204  * catch (Exception e) {
205  *     Console.WriteLine("VLC is not available on your system.");
206  *     throw e;
207  * }
208  *
209  * string[] args = new string[]{ "-v", "--ignore-config" };
210  * VLC vlc = new VLC(args);
211  * @endcode
212  * @see VideoLAN::LibVLC::VLC
213  *
214  * To play media, you need a media and a player.
215  * @code
216  * Media media = new Media(vlc, "http://www.example.com/video.ogv");
217  * Player player = new Player(media);
218  * player.Play();
219  * @endcode
220  * @see VideoLAN::LibVLC::Media @see VideoLAN::LibVLC::Player
221  *
222  * All these objects use unmanaged resources.
223  * They all implement the IDisposeable interface.
224  * You should dispose them when you do not need them anymore:
225  * @code
226  * player.Dispose();
227  * media.Dispose();
228  * vlc.Dispose();
229  * @endcode
230  */