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