2 * This file is part of DisOrder.
3 * Copyright (C) 2010 Richard Kettlewell
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 #ifndef CLIENT_STUBS_H
19 #define CLIENT_STUBS_H
21 /** @brief Adopt a track
23 * Makes the calling user owner of a randomly picked track.
27 * @return 0 on success, non-0 on error
29 int disorder_adopt(disorder_client *c, const char *id);
31 /** @brief Create a user
33 * Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.
36 * @param user New username
37 * @param password Initial password
38 * @param rights Initial rights (optional)
39 * @return 0 on success, non-0 on error
41 int disorder_adduser(disorder_client *c, const char *user, const char *password, const char *rights);
43 /** @brief List files and directories in a directory
45 * See 'files' and 'dirs' for more specific lists.
48 * @param dir Directory to list (optional)
49 * @param re Regexp that results must match (optional)
50 * @param filesp List of matching files and directories
51 * @param nfilesp Number of elements in filesp
52 * @return 0 on success, non-0 on error
54 int disorder_allfiles(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
56 /** @brief Confirm registration
58 * The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are.
61 * @param confirmation Confirmation string
62 * @return 0 on success, non-0 on error
64 int disorder_confirm(disorder_client *c, const char *confirmation);
66 /** @brief Log in with a cookie
68 * The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.
71 * @param cookie Cookie string
72 * @return 0 on success, non-0 on error
74 int disorder_cookie(disorder_client *c, const char *cookie);
76 /** @brief Delete user
78 * Requires the 'admin' right.
81 * @param user User to delete
82 * @return 0 on success, non-0 on error
84 int disorder_deluser(disorder_client *c, const char *user);
86 /** @brief List directories in a directory
91 * @param dir Directory to list (optional)
92 * @param re Regexp that results must match (optional)
93 * @param filesp List of matching directories
94 * @param nfilesp Number of elements in filesp
95 * @return 0 on success, non-0 on error
97 int disorder_dirs(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
99 /** @brief Disable play
101 * Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.
104 * @return 0 on success, non-0 on error
106 int disorder_disable(disorder_client *c);
108 /** @brief Set a user property
110 * With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
113 * @param username User to modify
114 * @param property Property name
115 * @param value New property value
116 * @return 0 on success, non-0 on error
118 int disorder_edituser(disorder_client *c, const char *username, const char *property, const char *value);
120 /** @brief Enable play
122 * Requires the 'global prefs' right.
125 * @return 0 on success, non-0 on error
127 int disorder_enable(disorder_client *c);
129 /** @brief Detect whether play is enabled
134 * @param enabledp 1 if play is enabled and 0 otherwise
135 * @return 0 on success, non-0 on error
137 int disorder_enabled(disorder_client *c, int *enabledp);
139 /** @brief Test whether a track exists
144 * @param track Track name
145 * @param existsp 1 if the track exists and 0 otherwise
146 * @return 0 on success, non-0 on error
148 int disorder_exists(disorder_client *c, const char *track, int *existsp);
150 /** @brief List files in a directory
155 * @param dir Directory to list (optional)
156 * @param re Regexp that results must match (optional)
157 * @param filesp List of matching files
158 * @param nfilesp Number of elements in filesp
159 * @return 0 on success, non-0 on error
161 int disorder_files(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
163 /** @brief Get a track preference
165 * If the track does not exist that is an error. If the track exists but the preference does not then a null value is returned.
168 * @param track Track name
169 * @param pref Preference name
170 * @param valuep Preference value
171 * @return 0 on success, non-0 on error
173 int disorder_get(disorder_client *c, const char *track, const char *pref, char **valuep);
175 /** @brief Get a global preference
177 * If the preference does exist not then a null value is returned.
180 * @param pref Global preference name
181 * @param valuep Preference value
182 * @return 0 on success, non-0 on error
184 int disorder_get_global(disorder_client *c, const char *pref, char **valuep);
186 /** @brief Get a track's length
188 * If the track does not exist an error is returned.
191 * @param track Track name
192 * @param lengthp Track length in seconds
193 * @return 0 on success, non-0 on error
195 int disorder_length(disorder_client *c, const char *track, long *lengthp);
197 /** @brief Create a login cookie for this user
199 * The cookie may be redeemed via the 'cookie' command
202 * @param cookiep Newly created cookie
203 * @return 0 on success, non-0 on error
205 int disorder_make_cookie(disorder_client *c, char **cookiep);
207 /** @brief Move a track
209 * Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.
212 * @param track Track ID or name
213 * @param delta How far to move the track towards the head of the queue
214 * @return 0 on success, non-0 on error
216 int disorder_move(disorder_client *c, const char *track, long delta);
218 /** @brief Move multiple tracks
220 * Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.
223 * @param target Move after this track, or to head if ""
224 * @param ids List of tracks to move by ID
225 * @param nids Length of ids
226 * @return 0 on success, non-0 on error
228 int disorder_moveafter(disorder_client *c, const char *target, char **ids, int nids);
230 /** @brief Do nothing
232 * Used as a keepalive. No authentication required.
235 * @return 0 on success, non-0 on error
237 int disorder_nop(disorder_client *c);
239 /** @brief Get a track name part
241 * If the name part cannot be constructed an empty string is returned.
244 * @param track Track name
245 * @param context Context ("sort" or "display")
246 * @param part Name part ("artist", "album" or "title")
247 * @param partp Value of name part
248 * @return 0 on success, non-0 on error
250 int disorder_part(disorder_client *c, const char *track, const char *context, const char *part, char **partp);
252 /** @brief Pause the currently playing track
254 * Requires the 'pause' right.
257 * @return 0 on success, non-0 on error
259 int disorder_pause(disorder_client *c);
261 /** @brief Play a track
263 * Requires the 'play' right.
266 * @param track Track to play
267 * @param idp Queue ID of new track
268 * @return 0 on success, non-0 on error
270 int disorder_play(disorder_client *c, const char *track, char **idp);
272 /** @brief Play multiple tracks
274 * Requires the 'play' right.
277 * @param target Insert into queue after this track, or at head if ""
278 * @param tracks List of track names to play
279 * @param ntracks Length of tracks
280 * @return 0 on success, non-0 on error
282 int disorder_playafter(disorder_client *c, const char *target, char **tracks, int ntracks);
284 /** @brief Retrieve the playing track
289 * @param playingp Details of the playing track
290 * @return 0 on success, non-0 on error
292 int disorder_playing(disorder_client *c, struct queue_entry **playingp);
294 /** @brief Delete a playlist
296 * Requires the 'play' right and permission to modify the playlist.
299 * @param playlist Playlist to delete
300 * @return 0 on success, non-0 on error
302 int disorder_playlist_delete(disorder_client *c, const char *playlist);
304 /** @brief List the contents of a playlist
306 * Requires the 'read' right and oermission to read the playlist.
309 * @param playlist Playlist name
310 * @param tracksp List of tracks in playlist
311 * @param ntracksp Number of elements in tracksp
312 * @return 0 on success, non-0 on error
314 int disorder_playlist_get(disorder_client *c, const char *playlist, char ***tracksp, int *ntracksp);
316 /** @brief Get a playlist's sharing status
318 * Requires the 'read' right and permission to read the playlist.
321 * @param playlist Playlist to read
322 * @param sharep Sharing status ("public", "private" or "shared")
323 * @return 0 on success, non-0 on error
325 int disorder_playlist_get_share(disorder_client *c, const char *playlist, char **sharep);
327 /** @brief Lock a playlist
329 * Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.
332 * @param playlist Playlist to delete
333 * @return 0 on success, non-0 on error
335 int disorder_playlist_lock(disorder_client *c, const char *playlist);
337 /** @brief Set the contents of a playlist
339 * Requires the 'play' right and permission to modify the playlist, which must be locked.
342 * @param playlist Playlist to modify
343 * @param tracks New list of tracks for playlist
344 * @param ntracks Length of tracks
345 * @return 0 on success, non-0 on error
347 int disorder_playlist_set(disorder_client *c, const char *playlist, char **tracks, int ntracks);
349 /** @brief Set a playlist's sharing status
351 * Requires the 'play' right and permission to modify the playlist.
354 * @param playlist Playlist to modify
355 * @param share New sharing status ("public", "private" or "shared")
356 * @return 0 on success, non-0 on error
358 int disorder_playlist_set_share(disorder_client *c, const char *playlist, const char *share);
360 /** @brief Unlock the locked playlist playlist
362 * The playlist to unlock is implicit in the connection.
365 * @return 0 on success, non-0 on error
367 int disorder_playlist_unlock(disorder_client *c);
369 /** @brief List playlists
371 * Requires the 'read' right. Only playlists that you have permission to read are returned.
374 * @param playlistsp Playlist names
375 * @param nplaylistsp Number of elements in playlistsp
376 * @return 0 on success, non-0 on error
378 int disorder_playlists(disorder_client *c, char ***playlistsp, int *nplaylistsp);
380 /** @brief Get all the preferences for a track
385 * @param track Track name
386 * @param prefsp Track preferences
387 * @return 0 on success, non-0 on error
389 int disorder_prefs(disorder_client *c, const char *track, struct kvp **prefsp);
391 /** @brief List the queue
396 * @param queuep Current queue contents
397 * @return 0 on success, non-0 on error
399 int disorder_queue(disorder_client *c, struct queue_entry **queuep);
401 /** @brief Disable random play
403 * Requires the 'global prefs' right.
406 * @return 0 on success, non-0 on error
408 int disorder_random_disable(disorder_client *c);
410 /** @brief Enable random play
412 * Requires the 'global prefs' right.
415 * @return 0 on success, non-0 on error
417 int disorder_random_enable(disorder_client *c);
419 /** @brief Detect whether random play is enabled
421 * Random play counts as enabled even if play is disabled.
424 * @param enabledp 1 if random play is enabled and 0 otherwise
425 * @return 0 on success, non-0 on error
427 int disorder_random_enabled(disorder_client *c, int *enabledp);
429 /** @brief List recently played tracks
434 * @param recentp Recently played tracks
435 * @return 0 on success, non-0 on error
437 int disorder_recent(disorder_client *c, struct queue_entry **recentp);
439 /** @brief Re-read configuraiton file.
441 * Requires the 'admin' right.
444 * @return 0 on success, non-0 on error
446 int disorder_reconfigure(disorder_client *c);
448 /** @brief Register a new user
450 * Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.
453 * @param username Requested new username
454 * @param password Requested initial password
455 * @param email New user's email address
456 * @param confirmationp Confirmation string
457 * @return 0 on success, non-0 on error
459 int disorder_register(disorder_client *c, const char *username, const char *password, const char *email, char **confirmationp);
461 /** @brief Send a password reminder.
463 * If the user has no valid email address, or no password, or a reminder has been sent too recently, then no reminder will be sent.
466 * @param username User to remind
467 * @return 0 on success, non-0 on error
469 int disorder_reminder(disorder_client *c, const char *username);
471 /** @brief Remove a track form the queue.
473 * Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.
477 * @return 0 on success, non-0 on error
479 int disorder_remove(disorder_client *c, const char *id);
481 /** @brief Rescan all collections for new or obsolete tracks.
483 * Requires the 'rescan' right.
486 * @return 0 on success, non-0 on error
488 int disorder_rescan(disorder_client *c);
490 /** @brief Resolve a track name
492 * Converts aliases to non-alias track names
495 * @param track Track name (might be an alias)
496 * @param resolvedp Resolve track name (definitely not an alias)
497 * @return 0 on success, non-0 on error
499 int disorder_resolve(disorder_client *c, const char *track, char **resolvedp);
501 /** @brief Resume the currently playing track
503 * Requires the 'pause' right.
506 * @return 0 on success, non-0 on error
508 int disorder_resume(disorder_client *c);
510 /** @brief Revoke a cookie.
512 * It will not subsequently be possible to log in with the cookie.
515 * @return 0 on success, non-0 on error
517 int disorder_revoke(disorder_client *c);
519 /** @brief Terminate the playing track.
521 * Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.
524 * @param id Track ID (optional)
525 * @return 0 on success, non-0 on error
527 int disorder_scratch(disorder_client *c, const char *id);
529 /** @brief Delete a scheduled event.
531 * Users can always delete their own scheduled events; with the admin right you can delete any event.
534 * @param event ID of event to delete
535 * @return 0 on success, non-0 on error
537 int disorder_schedule_del(disorder_client *c, const char *event);
539 /** @brief Get the details of scheduled event
545 * @param actiondatap Details of event
546 * @return 0 on success, non-0 on error
548 int disorder_schedule_get(disorder_client *c, const char *id, struct kvp **actiondatap);
550 /** @brief List scheduled events
552 * This just lists IDs. Use 'schedule-get' to retrieve more detail
555 * @param idsp List of event IDs
556 * @param nidsp Number of elements in idsp
557 * @return 0 on success, non-0 on error
559 int disorder_schedule_list(disorder_client *c, char ***idsp, int *nidsp);
561 /** @brief Search for tracks
563 * Terms are either keywords or tags formatted as 'tag:TAG-NAME'.
566 * @param terms List of search terms
567 * @param tracksp List of matching tracks
568 * @param ntracksp Number of elements in tracksp
569 * @return 0 on success, non-0 on error
571 int disorder_search(disorder_client *c, const char *terms, char ***tracksp, int *ntracksp);
573 /** @brief Set a track preference
575 * Requires the 'prefs' right.
578 * @param track Track name
579 * @param pref Preference name
580 * @param value New value
581 * @return 0 on success, non-0 on error
583 int disorder_set(disorder_client *c, const char *track, const char *pref, const char *value);
585 /** @brief Set a global preference
587 * Requires the 'global prefs' right.
590 * @param pref Preference name
591 * @param value New value
592 * @return 0 on success, non-0 on error
594 int disorder_set_global(disorder_client *c, const char *pref, const char *value);
596 /** @brief Request server shutdown
598 * Requires the 'admin' right.
601 * @return 0 on success, non-0 on error
603 int disorder_shutdown(disorder_client *c);
605 /** @brief Get server statistics
607 * The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line..
610 * @param statsp List of server information strings.
611 * @param nstatsp Number of elements in statsp
612 * @return 0 on success, non-0 on error
614 int disorder_stats(disorder_client *c, char ***statsp, int *nstatsp);
616 /** @brief Get a list of known tags
618 * Only tags which apply to at least one track are returned.
621 * @param tagsp List of tags
622 * @param ntagsp Number of elements in tagsp
623 * @return 0 on success, non-0 on error
625 int disorder_tags(disorder_client *c, char ***tagsp, int *ntagsp);
627 /** @brief Unset a track preference
629 * Requires the 'prefs' right.
632 * @param track Track name
633 * @param pref Preference name
634 * @return 0 on success, non-0 on error
636 int disorder_unset(disorder_client *c, const char *track, const char *pref);
638 /** @brief Set a global preference
640 * Requires the 'global prefs' right.
643 * @param pref Preference name
644 * @return 0 on success, non-0 on error
646 int disorder_unset_global(disorder_client *c, const char *pref);
648 /** @brief Get a user property.
650 * If the user does not exist an error is returned, if the user exists but the property does not then a null value is returned.
653 * @param username User to read
654 * @param property Property to read
655 * @param valuep Value of property
656 * @return 0 on success, non-0 on error
658 int disorder_userinfo(disorder_client *c, const char *username, const char *property, char **valuep);
660 /** @brief Get a list of users
665 * @param usersp List of users
666 * @param nusersp Number of elements in usersp
667 * @return 0 on success, non-0 on error
669 int disorder_users(disorder_client *c, char ***usersp, int *nusersp);
671 /** @brief Get the server version
676 * @param versionp Server version string
677 * @return 0 on success, non-0 on error
679 int disorder_version(disorder_client *c, char **versionp);