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.
60 * @param confirmation Confirmation string
61 * @return 0 on success, non-0 on error
63 int disorder_confirm(disorder_client *c, const char *confirmation);
64 /** @brief Log in with a cookie
66 * The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.
68 * @param cookie Cookie string
69 * @return 0 on success, non-0 on error
71 int disorder_cookie(disorder_client *c, const char *cookie);
72 /** @brief Delete user
74 * Requires the 'admin' right.
77 * @param user User to delete
78 * @return 0 on success, non-0 on error
80 int disorder_deluser(disorder_client *c, const char *user);
82 /** @brief List directories in a directory
87 * @param dir Directory to list (optional)
88 * @param re Regexp that results must match (optional)
89 * @param filesp List of matching directories
90 * @param nfilesp Number of elements in filesp
91 * @return 0 on success, non-0 on error
93 int disorder_dirs(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
95 /** @brief Disable play
97 * Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.
100 * @return 0 on success, non-0 on error
102 int disorder_disable(disorder_client *c);
104 /** @brief Set a user property
106 * With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
109 * @param username User to modify
110 * @param property Property name
111 * @param value New property value
112 * @return 0 on success, non-0 on error
114 int disorder_edituser(disorder_client *c, const char *username, const char *property, const char *value);
116 /** @brief Enable play
118 * Requires the 'global prefs' right.
121 * @return 0 on success, non-0 on error
123 int disorder_enable(disorder_client *c);
125 /** @brief Detect whether play is enabled
130 * @param enabledp 1 if play is enabled and 0 otherwise
131 * @return 0 on success, non-0 on error
133 int disorder_enabled(disorder_client *c, int *enabledp);
135 /** @brief Test whether a track exists
140 * @param track Track name
141 * @param existsp 1 if the track exists and 0 otherwise
142 * @return 0 on success, non-0 on error
144 int disorder_exists(disorder_client *c, const char *track, int *existsp);
146 /** @brief List files in a directory
151 * @param dir Directory to list (optional)
152 * @param re Regexp that results must match (optional)
153 * @param filesp List of matching files
154 * @param nfilesp Number of elements in filesp
155 * @return 0 on success, non-0 on error
157 int disorder_files(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
159 /** @brief Get a track preference
161 * 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.
164 * @param track Track name
165 * @param pref Preference name
166 * @param valuep Preference value
167 * @return 0 on success, non-0 on error
169 int disorder_get(disorder_client *c, const char *track, const char *pref, char **valuep);
171 /** @brief Get a global preference
173 * If the preference does exist not then a null value is returned.
176 * @param pref Global preference name
177 * @param valuep Preference value
178 * @return 0 on success, non-0 on error
180 int disorder_get_global(disorder_client *c, const char *pref, char **valuep);
182 /** @brief Get a track's length
184 * If the track does not exist an error is returned.
187 * @param track Track name
188 * @param lengthp Track length in seconds
189 * @return 0 on success, non-0 on error
191 int disorder_length(disorder_client *c, const char *track, long *lengthp);
193 /** @brief Create a login cookie for this user
195 * The cookie may be redeemed via the 'cookie' command
198 * @param cookiep Newly created cookie
199 * @return 0 on success, non-0 on error
201 int disorder_make_cookie(disorder_client *c, char **cookiep);
203 /** @brief Do nothing
205 * Used as a keepalive. No authentication required.
208 * @return 0 on success, non-0 on error
210 int disorder_nop(disorder_client *c);
212 /** @brief Get a track name part
214 * If the name part cannot be constructed an empty string is returned.
217 * @param track Track name
218 * @param context Context ("sort" or "display")
219 * @param part Name part ("artist", "album" or "title")
220 * @param partp Value of name part
221 * @return 0 on success, non-0 on error
223 int disorder_part(disorder_client *c, const char *track, const char *context, const char *part, char **partp);
225 /** @brief Pause the currently playing track
227 * Requires the 'pause' right.
230 * @return 0 on success, non-0 on error
232 int disorder_pause(disorder_client *c);
234 /** @brief Play a track
236 * Requires the 'play' right.
239 * @param track Track to play
240 * @param idp Queue ID of new track
241 * @return 0 on success, non-0 on error
243 int disorder_play(disorder_client *c, const char *track, char **idp);
245 /** @brief Delete a playlist
247 * Requires the 'play' right and permission to modify the playlist.
250 * @param playlist Playlist to delete
251 * @return 0 on success, non-0 on error
253 int disorder_playlist_delete(disorder_client *c, const char *playlist);
255 /** @brief List the contents of a playlist
257 * Requires the 'read' right and oermission to read the playlist.
260 * @param playlist Playlist name
261 * @param tracksp List of tracks in playlist
262 * @param ntracksp Number of elements in tracksp
263 * @return 0 on success, non-0 on error
265 int disorder_playlist_get(disorder_client *c, const char *playlist, char ***tracksp, int *ntracksp);
267 /** @brief Get a playlist's sharing status
269 * Requires the 'read' right and permission to read the playlist.
272 * @param playlist Playlist to read
273 * @param sharep Sharing status ("public", "private" or "shared")
274 * @return 0 on success, non-0 on error
276 int disorder_playlist_get_share(disorder_client *c, const char *playlist, char **sharep);
278 /** @brief Lock a playlist
280 * Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.
283 * @param playlist Playlist to delete
284 * @return 0 on success, non-0 on error
286 int disorder_playlist_lock(disorder_client *c, const char *playlist);
288 /** @brief Set the contents of a playlist
290 * Requires the 'play' right and permission to modify the playlist, which must be locked.
293 * @param playlist Playlist to modify
294 * @param tracks New list of tracks for playlist
295 * @param ntracks Length of tracks
296 * @return 0 on success, non-0 on error
298 int disorder_playlist_set(disorder_client *c, const char *playlist, char **tracks, int ntracks);
300 /** @brief Set a playlist's sharing status
302 * Requires the 'play' right and permission to modify the playlist.
305 * @param playlist Playlist to modify
306 * @param share New sharing status ("public", "private" or "shared")
307 * @return 0 on success, non-0 on error
309 int disorder_playlist_set_share(disorder_client *c, const char *playlist, const char *share);
311 /** @brief Unlock the locked playlist playlist
313 * The playlist to unlock is implicit in the connection.
316 * @return 0 on success, non-0 on error
318 int disorder_playlist_unlock(disorder_client *c);
320 /** @brief List playlists
322 * Requires the 'read' right. Only playlists that you have permission to read are returned.
325 * @param playlistsp Playlist names
326 * @param nplaylistsp Number of elements in playlistsp
327 * @return 0 on success, non-0 on error
329 int disorder_playlists(disorder_client *c, char ***playlistsp, int *nplaylistsp);
331 /** @brief List the queue
336 * @param queuep Current queue contents
337 * @return 0 on success, non-0 on error
339 int disorder_queue(disorder_client *c, struct queue_entry **queuep);
341 /** @brief Disable random play
343 * Requires the 'global prefs' right.
346 * @return 0 on success, non-0 on error
348 int disorder_random_disable(disorder_client *c);
350 /** @brief Enable random play
352 * Requires the 'global prefs' right.
355 * @return 0 on success, non-0 on error
357 int disorder_random_enable(disorder_client *c);
359 /** @brief Detect whether random play is enabled
361 * Random play counts as enabled even if play is disabled.
364 * @param enabledp 1 if random play is enabled and 0 otherwise
365 * @return 0 on success, non-0 on error
367 int disorder_random_enabled(disorder_client *c, int *enabledp);
369 /** @brief List recently played tracks
374 * @param recentp Recently played tracks
375 * @return 0 on success, non-0 on error
377 int disorder_recent(disorder_client *c, struct queue_entry **recentp);
379 /** @brief Re-read configuraiton file.
381 * Requires the 'admin' right.
384 * @return 0 on success, non-0 on error
386 int disorder_reconfigure(disorder_client *c);
388 /** @brief Register a new user
390 * Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.
393 * @param username Requested new username
394 * @param password Requested initial password
395 * @param email New user's email address
396 * @param confirmationp Confirmation string
397 * @return 0 on success, non-0 on error
399 int disorder_register(disorder_client *c, const char *username, const char *password, const char *email, char **confirmationp);
401 /** @brief Send a password reminder.
403 * 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.
406 * @param username User to remind
407 * @return 0 on success, non-0 on error
409 int disorder_reminder(disorder_client *c, const char *username);
411 /** @brief Remove a track form the queue.
413 * Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.
417 * @return 0 on success, non-0 on error
419 int disorder_remove(disorder_client *c, const char *id);
421 /** @brief Rescan all collections for new or obsolete tracks.
423 * Requires the 'rescan' right.
426 * @return 0 on success, non-0 on error
428 int disorder_rescan(disorder_client *c);
430 /** @brief Resolve a track name
432 * Converts aliases to non-alias track names
435 * @param track Track name (might be an alias)
436 * @param resolvedp Resolve track name (definitely not an alias)
437 * @return 0 on success, non-0 on error
439 int disorder_resolve(disorder_client *c, const char *track, char **resolvedp);
441 /** @brief Resume the currently playing track
443 * Requires the 'pause' right.
446 * @return 0 on success, non-0 on error
448 int disorder_resume(disorder_client *c);
450 /** @brief Revoke a cookie.
452 * It will not subsequently be possible to log in with the cookie.
455 * @return 0 on success, non-0 on error
457 int disorder_revoke(disorder_client *c);
459 /** @brief Terminate the playing track.
461 * Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.
464 * @param id Track ID (optional)
465 * @return 0 on success, non-0 on error
467 int disorder_scratch(disorder_client *c, const char *id);
469 /** @brief Delete a scheduled event.
471 * Users can always delete their own scheduled events; with the admin right you can delete any event.
474 * @param event ID of event to delete
475 * @return 0 on success, non-0 on error
477 int disorder_schedule_del(disorder_client *c, const char *event);
479 /** @brief List scheduled events
481 * This just lists IDs. Use 'schedule-get' to retrieve more detail
484 * @param idsp List of event IDs
485 * @param nidsp Number of elements in idsp
486 * @return 0 on success, non-0 on error
488 int disorder_schedule_list(disorder_client *c, char ***idsp, int *nidsp);
490 /** @brief Search for tracks
492 * Terms are either keywords or tags formatted as 'tag:TAG-NAME'.
495 * @param terms List of search terms
496 * @param tracksp List of matching tracks
497 * @param ntracksp Number of elements in tracksp
498 * @return 0 on success, non-0 on error
500 int disorder_search(disorder_client *c, const char *terms, char ***tracksp, int *ntracksp);
502 /** @brief Set a track preference
504 * Requires the 'prefs' right.
507 * @param track Track name
508 * @param pref Preference name
509 * @param value New value
510 * @return 0 on success, non-0 on error
512 int disorder_set(disorder_client *c, const char *track, const char *pref, const char *value);
514 /** @brief Set a global preference
516 * Requires the 'global prefs' right.
519 * @param pref Preference name
520 * @param value New value
521 * @return 0 on success, non-0 on error
523 int disorder_set_global(disorder_client *c, const char *pref, const char *value);
525 /** @brief Request server shutdown
527 * Requires the 'admin' right.
530 * @return 0 on success, non-0 on error
532 int disorder_shutdown(disorder_client *c);
534 /** @brief Get server statistics
536 * The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line..
539 * @param statsp List of server information strings.
540 * @param nstatsp Number of elements in statsp
541 * @return 0 on success, non-0 on error
543 int disorder_stats(disorder_client *c, char ***statsp, int *nstatsp);
545 /** @brief Get a list of known tags
547 * Only tags which apply to at least one track are returned.
550 * @param tagsp List of tags
551 * @param ntagsp Number of elements in tagsp
552 * @return 0 on success, non-0 on error
554 int disorder_tags(disorder_client *c, char ***tagsp, int *ntagsp);
556 /** @brief Unset a track preference
558 * Requires the 'prefs' right.
561 * @param track Track name
562 * @param pref Preference name
563 * @return 0 on success, non-0 on error
565 int disorder_unset(disorder_client *c, const char *track, const char *pref);
567 /** @brief Set a global preference
569 * Requires the 'global prefs' right.
572 * @param pref Preference name
573 * @return 0 on success, non-0 on error
575 int disorder_unset_global(disorder_client *c, const char *pref);
577 /** @brief Get a user property.
579 * 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.
582 * @param username User to read
583 * @param property Property to read
584 * @param valuep Value of property
585 * @return 0 on success, non-0 on error
587 int disorder_userinfo(disorder_client *c, const char *username, const char *property, char **valuep);
589 /** @brief Get a list of users
594 * @param usersp List of users
595 * @param nusersp Number of elements in usersp
596 * @return 0 on success, non-0 on error
598 int disorder_users(disorder_client *c, char ***usersp, int *nusersp);
600 /** @brief Get the server version
605 * @param versionp Server version string
606 * @return 0 on success, non-0 on error
608 int disorder_version(disorder_client *c, char **versionp);