git.sesse.net Git - vlc/blob - 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  */