MacOSX/Framework/VLCMedia: make the url property an NSURL.
[vlc.git] / extras / MacOSX / Framework / Headers / Public / VLCMedia.h
1 /*****************************************************************************
2  * VLCMedia.h: VLC.framework VLCMedia header
3  *****************************************************************************
4  * Copyright (C) 2007 Pierre d'Herbemont
5  * Copyright (C) 2007 the VideoLAN team
6  * $Id$
7  *
8  * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
9  *
10  * This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, write to the Free Software
22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23  *****************************************************************************/
24
25 #import <Cocoa/Cocoa.h>
26 #import "VLCMediaList.h"
27 #import "VLCTime.h"
28
29 /* Meta Dictionary Keys */
30 /**
31  * Standard dictionary keys for retreiving meta data.
32  */
33 extern NSString * VLCMetaInformationTitle;          /* NSString */
34 extern NSString * VLCMetaInformationArtist;         /* NSString */
35 extern NSString * VLCMetaInformationGenre;          /* NSString */
36 extern NSString * VLCMetaInformationCopyright;      /* NSString */
37 extern NSString * VLCMetaInformationAlbum;          /* NSString */
38 extern NSString * VLCMetaInformationTrackNumber;    /* NSString */
39 extern NSString * VLCMetaInformationDescription;    /* NSString */
40 extern NSString * VLCMetaInformationRating;         /* NSString */
41 extern NSString * VLCMetaInformationDate;           /* NSString */
42 extern NSString * VLCMetaInformationSetting;        /* NSString */
43 extern NSString * VLCMetaInformationURL;            /* NSString */
44 extern NSString * VLCMetaInformationLanguage;       /* NSString */
45 extern NSString * VLCMetaInformationNowPlaying;     /* NSString */
46 extern NSString * VLCMetaInformationPublisher;      /* NSString */
47 extern NSString * VLCMetaInformationEncodedBy;      /* NSString */
48 extern NSString * VLCMetaInformationArtworkURL;     /* NSString */
49 extern NSString * VLCMetaInformationArtwork;        /* NSImage  */
50 extern NSString * VLCMetaInformationTrackID;        /* NSString */
51
52 /* Notification Messages */
53 /**
54  * Available notification messages.
55  */
56 extern NSString * VLCMediaMetaChanged;  //< Notification message for when the media's meta data has changed
57
58 // Forward declarations, supresses compiler error messages
59 @class VLCMediaList;
60 @class VLCMedia;
61
62 typedef enum VLCMediaState
63 {
64     VLCMediaStateNothingSpecial,        //< Nothing
65     VLCMediaStateBuffering,             //< Stream is buffering
66     VLCMediaStatePlaying,               //< Stream is playing
67     VLCMediaStateError,                 //< Can't be played because an error occured
68 } VLCMediaState;
69
70 /**
71  * Informal protocol declaration for VLCMedia delegates.  Allows data changes to be
72  * trapped.
73  */
74 @protocol VLCMediaDelegate
75 // TODO: SubItemAdded/SubItemRemoved implementation.  Not sure if we really want to implement this.
76 ///**
77 // * Delegate method called whenever a sub item has been added to the specified VLCMedia.
78 // * \param aMedia The media resource that has received the new sub item.
79 // * \param childMedia The new sub item added.
80 // * \param index Location of the new subitem in the aMedia's sublist.
81 // */
82 // - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
83
84 ///**
85 // * Delegate method called whenever a sub item has been removed from the specified VLCMedia.
86 // * \param aMedia The media resource that has had a sub item removed from.
87 // * \param childMedia The sub item removed.
88 // * \param index The previous location of the recently removed sub item.
89 // */
90 // - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
91
92 /**
93  * Delegate method called whenever the meta has changed for the receiver.
94  * \param aMedia The media resource whose meta data has been changed.
95  * \param oldValue The old meta data value.
96  * \param key The key of the value that was changed.
97  */
98 - (void)media:(VLCMedia *)aMedia metaValueChangedFrom:(id)oldValue forKey:(NSString *)key;
99 @end
100
101 /**
102  * Defines files and streams as a managed object.  Each media object can be 
103  * administered seperately.  VLCMediaPlayer or VLCMediaControl must be used 
104  * to execute the appropriate playback functions.
105  * \see VLCMediaPlayer
106  * \see VLCMediaControl
107  */
108 @interface VLCMedia : NSObject
109 {
110     void *                p_md;              //< Internal media descriptor instance
111     NSURL *               url;               //< URL for this media resource
112     VLCMediaList *        subitems;          //< Sub list of items
113     VLCTime *             length;            //< Duration of the media
114     NSMutableDictionary * metaDictionary;    //< Meta data storage
115     id                    delegate;          //< Delegate object
116     BOOL                  preparsed;         //< Value used to determine of the file has been preparsed
117     VLCMediaState         state;
118 }
119
120 /* Object Factories */
121 /**
122  * Manufactures a new VLCMedia object using the URL specified.
123  * \param anURL URL to media to be accessed.
124  * \return A new VLCMedia object, only if there were no errors.  This object 
125  * will be automatically released.
126  * \see initWithMediaURL
127  */
128 + (id)mediaWithURL:(NSURL *)anURL;
129
130 /**
131  * Manufactures a new VLCMedia object using the path specified.
132  * \param aPath Path to the media to be accessed.
133  * \return A new VLCMedia object, only if there were no errors.  This object 
134  * will be automatically released.
135  * \see initWithPath
136  */
137 + (id)mediaWithPath:(NSString *)aPath;
138
139 /**
140  * TODO
141  * \param aName TODO
142  * \return a new VLCMedia object, only if there were no errors.  This object
143  * will be automatically released.
144  * \see initAsNodeWithName
145  */
146 + (id)mediaAsNodeWithName:(NSString *)aName;
147
148 /* Initializers */
149 /**
150  * Initializes a new VLCMedia object to use the specified URL.  
151  * \param aPath Path to media to be accessed.
152  * \return A new VLCMedia object, only if there were no errors.
153  */
154 - (id)initWithURL:(NSURL *)anURL;
155
156 /**
157  * Initializes a new VLCMedia object to use the specified path.  
158  * \param aPath Path to media to be accessed.
159  * \return A new VLCMedia object, only if there were no errors.
160  */
161 - (id)initWithPath:(NSString *)aPath;
162
163 /**
164  * TODO
165  * \param aName TODO
166  * \return A new VLCMedia object, only if there were no errors.
167  */
168 - (id)initAsNodeWithName:(NSString *)aName;
169
170 /**
171  * Returns an NSComparisonResult value that indicates the lexical ordering of 
172  * the receiver and a given meda.
173  * \param media The media with which to compare with the receiver.
174  * \return NSOrderedAscending if the URL of the receiver precedes media in 
175  * lexical ordering, NSOrderedSame if the URL of the receiver and media are 
176  * equivalent in lexical value, and NSOrderedDescending if the URL of the 
177  * receiver follows media. If media is nil, returns NSOrderedDescending.
178  */
179 - (NSComparisonResult)compare:(VLCMedia *)media;
180
181 /* Properties */
182 /**
183  * Receiver's delegate.
184  */
185 @property (assign) id delegate;
186
187 /**
188  * A VLCTime object describing the length of the media resource, only if it is
189  * available.  Use lengthWaitUntilDate: to wait for a specified length of time.
190  * \see lengthWaitUntilDate
191  */
192 @property (readonly) VLCTime * length;
193
194 /**
195  * Returns a VLCTime object describing the length of the media resource,
196  * however, this is a blocking operation and will wait until the preparsing is
197  * completed before returning anything.
198  * \param aDate Time for operation to wait until, if there are no results
199  * before specified date then nil is returned.
200  * \return The length of the media resource, nil if it couldn't wait for it.
201  */
202 - (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;
203
204 /**
205  * Determines if the media has already been preparsed. 
206  */
207 @property (readonly) BOOL isPreparsed;
208
209 /**
210  * The URL for the receiver's media resource.
211  */
212 @property (readonly) NSURL * url;
213
214 /**
215  * The receiver's sub list.
216  */
217 @property (readonly) VLCMediaList * subitems;
218
219 /**
220  * The receiver's meta data as a NSDictionary object.
221  */
222 @property (readonly) NSDictionary * metaDictionary;
223
224 /**
225  * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
226  */
227 @property (readonly) VLCMediaState state;
228 @end