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     BOOL                  isArtURLFetched;   //< Value used to determine of the other meta has been preparsed
 118     VLCMediaState         state;             //< Current state of the media
 119 }
 120
 121 /* Factories */
 122 /**
 123  * Manufactures a new VLCMedia object using the URL specified.
 124  * \param anURL URL to media to be accessed.
 125  * \return A new VLCMedia object, only if there were no errors.  This object 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 will be automatically released.
 134  * \see initWithPath
 135  */
 136 + (id)mediaWithPath:(NSString *)aPath;
 137
 138 /**
 139  * TODO
 140  * \param aName TODO
 141  * \return a new VLCMedia object, only if there were no errors.  This object
 142  * will be automatically released.
 143  * \see initAsNodeWithName
 144  */
 145 + (id)mediaAsNodeWithName:(NSString *)aName;
 146
 147 /* Initializers */
 148 /**
 149  * Initializes a new VLCMedia object to use the specified URL.
 150  * \param aPath Path to media to be accessed.
 151  * \return A new VLCMedia object, only if there were no errors.
 152  */
 153 - (id)initWithURL:(NSURL *)anURL;
 154
 155 /**
 156  * Initializes a new VLCMedia object to use the specified path.
 157  * \param aPath Path to media to be accessed.
 158  * \return A new VLCMedia object, only if there were no errors.
 159  */
 160 - (id)initWithPath:(NSString *)aPath;
 161
 162 /**
 163  * TODO
 164  * \param aName TODO
 165  * \return A new VLCMedia object, only if there were no errors.
 166  */
 167 - (id)initAsNodeWithName:(NSString *)aName;
 168
 169 /**
 170  * Returns an NSComparisonResult value that indicates the lexical ordering of
 171  * the receiver and a given meda.
 172  * \param media The media with which to compare with the receiver.
 173  * \return NSOrderedAscending if the URL of the receiver precedes media in
 174  * lexical ordering, NSOrderedSame if the URL of the receiver and media are
 175  * equivalent in lexical value, and NSOrderedDescending if the URL of the
 176  * receiver follows media. If media is nil, returns NSOrderedDescending.
 177  */
 178 - (NSComparisonResult)compare:(VLCMedia *)media;
 179
 180 /* Properties */
 181 /**
 182  * Receiver's delegate.
 183  */
 184 @property (assign) id delegate;
 185
 186 /**
 187  * A VLCTime object describing the length of the media resource, only if it is
 188  * available.  Use lengthWaitUntilDate: to wait for a specified length of time.
 189  * \see lengthWaitUntilDate
 190  */
 191 @property (retain, readonly) VLCTime * length;
 192
 193 /**
 194  * Returns a VLCTime object describing the length of the media resource,
 195  * however, this is a blocking operation and will wait until the preparsing is
 196  * completed before returning anything.
 197  * \param aDate Time for operation to wait until, if there are no results
 198  * before specified date then nil is returned.
 199  * \return The length of the media resource, nil if it couldn't wait for it.
 200  */
 201 - (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;
 202
 203 /**
 204  * Determines if the media has already been preparsed.
 205  */
 206 @property (readonly) BOOL isPreparsed;
 207
 208 /**
 209  * The URL for the receiver's media resource.
 210  */
 211 @property (retain, readonly) NSURL * url;
 212
 213 /**
 214  * The receiver's sub list.
 215  */
 216 @property (retain, readonly) VLCMediaList * subitems;
 217
 218 /**
 219  * The receiver's meta data as a NSDictionary object.
 220  */
 221 @property (retain, readonly) NSDictionary * metaDictionary;
 222
 223 /**
 224  * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
 225  */
 226 @property (readonly) VLCMediaState state;
 227 @end