Fix documentation
[vlc.git] / bindings / cil / src / media.cs
1 /**
2  * @file media.cs
3  * @brief Media descriptor class
4  * @ingroup API
5  */
6
7 /**********************************************************************
8  *  Copyright (C) 2007-2009 RĂ©mi Denis-Courmont.                      *
9  *  This program is free software; you can redistribute and/or modify *
10  *  it under the terms of the GNU General Public License as published *
11  *  by the Free Software Foundation; version 2 of the license, or (at *
12  *  your option) any later version.                                   *
13  *                                                                    *
14  *  This program is distributed in the hope that it will be useful,   *
15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of    *
16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.              *
17  *  See the GNU General Public License for more details.              *
18  *                                                                    *
19  *  You should have received a copy of the GNU General Public License *
20  *  along with this program; if not, you can get it from:             *
21  *  http://www.gnu.org/copyleft/gpl.html                              *
22  **********************************************************************/
23
24 using System;
25 //using System.Collections.Generic;
26 using System.Runtime.InteropServices;
27
28 namespace VideoLAN.LibVLC
29 {
30     /**
31      * @brief MediaHandle: unmanaged LibVLC media pointer
32      * @ingroup Internals
33      */
34     internal sealed class MediaHandle : NonNullHandle
35     {
36         /**
37          * NonNullHandle.Destroy
38          */
39         protected override void Destroy ()
40         {
41             LibVLC.MediaRelease (handle);
42         }
43     };
44
45     /**
46      * @brief Media: a source media
47      * @ingroup API
48      * Each media object represents an input media, such as a file or an URL.
49      */
50     public class Media : BaseObject
51     {
52         internal MediaHandle Handle
53         {
54             get
55             {
56                 return handle as MediaHandle;
57             }
58         }
59
60         /**
61          * Creates a Media object.
62          *
63          * @param instance VLC instance
64          * @param mrl Media Resource Locator (file path or URL)
65          */
66         public Media (VLC instance, string mrl)
67         {
68             U8String umrl = new U8String (mrl);
69
70             handle = LibVLC.MediaCreate (instance.Handle, umrl, ex);
71             Raise ();
72         }
73
74         /**
75          * Add VLC input item options to the media.
76          * @param options VLC options in VLC input item format
77          *                (see example below)
78          * @param trusted whether the options are set by a trusted agent
79          *                (e.g. the local computer configuration) or not
80          *                (e.g. a downloaded file).
81          * @code
82          * Media m = new Media(vlc, "http://www.example.com/music.ogg");
83          * m.AddOptions(":http-user-agent=LibVLC.Net "
84          *            + ":http-proxy=proxy:8080", true);
85          * @endcode
86          */
87         public void AddOptions (string options, bool trusted)
88         {
89             U8String uopts = new U8String (options);
90
91             if (trusted)
92                 LibVLC.MediaAddOption (Handle, uopts, ex);
93             else
94                 LibVLC.MediaAddUntrustedOption (Handle, uopts, ex);
95             Raise ();
96         }
97     };
98 };