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
  60
  61 ITMTRemotePlayerPlaylist.
  62  * @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.
  63  * @constant ITMTRemotePlayerPlaylist The generic playlist. Created and maintained by the user.
  64  * @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.
  65  * @constant ITMTRemotePlayerRadioPlaylist This is for when playing tracks off of (online) radio stations.
  66  */
  67 typedef enum {
  68     ITMTRemotePlayerLibraryPlaylist = -1,
  69     ITMTRemotePlayerPlaylist,
  70     ITMTRemotePlayerSmartPlaylist,
  71     ITMTRemotePlayerRadioPlaylist
  72 } ITMTRemotePlayerPlaylistClass;
  73
  74 typedef enum {
  75     ITMTRemoteLibrarySource = -1,
  76     ITMTRemoteCDSource,
  77     ITMTRemoteRadioSource,
  78     ITMTRemoteiPodSource,
  79     ITMTRemoteGenericDeviceSource,
  80     ITMTRemoteSharedLibrarySource
  81 } ITMTRemotePlayerSource;
  82
  83 /*!
  84  * @enum ITMTRemotePlayerRepeatMode
  85  * @abstract Possible repeat modes for the remote's player.
  86  * @discussion Used in functions that report or set the remote's player's repeat mode.
  87  * @constant ITMTRemotePlayerRepeatOff The player plays all of the songs in a playlist through to the end, and then stops.
  88  * @constant ITMTRemotePlayerRepeatAll The player plays all of the songs in a playlist through to the end, and then starts over again from the beginning.
  89  * @constant ITMTRemotePlayerRepeatOne The player loops playing the selected song.
  90  */
  91 typedef enum {
  92     ITMTRemotePlayerRepeatOff = -1,
  93     ITMTRemotePlayerRepeatAll,
  94     ITMTRemotePlayerRepeatOne
  95 } ITMTRemotePlayerRepeatMode;
  96
  97 /*!
  98  * @protocol ITMTRemote
  99  * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
 100  */
 101 @protocol ITMTRemote
 102
 103 /*!
 104  * @method remote
 105  * @abstract Returns an autoreleased instance of the remote.
 106  * @discussion Should be very quick and compact.
 107  *
 108  * EXAMPLE:<br>
 109  * + (id)remote<br>
 110  * {<br>
 111  * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return [[[MyRemote alloc] init] autorelease];<br>
 112  * }
 113  *
 114  * @result An instance of the remote.
 115  */
 116 + (id)remote;
 117
 118 /*!
 119  * @method remoteTitle
 120  * @abstract Returns the remote's title/name.
 121  * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
 122  * @result An NSString containing the title/name of the remote.
 123  */
 124 - (NSString *)remoteTitle;
 125
 126 /*!
 127  * @method remoteInformation
 128  * @abstract Returns the remote's information.
 129  * @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.
 130  * @result An NSString containing the information for the remote.
 131  */
 132 - (NSString *)remoteInformation;
 133
 134 /*!
 135  * @method remoteIcon
 136  * @abstract Returns the remote's icon.
 137  * @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.
 138  * @result An NSImage containing the icon of the remote.
 139  */
 140 - (NSImage *)remoteIcon;
 141
 142 /*!
 143  * @method begin
 144  * @abstract Sent when the remote should begin operation.
 145  * @result A result code signifying success.
 146  */
 147 - (BOOL)begin;
 148
 149 /*!
 150  * @method halt
 151  * @abstract Sent when the remote should cease operation.
 152  * @result A result code signifying success.
 153  */
 154 - (BOOL)halt;
 155
 156 /*!
 157  * @method playerFullName
 158  * @abstract Returns the remote's player's application filename.
 159  * @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
 160
 161 r application. This should return "Audion 3", not simply "Audion". See playerSimpleName.
 162  * @result An NSString containing the remote's player's application filename
 163  */
 164 - (NSString *)playerFullName;
 165
 166 /*!
 167  * @method playerSimpleName
 168  * @abstract Returns the simplified name of the remote's player.
 169  * @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.
 170  * @result An NSString containing the simplified name of the remote's player.
 171  */
 172 - (NSString *)playerSimpleName;
 173
 174 /*!
 175  * @method capabilities
 176  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
 177  * @discussion Discussion Forthcoming.
 178  * @result An NSDictionary defining the capabilities of the remote and it's player.
 179  */
 180 - (NSDictionary *)capabilities;
 181
 182 /*!
 183  * @method showPrimaryInterface
 184  */
 185 - (BOOL)showPrimaryInterface;
 186
 187 /*!
 188  * @method playerRunningState
 189  * @abstract Returns the running state of the remote's player.
 190  * @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
 191
 192 er's process managment.
 193  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
 194  */
 195 - (ITMTRemotePlayerRunningState)playerRunningState;
 196
 197 /*!
 198  * @method playerPlayingState
 199  */
 200 - (ITMTRemotePlayerPlayingState)playerPlayingState;
 201
 202 /*!
 203  * @method playlists
 204  */
 205 - (NSArray *)playlists;
 206
 207 /*!
 208  * @method artists
 209  */
 210 - (NSArray *)artists;
 211
 212 /*!
 213  * @method albums
 214  */
 215 - (NSArray *)albums;
 216
 217 /*!
 218  * @method numberOfSongsInPlaylistAtIndex:
 219  */
 220 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
 221
 222 /*!
 223  * @method currentSource
 224  */
 225 - (ITMTRemotePlayerSource)currentSource;
 226
 227 /*!
 228  * @method currentSourceIndex
 229  */
 230 - (int)currentSourceIndex;
 231
 232 /*!
 233  * @method currentPlaylistClass
 234  */
 235 - (ITMTRemotePlayerPlaylistClass)currentPlaylistClass;
 236
 237 /*!
 238  * @method currentPlaylistIndex
 239  */
 240 - (int)currentPlaylistIndex;
 241
 242 /*!
 243  * @method songTitleAtIndex:
 244  */
 245 - (NSString *)songTitleAtIndex:(int)index;
 246
 247 /*!
 248  * @method currentAlbumTrackCount:
 249  */
 250 - (int)currentAlbumTrackCount;
 251
 252 /*!
 253  * @method currentSongTrack:
 254  */
 255 - (int)currentSongTrack;
 256
 257 /*!
 258  * @method playerStateUniqueIdentifier:
 259  */
 260 - (NSString *)playerStateUniqueIdentifier;
 261
 262 /*!
 263  * @method currentSongIndex
 264  */
 265 - (int)currentSongIndex;
 266
 267 /*!
 268  * @method currentSongTitle
 269  */
 270 - (NSString *)currentSongTitle;
 271
 272 /*!
 273  * @method currentSongArtist
 274  */
 275 - (NSString *)currentSongArtist;
 276
 277 /*!
 278  * @method currentSongComposer
 279  */
 280 - (NSString *)currentSongComposer;
 281
 282 /*!
 283  * @method currentSongAlbum
 284  */
 285 - (NSString *)currentSongAlbum;
 286
 287 /*!
 288  * @method currentSongGenre
 289  */
 290 - (NSString *)currentSongGenre;
 291
 292 /*!
 293  * @method currentSongLength
 294  */
 295 - (NSString *)currentSongLength;
 296
 297 /*!
 298  * @method currentSongRemaining
 299  */
 300 - (NSString *)currentSongRemaining;
 301
 302 /*!
 303  * @method currentSongElapsed
 304  */
 305 - (NSString *)currentSongElapsed;
 306
 307 /*!
 308  * @method currentSongAlbumArt
 309  */
 310 - (NSImage *)currentSongAlbumArt;
 311
 312 /*!
 313  * @method currentSongPlayCount
 314  */
 315 - (int)currentSongPlayCount;
 316
 317 /*!
 318  * @method currentSongRating
 319  */
 320 - (float)currentSongRating;
 321
 322 /*!
 323  * @method setCurrentSongRating:
 324  */
 325 - (BOOL)setCurrentSongRating:(float)rating;
 326
 327 /*!
 328  * @method equalizerEnabled
 329  */
 330 - (BOOL)equalizerEnabled;
 331
 332 /*!
 333  * @method setEqualizerEnabled:
 334  */
 335 - (BOOL)setEqualizerEnabled:(BOOL)enabled;
 336
 337 /*!
 338  * @method eqPresets
 339  */
 340 - (NSArray *)eqPresets;
 341
 342 /*!
 343  * @method currentEQPresetIndex
 344  */
 345 - (int)currentEQPresetIndex;
 346
 347 /*!
 348  * @method volume
 349  */
 350 - (float)volume;
 351
 352 /*!
 353  * @method setVolume:
 354  */
 355 - (BOOL)setVolume:(float)volume;
 356
 357 /*!
 358  * @method shuffleEnabled
 359  */
 360 - (BOOL)shuffleEnabled;
 361
 362 /*!
 363  * @method setShuffleEnabled:
 364  */
 365 - (BOOL)setShuffleEnabled:(BOOL)enabled;
 366
 367 /*!
 368  * @method repeatMode
 369  */
 370 - (ITMTRemotePlayerRepeatMode)repeatMode;
 371
 372 /*!
 373  * @method setRepeatMode:
 374  */
 375 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
 376
 377 /*!
 378  * @method play
 379  */
 380 - (BOOL)play;
 381
 382 /*!
 383  * @method pause
 384  */
 385 - (BOOL)pause;
 386
 387 /*!
 388  * @method goToNextSong
 389  */
 390 - (BOOL)goToNextSong;
 391
 392 /*!
 393  * @method goToPreviousSong
 394  */
 395 - (BOOL)goToPreviousSong;
 396
 397 /*!
 398  * @method forward
 399  */
 400 - (BOOL)forward;
 401
 402 /*!
 403  * @method rewind
 404  */
 405 - (BOOL)rewind;
 406
 407 /*!
 408  * @method switchToPlaylistAtIndex:
 409  */
 410 - (BOOL)switchToPlaylistAtIndex:(int)index;
 411
 412 /*!
 413  * @method switchToPlaylistAtIndex:
 414  */
 415 - (BOOL)switchToPlaylistAtIndex:(int)index ofSourceAtIndex:(int)index2;
 416
 417 /*!
 418  * @method switchToSongAtIndex:
 419  */
 420 - (BOOL)switchToSongAtIndex:(int)index;
 421
 422 /*!
 423  * @method switchToEQAtIndex:
 424  */
 425 - (BOOL)switchToEQAtIndex:(int)index;
 426
 427 /*!
 428  * @method makePlaylistWithTerm:ofType:
 429  */
 430 - (BOOL)makePlaylistWithTerm:(NSString *)term ofType:(int)type;
 431
 432 @end
 433
 434 /*!
 435  * @class ITMTRemote
 436  */
 437 @interface ITMTRemote : NSObject <ITMTRemote>
 438
 439 @end