git.sesse.net Git - vlc/blob - 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