git.sesse.net Git - vlc/blob - projects/macosx/framework/Headers/Public/VLCMedia.h

   1 /*****************************************************************************
   2  * VLCMedia.h: VLCKit.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 "VLCMediaList.h"
  26 #import "VLCTime.h"
  27
  28 /* Meta Dictionary Keys */
  29 /**
  30  * Standard dictionary keys for retreiving meta data.
  31  */
  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 */
  50
  51 /* Notification Messages */
  52 /**
  53  * Available notification messages.
  54  */
  55 extern NSString * VLCMediaMetaChanged;  //< Notification message for when the media's meta data has changed
  56
  57 // Forward declarations, supresses compiler error messages
  58 @class VLCMediaList;
  59 @class VLCMedia;
  60
  61 typedef enum VLCMediaState
  62 {
  63     VLCMediaStateNothingSpecial,        //< Nothing
  64     VLCMediaStateBuffering,             //< Stream is buffering
  65     VLCMediaStatePlaying,               //< Stream is playing
  66     VLCMediaStateError,                 //< Can't be played because an error occured
  67 } VLCMediaState;
  68
  69 /**
  70  * Informal protocol declaration for VLCMedia delegates.  Allows data changes to be
  71  * trapped.
  72  */
  73 @protocol VLCMediaDelegate
  74 // TODO: SubItemAdded/SubItemRemoved implementation.  Not sure if we really want to implement this.
  75 ///**
  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.
  80 // */
  81 // - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
  82
  83 ///**
  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.
  88 // */
  89 // - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
  90
  91 /**
  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.
  96  */
  97 - (void)media:(VLCMedia *)aMedia metaValueChangedFrom:(id)oldValue forKey:(NSString *)key;
  98 @end
  99
 100 /**
 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
 105  * \see VLCMediaList
 106  */
 107 @interface VLCMedia : NSObject
 108 {
 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
 118 }
 119
 120 /* 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 will be automatically released.
 125  * \see initWithMediaURL
 126  */
 127 + (id)mediaWithURL:(NSURL *)anURL;
 128
 129 /**
 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.
 133  * \see initWithPath
 134  */
 135 + (id)mediaWithPath:(NSString *)aPath;
 136
 137 /**
 138  * TODO
 139  * \param aName TODO
 140  * \return a new VLCMedia object, only if there were no errors.  This object
 141  * will be automatically released.
 142  * \see initAsNodeWithName
 143  */
 144 + (id)mediaAsNodeWithName:(NSString *)aName;
 145
 146 /* Initializers */
 147 /**
 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.
 151  */
 152 - (id)initWithURL:(NSURL *)anURL;
 153
 154 /**
 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.
 158  */
 159 - (id)initWithPath:(NSString *)aPath;
 160
 161 /**
 162  * TODO
 163  * \param aName TODO
 164  * \return A new VLCMedia object, only if there were no errors.
 165  */
 166 - (id)initAsNodeWithName:(NSString *)aName;
 167
 168 /**
 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.
 176  */
 177 - (NSComparisonResult)compare:(VLCMedia *)media;
 178
 179 /* Properties */
 180 /**
 181  * Receiver's delegate.
 182  */
 183 @property (assign) id delegate;
 184
 185 /**
 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
 189  */
 190 @property (retain, readonly) VLCTime * length;
 191
 192 /**
 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.
 199  */
 200 - (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;
 201
 202 /**
 203  * Determines if the media has already been preparsed.
 204  */
 205 @property (readonly) BOOL isPreparsed;
 206
 207 /**
 208  * The URL for the receiver's media resource.
 209  */
 210 @property (retain, readonly) NSURL * url;
 211
 212 /**
 213  * The receiver's sub list.
 214  */
 215 @property (retain, readonly) VLCMediaList * subitems;
 216
 217 /**
 218  * The receiver's meta data as a NSDictionary object.
 219  */
 220 @property (retain, readonly) NSDictionary * metaDictionary;
 221
 222 /**
 223  * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
 224  */
 225 @property (readonly) VLCMediaState state;
 226 @end