ITMTRemote.h

   1 /*
   2  *      MenuTunes
   3  *      ITMTRemote.h
   4  *
   5  *      Plugin definition for audio player control via MenuTunes.
   6  *
   7  *      This header defines the Objective-C protocol which all MenuTunes Remote
   8  *      plugins must implement.  To build a remote, create a subclass of this
   9  *      object, and implement each method in the @protocol below.
  10  *
  11  *      Copyright (c) 2002-2003 iThink Software
  12  *
  13  */
  14
  15 /*!
  16  * @header ITMTRemote
  17  * @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.
  18  */
  19 #import <Cocoa/Cocoa.h>
  20
  21 /*!
  22  * @enum ITMTRemotePlayerRunningState
  23  * @abstract Possible running states for the remote's player.
  24  * @discussion Used in fuctions that report or take the running state of the remote's player application.
  25  * @constant ITMTRemotePlayerNotRunning The remote's player isn't running.
  26  * @constant ITMTRemotePlayerLaunching The remote's player is starting up, or is running, but not yet accepting remote commands.
  27  * @constant ITMTRemotePlayerRunning The remote's player is running, and as such, is accepting remote commands.
  28  */
  29 typedef enum {
  30     ITMTRemotePlayerNotRunning = -1,
  31     ITMTRemotePlayerLaunching,
  32     ITMTRemotePlayerRunning
  33 } ITMTRemotePlayerRunningState;
  34
  35 /*!
  36  * @enum ITMTRemotePlayerPlayingState
  37  * @abstract Possible playing states for the remote's player.
  38  * @discussion Used in functions that report or take the playing state of the remote's player application.
  39  * @constant ITMTRemotePlayerStopped The remote's player is stopped.
  40  * @constant ITMTRemotePlayerPaused The remote's player is paused.
  41  * @constant ITMTRemotePlayerPlaying The remote's player is playing.
  42  * @constant ITMTRemotePlayerRewinding The remote's player is rewinding.
  43  * @constant ITMTRemotePlayerForwarding The remote's player is forwarding.
  44  */
  45 typedef enum {
  46     ITMTRemotePlayerStopped = -1,
  47     ITMTRemotePlayerPaused,
  48     ITMTRemotePlayerPlaying,
  49     ITMTRemotePlayerRewinding,
  50     ITMTRemotePlayerForwarding
  51 } ITMTRemotePlayerPlayingState;
  52
  53 /*!
  54  * @enum ITMTRemotePlayerPlaylistClass
  55  * @abstract Possible playlist classes used by a remote's player
  56  * @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
  57
  58 ITMTRemotePlayerPlaylist.
  59  * @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.
  60  * @constant ITMTRemotePlayerPlaylist The generic playlist. Created and maintained by the user.
  61  * @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.
  62  * @constant ITMTRemotePlayerRadioPlaylist This is for when playing tracks off of (online) radio stations.
  63  */
  64 typedef enum {
  65     ITMTRemotePlayerLibraryPlaylist = -1,
  66     ITMTRemotePlayerPlaylist,
  67     ITMTRemotePlayerSmartPlaylist,
  68     ITMTRemotePlayerRadioPlaylist
  69 } ITMTRemotePlayerPlaylistClass;
  70
  71 typedef enum {
  72     ITMTRemoteLibrarySource = -1,
  73     ITMTRemoteCDSource,
  74     ITMTRemoteRadioSource,
  75     ITMTRemoteiPodSource,
  76     ITMTRemoteGenericDeviceSource,
  77     ITMTRemoteSharedLibrarySource
  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 thei
 157
 158 r application. This should return "Audion 3", not simply "Audion". See playerSimpleName.
 159  * @result An NSString containing the remote's player's application filename
 160  */
 161 - (NSString *)playerFullName;
 162
 163 /*!
 164  * @method playerSimpleName
 165  * @abstract Returns the simplified name of the remote's player.
 166  * @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.
 167  * @result An NSString containing the simplified name of the remote's player.
 168  */
 169 - (NSString *)playerSimpleName;
 170
 171 /*!
 172  * @method capabilities
 173  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
 174  * @discussion Discussion Forthcoming.
 175  * @result An NSDictionary defining the capabilities of the remote and it's player.
 176  */
 177 - (NSDictionary *)capabilities;
 178
 179 /*!
 180  * @method showPrimaryInterface
 181  */
 182 - (BOOL)showPrimaryInterface;
 183
 184 /*!
 185  * @method playerRunningState
 186  * @abstract Returns the running state of the remote's player.
 187  * @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 play
 188
 189 er's process managment.
 190  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
 191  */
 192 - (ITMTRemotePlayerRunningState)playerRunningState;
 193
 194 /*!
 195  * @method playerPlayingState
 196  */
 197 - (ITMTRemotePlayerPlayingState)playerPlayingState;
 198
 199 /*!
 200  * @method playlists
 201  */
 202 - (NSArray *)playlists;
 203
 204 /*!
 205  * @method artists
 206  */
 207 - (NSArray *)artists;
 208
 209 /*!
 210  * @method albums
 211  */
 212 - (NSArray *)albums;
 213
 214 /*!
 215  * @method numberOfSongsInPlaylistAtIndex:
 216  */
 217 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
 218
 219 /*!
 220  * @method currentSource
 221  */
 222 - (ITMTRemotePlayerSource)currentSource;
 223
 224 /*!
 225  * @method currentSourceIndex
 226  */
 227 - (int)currentSourceIndex;
 228
 229 /*!
 230  * @method currentPlaylistClass
 231  */
 232 - (ITMTRemotePlayerPlaylistClass)currentPlaylistClass;
 233
 234 /*!
 235  * @method currentPlaylistIndex
 236  */
 237 - (int)currentPlaylistIndex;
 238
 239 /*!
 240  * @method songTitleAtIndex:
 241  */
 242 - (NSString *)songTitleAtIndex:(int)index;
 243
 244 /*!
 245  * @method songEnabledAtIndex:
 246  */
 247 - (BOOL)songEnabledAtIndex:(int)index;
 248
 249 /*!
 250  * @method currentAlbumTrackCount:
 251  */
 252 - (int)currentAlbumTrackCount;
 253
 254 /*!
 255  * @method currentSongTrack:
 256  */
 257 - (int)currentSongTrack;
 258
 259 /*!
 260  * @method playerStateUniqueIdentifier:
 261  */
 262 - (NSString *)playerStateUniqueIdentifier;
 263
 264 /*!
 265  * @method currentSongIndex
 266  */
 267 - (int)currentSongIndex;
 268
 269 /*!
 270  * @method currentSongTitle
 271  */
 272 - (NSString *)currentSongTitle;
 273
 274 /*!
 275  * @method currentSongArtist
 276  */
 277 - (NSString *)currentSongArtist;
 278
 279 /*!
 280  * @method currentSongComposer
 281  */
 282 - (NSString *)currentSongComposer;
 283
 284 /*!
 285  * @method currentSongAlbum
 286  */
 287 - (NSString *)currentSongAlbum;
 288
 289 /*!
 290  * @method currentSongGenre
 291  */
 292 - (NSString *)currentSongGenre;
 293
 294 /*!
 295  * @method currentSongLength
 296  */
 297 - (NSString *)currentSongLength;
 298
 299 /*!
 300  * @method currentSongPlayed
 301  */
 302 - (int)currentSongPlayed;
 303
 304 /*!
 305  * @method currentSongDuration
 306  */
 307 - (int)currentSongDuration;
 308
 309 /*!
 310  * @method currentSongRemaining
 311  */
 312 - (NSString *)currentSongRemaining;
 313
 314 /*!
 315  * @method currentSongElapsed
 316  */
 317 - (NSString *)currentSongElapsed;
 318
 319 /*!
 320  * @method currentSongAlbumArt
 321  */
 322 - (NSImage *)currentSongAlbumArt;
 323
 324 /*!
 325  * @method currentSongPlayCount
 326  */
 327 - (int)currentSongPlayCount;
 328
 329 /*!
 330  * @method currentSongRating
 331  */
 332 - (float)currentSongRating;
 333
 334 /*!
 335  * @method setCurrentSongRating:
 336  */
 337 - (BOOL)setCurrentSongRating:(float)rating;
 338
 339 /*!
 340  * @method currentSongShuffable
 341  */
 342 - (BOOL)currentSongShufflable;
 343
 344 /*!
 345  * @method setCurrentSongShuffable:
 346  */
 347 - (BOOL)setCurrentSongShufflable:(BOOL)shufflable;
 348
 349 /*!
 350  * @method equalizerEnabled
 351  */
 352 - (BOOL)equalizerEnabled;
 353
 354 /*!
 355  * @method setEqualizerEnabled:
 356  */
 357 - (BOOL)setEqualizerEnabled:(BOOL)enabled;
 358
 359 /*!
 360  * @method eqPresets
 361  */
 362 - (NSArray *)eqPresets;
 363
 364 /*!
 365  * @method currentEQPresetIndex
 366  */
 367 - (int)currentEQPresetIndex;
 368
 369 /*!
 370  * @method volume
 371  */
 372 - (float)volume;
 373
 374 /*!
 375  * @method setVolume:
 376  */
 377 - (BOOL)setVolume:(float)volume;
 378
 379 /*!
 380  * @method shuffleEnabled
 381  */
 382 - (BOOL)shuffleEnabled;
 383
 384 /*!
 385  * @method setShuffleEnabled:
 386  */
 387 - (BOOL)setShuffleEnabled:(BOOL)enabled;
 388
 389 /*!
 390  * @method repeatMode
 391  */
 392 - (ITMTRemotePlayerRepeatMode)repeatMode;
 393
 394 /*!
 395  * @method setRepeatMode:
 396  */
 397 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
 398
 399 /*!
 400  * @method play
 401  */
 402 - (BOOL)play;
 403
 404 /*!
 405  * @method pause
 406  */
 407 - (BOOL)pause;
 408
 409 /*!
 410  * @method goToNextSong
 411  */
 412 - (BOOL)goToNextSong;
 413
 414 /*!
 415  * @method goToPreviousSong
 416  */
 417 - (BOOL)goToPreviousSong;
 418
 419 /*!
 420  * @method forward
 421  */
 422 - (BOOL)forward;
 423
 424 /*!
 425  * @method rewind
 426  */
 427 - (BOOL)rewind;
 428
 429 /*!
 430  * @method switchToPlaylistAtIndex:
 431  */
 432 - (BOOL)switchToPlaylistAtIndex:(int)index;
 433
 434 /*!
 435  * @method switchToPlaylistAtIndex:
 436  */
 437 - (BOOL)switchToPlaylistAtIndex:(int)index ofSourceAtIndex:(int)index2;
 438
 439 /*!
 440  * @method switchToSongAtIndex:
 441  */
 442 - (BOOL)switchToSongAtIndex:(int)index;
 443
 444 /*!
 445  * @method switchToEQAtIndex:
 446  */
 447 - (BOOL)switchToEQAtIndex:(int)index;
 448
 449 /*!
 450  * @method makePlaylistWithTerm:ofType:
 451  */
 452 - (BOOL)makePlaylistWithTerm:(NSString *)term ofType:(int)type;
 453
 454 @end
 455
 456 /*!
 457  * @class ITMTRemote
 458  */
 459 @interface ITMTRemote : NSObject <ITMTRemote>
 460
 461 @end