ITMTRemote.h

   1 /*
   2  *  MenuTunes
   3  *  ITMTRemote
   4  *    Plugin definition for audio player control via MenuTunes
   5  *
   6  *  Original Author : Matt Judy <mjudy@ithinksw.com>
   7  *   Responsibility : Matt Judy <mjudy@ithinksw.com>
   8  *
   9  *  Copyright (c) 2002 - 2003 iThink Software.
  10  *  All Rights Reserved
  11  *
  12  *      This header defines the Objective-C protocol which all MenuTunes Remote
  13  *  plugins must implement.  To build a remote, create a subclass of this
  14  *  object, and implement each method in the @protocol below.
  15  *
  16  */
  17
  18 /*!
  19  * @header ITMTRemote
  20  * @discussion This header defines the Objective-C protocol which all MenuTunes Remote plugins must implement.  To build a remote, create a subclass of the ITMTRemote object, and implement each method in the ITMTRemote protocol.
  21  */
  22 #import <Cocoa/Cocoa.h>
  23
  24 /*!
  25  * @enum ITMTRemotePlayerRunningState
  26  * @abstract Possible running states for the remote's player.
  27  * @discussion Used in fuctions that report or take the running state of the remote's player application.
  28  * @constant ITMTRemotePlayerNotRunning The remote's player isn't running.
  29  * @constant ITMTRemotePlayerLaunching The remote's player is starting up, or is running, but not yet accepting remote commands.
  30  * @constant ITMTRemotePlayerRunning The remote's player is running, and as such, is accepting remote commands.
  31  */
  32 typedef enum {
  33     ITMTRemotePlayerNotRunning = -1,
  34     ITMTRemotePlayerLaunching,
  35     ITMTRemotePlayerRunning
  36 } ITMTRemotePlayerRunningState;
  37
  38 /*!
  39  * @enum ITMTRemotePlayerPlayingState
  40  * @abstract Possible playing states for the remote's player.
  41  * @discussion Used in functions that report or take the playing state of the remote's player application.
  42  * @constant ITMTRemotePlayerStopped The remote's player is stopped.
  43  * @constant ITMTRemotePlayerPaused The remote's player is paused.
  44  * @constant ITMTRemotePlayerPlaying The remote's player is playing.
  45  * @constant ITMTRemotePlayerRewinding The remote's player is rewinding.
  46  * @constant ITMTRemotePlayerForwarding The remote's player is forwarding.
  47  */
  48 typedef enum {
  49     ITMTRemotePlayerStopped = -1,
  50     ITMTRemotePlayerPaused,
  51     ITMTRemotePlayerPlaying,
  52     ITMTRemotePlayerRewinding,
  53     ITMTRemotePlayerForwarding
  54 } ITMTRemotePlayerPlayingState;
  55
  56 /*!
  57  * @enum ITMTRemotePlayerPlaylistClass
  58  * @abstract Possible playlist classes used by a remote's player
  59  * @discussion Used in functions that report the class of a playlist to MenuTunes. While we borrow the terms/descriptions from iTunes, these should work fine with any other player. If your player doesn't support a given type of playlist, then just return ITMTRemotePlayerPlaylist.
  60  * @constant ITMTRemotePlayerLibraryPlaylist For players that have one playlist that contains all of a user's music, or for players that don't have the concept of multiple playlists, this is the class for that "Master" list.
  61  * @constant ITMTRemotePlayerPlaylist The generic playlist. Created and maintained by the user.
  62  * @constant ITMTRemotePlayerSmartPlaylist A smart playlist is a playlist who's contents are dynamic, based on a set of criteria or updated by a script. These are usually not edited directly by the user, but instead maintained by the player.
  63  * @constant ITMTRemotePlayerRadioPlaylist This is for when playing tracks off of (online) radio stations.
  64  */
  65 typedef enum {
  66     ITMTRemotePlayerLibraryPlaylist = -1,
  67     ITMTRemotePlayerPlaylist,
  68     ITMTRemotePlayerSmartPlaylist,
  69     ITMTRemotePlayerRadioPlaylist
  70 } ITMTRemotePlayerPlaylistClass;
  71
  72 typedef enum {
  73     ITMTRemoteLibrarySource = -1,
  74     ITMTRemoteCDSource,
  75     ITMTRemoteRadioSource,
  76     ITMTRemoteiPodSource,
  77     ITMTRemoteMP3PlayerSource
  78 } ITMTRemotePlayerSource;
  79
  80 /*!
  81  * @enum ITMTRemotePlayerRepeatMode
  82  * @abstract Possible repeat modes for the remote's player.
  83  * @discussion Used in functions that report or set the remote's player's repeat mode.
  84  * @constant ITMTRemotePlayerRepeatOff The player plays all of the songs in a playlist through to the end, and then stops.
  85  * @constant ITMTRemotePlayerRepeatAll The player plays all of the songs in a playlist through to the end, and then starts over again from the beginning.
  86  * @constant ITMTRemotePlayerRepeatOne The player loops playing the selected song.
  87  */
  88 typedef enum {
  89     ITMTRemotePlayerRepeatOff = -1,
  90     ITMTRemotePlayerRepeatAll,
  91     ITMTRemotePlayerRepeatOne
  92 } ITMTRemotePlayerRepeatMode;
  93
  94 /*!
  95  * @protocol ITMTRemote
  96  * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
  97  */
  98 @protocol ITMTRemote
  99
 100 /*!
 101  * @method remote
 102  * @abstract Returns an autoreleased instance of the remote.
 103  * @discussion Should be very quick and compact.
 104  *
 105  * EXAMPLE:<br>
 106  * + (id)remote<br>
 107  * {<br>
 108  * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return [[[MyRemote alloc] init] autorelease];<br>
 109  * }
 110  *
 111  * @result An instance of the remote.
 112  */
 113 + (id)remote;
 114
 115 /*!
 116  * @method remoteTitle
 117  * @abstract Returns the remote's title/name.
 118  * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
 119  * @result An NSString containing the title/name of the remote.
 120  */
 121 - (NSString *)remoteTitle;
 122
 123 /*!
 124  * @method remoteInformation
 125  * @abstract Returns the remote's information.
 126  * @discussion Information on the remote that the user will see when selecting which remote to use. The information returned here has no bearing on how the remote works, it's simply here for informing the user.
 127  * @result An NSString containing the information for the remote.
 128  */
 129 - (NSString *)remoteInformation;
 130
 131 /*!
 132  * @method remoteIcon
 133  * @abstract Returns the remote's icon.
 134  * @discussion This icon is shown while the user is selecting which remote to use. Typically, this is the remote's player's application icon, however it can be anything you like.
 135  * @result An NSImage containing the icon of the remote.
 136  */
 137 - (NSImage *)remoteIcon;
 138
 139 /*!
 140  * @method begin
 141  * @abstract Sent when the remote should begin operation.
 142  * @result A result code signifying success.
 143  */
 144 - (BOOL)begin;
 145
 146 /*!
 147  * @method halt
 148  * @abstract Sent when the remote should cease operation.
 149  * @result A result code signifying success.
 150  */
 151 - (BOOL)halt;
 152
 153 /*!
 154  * @method playerFullName
 155  * @abstract Returns the remote's player's application filename.
 156  * @discussion This string should be the name typically used by the remote's player's application bundle/file. For example, Panic's Audion audio player is known simply as "Audion", however, the application bundle is called "Audion 3" for version 3 of their application. This should return "Audion 3", not simply "Audion". See playerSimpleName.
 157  * @result An NSString containing the remote's player's application filename
 158  */
 159 - (NSString *)playerFullName;
 160
 161 /*!
 162  * @method playerSimpleName
 163  * @abstract Returns the simplified name of the remote's player.
 164  * @discussion This is the name used in the User Interface for when referring to the remote's player. Continuing the example from the playerFullName method, this method would return simply "Audion", as that is how the player is known.
 165  * @result An NSString containing the simplified name of the remote's player.
 166  */
 167 - (NSString *)playerSimpleName;
 168
 169 /*!
 170  * @method capabilities
 171  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
 172  * @discussion Discussion Forthcoming.
 173  * @result An NSDictionary defining the capabilities of the remote and it's player.
 174  */
 175 - (NSDictionary *)capabilities;
 176
 177 /*!
 178  * @method showPrimaryInterface
 179  */
 180 - (BOOL)showPrimaryInterface;
 181
 182 /*!
 183  * @method playerRunningState
 184  * @abstract Returns the running state of the remote's player.
 185  * @discussion While most remotes will use only ITMTRemotePlayerNotRunning or ITMTRemotePlayerRunning, we have included support for ITMTRemotePlayerLaunching (see ITMTRemotePlayerRunningState) for remotes that want the most precise control over their player's process managment.
 186  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
 187  */
 188 - (ITMTRemotePlayerRunningState)playerRunningState;
 189
 190 /*!
 191  * @method playerPlayingState
 192  */
 193 - (ITMTRemotePlayerPlayingState)playerPlayingState;
 194
 195 /*!
 196  * @method playlists
 197  */
 198 - (NSArray *)playlists;
 199
 200 /*!
 201  * @method numberOfSongsInPlaylistAtIndex:
 202  */
 203 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
 204
 205 /*!
 206  * @method currentSource
 207  */
 208 - (ITMTRemotePlayerSource)currentSource;
 209
 210 /*!
 211  * @method currentPlaylistClass
 212  */
 213 - (ITMTRemotePlayerPlaylistClass)currentPlaylistClass;
 214
 215 /*!
 216  * @method currentPlaylistIndex
 217  */
 218 - (int)currentPlaylistIndex;
 219
 220 /*!
 221  * @method songTitleAtIndex:
 222  */
 223 - (NSString *)songTitleAtIndex:(int)index;
 224
 225 /*!
 226  * @method currentAlbumTrackCount:
 227  */
 228 - (int)currentAlbumTrackCount;
 229
 230 /*!
 231  * @method currentSongTrack:
 232  */
 233 - (int)currentSongTrack;
 234
 235 /*!
 236  * @method playerStateUniqueIdentifier:
 237  */
 238 - (NSString *)playerStateUniqueIdentifier;
 239
 240 /*!
 241  * @method currentSongIndex
 242  */
 243 - (int)currentSongIndex;
 244
 245 /*!
 246  * @method currentSongTitle
 247  */
 248 - (NSString *)currentSongTitle;
 249
 250 /*!
 251  * @method currentSongArtist
 252  */
 253 - (NSString *)currentSongArtist;
 254
 255 /*!
 256  * @method currentSongAlbum
 257  */
 258 - (NSString *)currentSongAlbum;
 259
 260 /*!
 261  * @method currentSongGenre
 262  */
 263 - (NSString *)currentSongGenre;
 264
 265 /*!
 266  * @method currentSongLength
 267  */
 268 - (NSString *)currentSongLength;
 269
 270 /*!
 271  * @method currentSongRemaining
 272  */
 273 - (NSString *)currentSongRemaining;
 274
 275 /*!
 276  * @method currentSongRating
 277  */
 278 - (float)currentSongRating;
 279
 280 /*!
 281  * @method setCurrentSongRating:
 282  */
 283 - (BOOL)setCurrentSongRating:(float)rating;
 284
 285 /*!
 286  * @method eqPresets
 287  */
 288 - (NSArray *)eqPresets;
 289
 290 /*!
 291  * @method currentEQPresetIndex
 292  */
 293 - (int)currentEQPresetIndex;
 294
 295 /*!
 296  * @method volume
 297  */
 298 - (float)volume;
 299
 300 /*!
 301  * @method setVolume:
 302  */
 303 - (BOOL)setVolume:(float)volume;
 304
 305 /*!
 306  * @method shuffleEnabled
 307  */
 308 - (BOOL)shuffleEnabled;
 309
 310 /*!
 311  * @method setShuffleEnabled:
 312  */
 313 - (BOOL)setShuffleEnabled:(BOOL)enabled;
 314
 315 /*!
 316  * @method repeatMode
 317  */
 318 - (ITMTRemotePlayerRepeatMode)repeatMode;
 319
 320 /*!
 321  * @method setRepeatMode:
 322  */
 323 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
 324
 325 /*!
 326  * @method play
 327  */
 328 - (BOOL)play;
 329
 330 /*!
 331  * @method pause
 332  */
 333 - (BOOL)pause;
 334
 335 /*!
 336  * @method goToNextSong
 337  */
 338 - (BOOL)goToNextSong;
 339
 340 /*!
 341  * @method goToPreviousSong
 342  */
 343 - (BOOL)goToPreviousSong;
 344
 345 /*!
 346  * @method forward
 347  */
 348 - (BOOL)forward;
 349
 350 /*!
 351  * @method rewind
 352  */
 353 - (BOOL)rewind;
 354
 355 /*!
 356  * @method switchToPlaylistAtIndex:
 357  */
 358 - (BOOL)switchToPlaylistAtIndex:(int)index;
 359
 360 /*!
 361  * @method switchToSongAtIndex:
 362  */
 363 - (BOOL)switchToSongAtIndex:(int)index;
 364
 365 /*!
 366  * @method switchToEQAtIndex:
 367  */
 368 - (BOOL)switchToEQAtIndex:(int)index;
 369
 370 @end
 371
 372 /*!
 373  * @class ITMTRemote
 374  */
 375 @interface ITMTRemote : NSObject <ITMTRemote>
 376
 377 @end