1 /*****************************************************************************
2 * VLCMedia.h: VLCKit.framework VLCMedia header
3 *****************************************************************************
4 * Copyright (C) 2007 Pierre d'Herbemont
5 * Copyright (C) 2007 the VideoLAN team
8 * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
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.
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.
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 *****************************************************************************/
25 #import "VLCMediaList.h"
28 /* Meta Dictionary Keys */
30 * Standard dictionary keys for retreiving meta data.
32 extern NSString * VLCMetaInformationTitle; /* NSString */
33 extern NSString * VLCMetaInformationArtist; /* NSString */
34 extern NSString * VLCMetaInformationGenre; /* NSString */
35 extern NSString * VLCMetaInformationCopyright; /* NSString */
36 extern NSString * VLCMetaInformationAlbum; /* NSString */
37 extern NSString * VLCMetaInformationTrackNumber; /* NSString */
38 extern NSString * VLCMetaInformationDescription; /* NSString */
39 extern NSString * VLCMetaInformationRating; /* NSString */
40 extern NSString * VLCMetaInformationDate; /* NSString */
41 extern NSString * VLCMetaInformationSetting; /* NSString */
42 extern NSString * VLCMetaInformationURL; /* NSString */
43 extern NSString * VLCMetaInformationLanguage; /* NSString */
44 extern NSString * VLCMetaInformationNowPlaying; /* NSString */
45 extern NSString * VLCMetaInformationPublisher; /* NSString */
46 extern NSString * VLCMetaInformationEncodedBy; /* NSString */
47 extern NSString * VLCMetaInformationArtworkURL; /* NSString */
48 extern NSString * VLCMetaInformationArtwork; /* NSImage */
49 extern NSString * VLCMetaInformationTrackID; /* NSString */
51 /* Notification Messages */
53 * Available notification messages.
55 extern NSString * VLCMediaMetaChanged; //< Notification message for when the media's meta data has changed
57 // Forward declarations, supresses compiler error messages
61 typedef enum VLCMediaState
63 VLCMediaStateNothingSpecial, //< Nothing
64 VLCMediaStateBuffering, //< Stream is buffering
65 VLCMediaStatePlaying, //< Stream is playing
66 VLCMediaStateError, //< Can't be played because an error occured
70 * Informal protocol declaration for VLCMedia delegates. Allows data changes to be
73 @protocol VLCMediaDelegate
74 // TODO: SubItemAdded/SubItemRemoved implementation. Not sure if we really want to implement this.
76 // * Delegate method called whenever a sub item has been added to the specified VLCMedia.
77 // * \param aMedia The media resource that has received the new sub item.
78 // * \param childMedia The new sub item added.
79 // * \param index Location of the new subitem in the aMedia's sublist.
81 // - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
84 // * Delegate method called whenever a sub item has been removed from the specified VLCMedia.
85 // * \param aMedia The media resource that has had a sub item removed from.
86 // * \param childMedia The sub item removed.
87 // * \param index The previous location of the recently removed sub item.
89 // - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
92 * Delegate method called whenever the meta has changed for the receiver.
93 * \param aMedia The media resource whose meta data has been changed.
94 * \param oldValue The old meta data value.
95 * \param key The key of the value that was changed.
97 - (void)media:(VLCMedia *)aMedia metaValueChangedFrom:(id)oldValue forKey:(NSString *)key;
101 * Defines files and streams as a managed object. Each media object can be
102 * administered seperately. VLCMediaPlayer or VLCMediaList must be used
103 * to execute the appropriate playback functions.
104 * \see VLCMediaPlayer
107 @interface VLCMedia : NSObject
109 void * p_md; //< Internal media descriptor instance
110 NSURL * url; //< URL (MRL) for this media resource
111 VLCMediaList * subitems; //< Sub list of items
112 VLCTime * length; //< Cached duration of the media
113 NSMutableDictionary * metaDictionary; //< Meta data storage
114 id delegate; //< Delegate object
115 BOOL isArtFetched; //< Value used to determine of the artwork has been preparsed
116 BOOL areOthersMetaFetched; //< Value used to determine of the other meta has been preparsed
117 VLCMediaState state; //< Current state of the media
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 will be automatically released.
125 * \see initWithMediaURL
127 + (id)mediaWithURL:(NSURL *)anURL;
130 * Manufactures a new VLCMedia object using the path specified.
131 * \param aPath Path to the media to be accessed.
132 * \return A new VLCMedia object, only if there were no errors. This object will be automatically released.
135 + (id)mediaWithPath:(NSString *)aPath;
140 * \return a new VLCMedia object, only if there were no errors. This object
141 * will be automatically released.
142 * \see initAsNodeWithName
144 + (id)mediaAsNodeWithName:(NSString *)aName;
148 * Initializes a new VLCMedia object to use the specified URL.
149 * \param aPath Path to media to be accessed.
150 * \return A new VLCMedia object, only if there were no errors.
152 - (id)initWithURL:(NSURL *)anURL;
155 * Initializes a new VLCMedia object to use the specified path.
156 * \param aPath Path to media to be accessed.
157 * \return A new VLCMedia object, only if there were no errors.
159 - (id)initWithPath:(NSString *)aPath;
164 * \return A new VLCMedia object, only if there were no errors.
166 - (id)initAsNodeWithName:(NSString *)aName;
169 * Returns an NSComparisonResult value that indicates the lexical ordering of
170 * the receiver and a given meda.
171 * \param media The media with which to compare with the receiver.
172 * \return NSOrderedAscending if the URL of the receiver precedes media in
173 * lexical ordering, NSOrderedSame if the URL of the receiver and media are
174 * equivalent in lexical value, and NSOrderedDescending if the URL of the
175 * receiver follows media. If media is nil, returns NSOrderedDescending.
177 - (NSComparisonResult)compare:(VLCMedia *)media;
181 * Receiver's delegate.
183 @property (assign) id delegate;
186 * A VLCTime object describing the length of the media resource, only if it is
187 * available. Use lengthWaitUntilDate: to wait for a specified length of time.
188 * \see lengthWaitUntilDate
190 @property (retain, readonly) VLCTime * length;
193 * Returns a VLCTime object describing the length of the media resource,
194 * however, this is a blocking operation and will wait until the preparsing is
195 * completed before returning anything.
196 * \param aDate Time for operation to wait until, if there are no results
197 * before specified date then nil is returned.
198 * \return The length of the media resource, nil if it couldn't wait for it.
200 - (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;
203 * Determines if the media has already been preparsed.
205 @property (readonly) BOOL isPreparsed;
208 * The URL for the receiver's media resource.
210 @property (retain, readonly) NSURL * url;
213 * The receiver's sub list.
215 @property (retain, readonly) VLCMediaList * subitems;
218 * The receiver's meta data as a NSDictionary object.
220 @property (retain, readonly) NSDictionary * metaDictionary;
223 * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
225 @property (readonly) VLCMediaState state;