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 ITMTRemotePlayerRepeatMode
  58  * @abstract Possible repeat modes for the remote's player.
  59  * @discussion Used in functions that report or set the remote's player's repeat mode.
  60  * @constant ITMTRemotePlayerRepeatOff The player plays all of the songs in a playlist through to the end, and then stops.
  61  * @constant ITMTRemotePlayerRepeatAll The player plays all of the songs in a playlist through to the end, and then starts over again from the beginning.
  62  * @constant ITMTRemotePlayerRepeatOne The player loops playing the selected song.
  63  */
  64 typedef enum {
  65     ITMTRemotePlayerRepeatOff = -1,
  66     ITMTRemotePlayerRepeatAll,
  67     ITMTRemotePlayerRepeatOne
  68 } ITMTRemotePlayerRepeatMode;
  69
  70 /*!
  71  * @protocol ITMTRemote
  72  * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
  73  */
  74 @protocol ITMTRemote
  75
  76 /*!
  77  * @method remote
  78  * @abstract Returns an autoreleased instance of the remote.
  79  * @discussion Should be very quick and compact.
  80  *
  81  * EXAMPLE:<br>
  82  * + (id)remote<br>
  83  * {<br>
  84  * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return [[[MyRemote alloc] init] autorelease];<br>
  85  * }
  86  *
  87  * @result An instance of the remote.
  88  */
  89 + (id)remote;
  90
  91 /*!
  92  * @method remoteTitle
  93  * @abstract Returns the remote's title/name.
  94  * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
  95  * @result An NSString containing the title/name of the remote.
  96  */
  97 - (NSString *)remoteTitle;
  98
  99 /*!
 100  * @method remoteInformation
 101  * @abstract Returns the remote's information.
 102  * @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.
 103  * @result An NSString containing the information for the remote.
 104  */
 105 - (NSString *)remoteInformation;
 106
 107 /*!
 108  * @method remoteIcon
 109  * @abstract Returns the remote's icon.
 110  * @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.
 111  * @result An NSImage containing the icon of the remote.
 112  */
 113 - (NSImage *)remoteIcon;
 114
 115 /*!
 116  * @method begin
 117  * @abstract Sent when the remote should begin operation.
 118  * @result A result code signifying success.
 119  */
 120 - (BOOL)begin;
 121
 122 /*!
 123  * @method halt
 124  * @abstract Sent when the remote should cease operation.
 125  * @result A result code signifying success.
 126  */
 127 - (BOOL)halt;
 128
 129 /*!
 130  * @method playerFullName
 131  * @abstract Returns the remote's player's application filename.
 132  * @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.
 133  * @result An NSString containing the remote's player's application filename
 134  */
 135 - (NSString *)playerFullName;
 136
 137 /*!
 138  * @method playerSimpleName
 139  * @abstract Returns the simplified name of the remote's player.
 140  * @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.
 141  * @result An NSString containing the simplified name of the remote's player.
 142  */
 143 - (NSString *)playerSimpleName;
 144
 145 /*!
 146  * @method capabilities
 147  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
 148  * @discussion Discussion Forthcoming.
 149  * @result An NSDictionary defining the capabilities of the remote and it's player.
 150  */
 151 - (NSDictionary *)capabilities;
 152
 153 /*!
 154  * @method playerRunningState
 155  * @abstract Returns the running state of the remote's player.
 156  * @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.
 157  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
 158  */
 159 - (ITMTRemotePlayerRunningState)playerRunningState;
 160
 161 /*!
 162  * @method playerPlayingState
 163  */
 164 - (ITMTRemotePlayerPlayingState)playerPlayingState;
 165
 166 /*!
 167  * @method playlists
 168  */
 169 - (NSArray *)playlists;
 170
 171 /*!
 172  * @method numberOfSongsInPlaylistAtIndex:
 173  */
 174 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
 175
 176 /*!
 177  * @method classOfPlaylistAtIndex:
 178  */
 179 - (NSString *)classOfPlaylistAtIndex:(int)index;
 180
 181 /*!
 182  * @method currentPlaylistIndex
 183  */
 184 - (int)currentPlaylistIndex;
 185
 186 /*!
 187  * @method songTitleAtIndex:
 188  */
 189 - (NSString *)songTitleAtIndex:(int)index;
 190
 191 /*!
 192  * @method currentSongIndex
 193  */
 194 - (int)currentSongIndex;
 195
 196 /*!
 197  * @method currentSongTitle
 198  */
 199 - (NSString *)currentSongTitle;
 200
 201 /*!
 202  * @method currentSongArtist
 203  */
 204 - (NSString *)currentSongArtist;
 205
 206 /*!
 207  * @method currentSongAlbum
 208  */
 209 - (NSString *)currentSongAlbum;
 210
 211 /*!
 212  * @method currentSongGenre
 213  */
 214 - (NSString *)currentSongGenre;
 215
 216 /*!
 217  * @method currentSongLength
 218  */
 219 - (NSString *)currentSongLength;
 220
 221 /*!
 222  * @method currentSongRemaining
 223  */
 224 - (NSString *)currentSongRemaining;
 225
 226 /*!
 227  * @method currentSongRating
 228  */
 229 - (float)currentSongRating;
 230
 231 /*!
 232  * @method setCurrentSongRating:
 233  */
 234 - (BOOL)setCurrentSongRating:(float)rating;
 235
 236 /*!
 237  * @method equalizerEnabled
 238  */
 239 - (BOOL)equalizerEnabled;
 240
 241 /*!
 242  * @method setEqualizerEnabled:
 243  */
 244 - (BOOL)setEqualizerEnabled:(BOOL)enabled;
 245
 246 /*!
 247  * @method eqPresets
 248  */
 249 - (NSArray *)eqPresets;
 250
 251 /*!
 252  * @method currentEQPresetIndex
 253  */
 254 - (int)currentEQPresetIndex;
 255
 256 /*!
 257  * @method volume
 258  */
 259 - (float)volume;
 260
 261 /*!
 262  * @method setVolume:
 263  */
 264 - (BOOL)setVolume:(float)volume;
 265
 266 /*!
 267  * @method shuffleEnabled
 268  */
 269 - (BOOL)shuffleEnabled;
 270
 271 /*!
 272  * @method setShuffleEnabled:
 273  */
 274 - (BOOL)setShuffleEnabled:(BOOL)enabled;
 275
 276 /*!
 277  * @method repeatMode
 278  */
 279 - (ITMTRemotePlayerRepeatMode)repeatMode;
 280
 281 /*!
 282  * @method setRepeatMode:
 283  */
 284 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
 285
 286 /*!
 287  * @method play
 288  */
 289 - (BOOL)play;
 290
 291 /*!
 292  * @method pause
 293  */
 294 - (BOOL)pause;
 295
 296 /*!
 297  * @method goToNextSong
 298  */
 299 - (BOOL)goToNextSong;
 300
 301 /*!
 302  * @method goToPreviousSong
 303  */
 304 - (BOOL)goToPreviousSong;
 305
 306 /*!
 307  * @method forward
 308  */
 309 - (BOOL)forward;
 310
 311 /*!
 312  * @method rewind
 313  */
 314 - (BOOL)rewind;
 315
 316 /*!
 317  * @method switchToPlaylistAtIndex:
 318  */
 319 - (BOOL)switchToPlaylistAtIndex:(int)index;
 320
 321 /*!
 322  * @method switchToSongAtIndex:
 323  */
 324 - (BOOL)switchToSongAtIndex:(int)index;
 325
 326 /*!
 327  * @method switchToEQAtIndex:
 328  */
 329 - (BOOL)switchToEQAtIndex:(int)index;
 330
 331 @end
 332
 333 /*!
 334  * @class ITMTRemote
 335  */
 336 @interface ITMTRemote : NSObject <ITMTRemote>
 337
 338 @end