2 * Automatically generated file, see scripts/protocol
7 * This file is part of DisOrder.
8 * Copyright (C) 2010-11 Richard Kettlewell
10 * This program is free software: you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation, either version 3 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program. If not, see <http://www.gnu.org/licenses/>.
23 #ifndef CLIENT_STUBS_H
24 #define CLIENT_STUBS_H
25 /** @file lib/client-stubs.h
26 * @brief Generated client API
28 * Don't include this file directly - use @ref lib/client.h instead.
31 /** @brief Adopt a track
33 * Makes the calling user owner of a randomly picked track.
37 * @return 0 on success, non-0 on error
39 int disorder_adopt(disorder_client *c, const char *id);
41 /** @brief Create a user
43 * Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.
46 * @param user New username
47 * @param password Initial password
48 * @param rights Initial rights (optional)
49 * @return 0 on success, non-0 on error
51 int disorder_adduser(disorder_client *c, const char *user, const char *password, const char *rights);
53 /** @brief List files and directories in a directory
55 * See 'files' and 'dirs' for more specific lists.
58 * @param dir Directory to list (optional)
59 * @param re Regexp that results must match (optional)
60 * @param filesp List of matching files and directories
61 * @param nfilesp Number of elements in filesp
62 * @return 0 on success, non-0 on error
64 int disorder_allfiles(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
66 /** @brief Confirm registration
68 * The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are.
71 * @param confirmation Confirmation string
72 * @return 0 on success, non-0 on error
74 int disorder_confirm(disorder_client *c, const char *confirmation);
76 /** @brief Log in with a cookie
78 * The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.
81 * @param cookie Cookie string
82 * @return 0 on success, non-0 on error
84 int disorder_cookie(disorder_client *c, const char *cookie);
86 /** @brief Delete user
88 * Requires the 'admin' right.
91 * @param user User to delete
92 * @return 0 on success, non-0 on error
94 int disorder_deluser(disorder_client *c, const char *user);
96 /** @brief List directories in a directory
101 * @param dir Directory to list (optional)
102 * @param re Regexp that results must match (optional)
103 * @param filesp List of matching directories
104 * @param nfilesp Number of elements in filesp
105 * @return 0 on success, non-0 on error
107 int disorder_dirs(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
109 /** @brief Disable play
111 * Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.
114 * @return 0 on success, non-0 on error
116 int disorder_disable(disorder_client *c);
118 /** @brief Set a user property
120 * With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
123 * @param username User to modify
124 * @param property Property name
125 * @param value New property value
126 * @return 0 on success, non-0 on error
128 int disorder_edituser(disorder_client *c, const char *username, const char *property, const char *value);
130 /** @brief Enable play
132 * Requires the 'global prefs' right.
135 * @return 0 on success, non-0 on error
137 int disorder_enable(disorder_client *c);
139 /** @brief Detect whether play is enabled
144 * @param enabledp 1 if play is enabled and 0 otherwise
145 * @return 0 on success, non-0 on error
147 int disorder_enabled(disorder_client *c, int *enabledp);
149 /** @brief Test whether a track exists
154 * @param track Track name
155 * @param existsp 1 if the track exists and 0 otherwise
156 * @return 0 on success, non-0 on error
158 int disorder_exists(disorder_client *c, const char *track, int *existsp);
160 /** @brief List files in a directory
165 * @param dir Directory to list (optional)
166 * @param re Regexp that results must match (optional)
167 * @param filesp List of matching files
168 * @param nfilesp Number of elements in filesp
169 * @return 0 on success, non-0 on error
171 int disorder_files(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
173 /** @brief Get a track preference
175 * 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.
178 * @param track Track name
179 * @param pref Preference name
180 * @param valuep Preference value
181 * @return 0 on success, non-0 on error
183 int disorder_get(disorder_client *c, const char *track, const char *pref, char **valuep);
185 /** @brief Get a global preference
187 * If the preference does exist not then a null value is returned.
190 * @param pref Global preference name
191 * @param valuep Preference value
192 * @return 0 on success, non-0 on error
194 int disorder_get_global(disorder_client *c, const char *pref, char **valuep);
196 /** @brief Get a track's length
198 * If the track does not exist an error is returned.
201 * @param track Track name
202 * @param lengthp Track length in seconds
203 * @return 0 on success, non-0 on error
205 int disorder_length(disorder_client *c, const char *track, long *lengthp);
207 /** @brief Create a login cookie for this user
209 * The cookie may be redeemed via the 'cookie' command
212 * @param cookiep Newly created cookie
213 * @return 0 on success, non-0 on error
215 int disorder_make_cookie(disorder_client *c, char **cookiep);
217 /** @brief Move a track
219 * Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.
222 * @param track Track ID or name
223 * @param delta How far to move the track towards the head of the queue
224 * @return 0 on success, non-0 on error
226 int disorder_move(disorder_client *c, const char *track, long delta);
228 /** @brief Move multiple tracks
230 * Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.
233 * @param target Move after this track, or to head if ""
234 * @param ids List of tracks to move by ID
235 * @param nids Length of ids
236 * @return 0 on success, non-0 on error
238 int disorder_moveafter(disorder_client *c, const char *target, char **ids, int nids);
240 /** @brief List recently added tracks
245 * @param max Maximum tracks to fetch, or 0 for all available
246 * @param tracksp Recently added tracks
247 * @param ntracksp Number of elements in tracksp
248 * @return 0 on success, non-0 on error
250 int disorder_new_tracks(disorder_client *c, long max, char ***tracksp, int *ntracksp);
252 /** @brief Do nothing
254 * Used as a keepalive. No authentication required.
257 * @return 0 on success, non-0 on error
259 int disorder_nop(disorder_client *c);
261 /** @brief Get a track name part
263 * If the name part cannot be constructed an empty string is returned.
266 * @param track Track name
267 * @param context Context ("sort" or "display")
268 * @param part Name part ("artist", "album" or "title")
269 * @param partp Value of name part
270 * @return 0 on success, non-0 on error
272 int disorder_part(disorder_client *c, const char *track, const char *context, const char *part, char **partp);
274 /** @brief Pause the currently playing track
276 * Requires the 'pause' right.
279 * @return 0 on success, non-0 on error
281 int disorder_pause(disorder_client *c);
283 /** @brief Play a track
285 * Requires the 'play' right.
288 * @param track Track to play
289 * @param idp Queue ID of new track
290 * @return 0 on success, non-0 on error
292 int disorder_play(disorder_client *c, const char *track, char **idp);
294 /** @brief Play multiple tracks
296 * Requires the 'play' right.
299 * @param target Insert into queue after this track, or at head if ""
300 * @param tracks List of track names to play
301 * @param ntracks Length of tracks
302 * @return 0 on success, non-0 on error
304 int disorder_playafter(disorder_client *c, const char *target, char **tracks, int ntracks);
306 /** @brief Retrieve the playing track
311 * @param playingp Details of the playing track
312 * @return 0 on success, non-0 on error
314 int disorder_playing(disorder_client *c, struct queue_entry **playingp);
316 /** @brief Delete a playlist
318 * Requires the 'play' right and permission to modify the playlist.
321 * @param playlist Playlist to delete
322 * @return 0 on success, non-0 on error
324 int disorder_playlist_delete(disorder_client *c, const char *playlist);
326 /** @brief List the contents of a playlist
328 * Requires the 'read' right and oermission to read the playlist.
331 * @param playlist Playlist name
332 * @param tracksp List of tracks in playlist
333 * @param ntracksp Number of elements in tracksp
334 * @return 0 on success, non-0 on error
336 int disorder_playlist_get(disorder_client *c, const char *playlist, char ***tracksp, int *ntracksp);
338 /** @brief Get a playlist's sharing status
340 * Requires the 'read' right and permission to read the playlist.
343 * @param playlist Playlist to read
344 * @param sharep Sharing status ("public", "private" or "shared")
345 * @return 0 on success, non-0 on error
347 int disorder_playlist_get_share(disorder_client *c, const char *playlist, char **sharep);
349 /** @brief Lock a playlist
351 * Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.
354 * @param playlist Playlist to delete
355 * @return 0 on success, non-0 on error
357 int disorder_playlist_lock(disorder_client *c, const char *playlist);
359 /** @brief Set the contents of a playlist
361 * Requires the 'play' right and permission to modify the playlist, which must be locked.
364 * @param playlist Playlist to modify
365 * @param tracks New list of tracks for playlist
366 * @param ntracks Length of tracks
367 * @return 0 on success, non-0 on error
369 int disorder_playlist_set(disorder_client *c, const char *playlist, char **tracks, int ntracks);
371 /** @brief Set a playlist's sharing status
373 * Requires the 'play' right and permission to modify the playlist.
376 * @param playlist Playlist to modify
377 * @param share New sharing status ("public", "private" or "shared")
378 * @return 0 on success, non-0 on error
380 int disorder_playlist_set_share(disorder_client *c, const char *playlist, const char *share);
382 /** @brief Unlock the locked playlist playlist
384 * The playlist to unlock is implicit in the connection.
387 * @return 0 on success, non-0 on error
389 int disorder_playlist_unlock(disorder_client *c);
391 /** @brief List playlists
393 * Requires the 'read' right. Only playlists that you have permission to read are returned.
396 * @param playlistsp Playlist names
397 * @param nplaylistsp Number of elements in playlistsp
398 * @return 0 on success, non-0 on error
400 int disorder_playlists(disorder_client *c, char ***playlistsp, int *nplaylistsp);
402 /** @brief Get all the preferences for a track
407 * @param track Track name
408 * @param prefsp Track preferences
409 * @return 0 on success, non-0 on error
411 int disorder_prefs(disorder_client *c, const char *track, struct kvp **prefsp);
413 /** @brief List the queue
418 * @param queuep Current queue contents
419 * @return 0 on success, non-0 on error
421 int disorder_queue(disorder_client *c, struct queue_entry **queuep);
423 /** @brief Disable random play
425 * Requires the 'global prefs' right.
428 * @return 0 on success, non-0 on error
430 int disorder_random_disable(disorder_client *c);
432 /** @brief Enable random play
434 * Requires the 'global prefs' right.
437 * @return 0 on success, non-0 on error
439 int disorder_random_enable(disorder_client *c);
441 /** @brief Detect whether random play is enabled
443 * Random play counts as enabled even if play is disabled.
446 * @param enabledp 1 if random play is enabled and 0 otherwise
447 * @return 0 on success, non-0 on error
449 int disorder_random_enabled(disorder_client *c, int *enabledp);
451 /** @brief List recently played tracks
456 * @param recentp Recently played tracks
457 * @return 0 on success, non-0 on error
459 int disorder_recent(disorder_client *c, struct queue_entry **recentp);
461 /** @brief Re-read configuraiton file.
463 * Requires the 'admin' right.
466 * @return 0 on success, non-0 on error
468 int disorder_reconfigure(disorder_client *c);
470 /** @brief Register a new user
472 * Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.
475 * @param username Requested new username
476 * @param password Requested initial password
477 * @param email New user's email address
478 * @param confirmationp Confirmation string
479 * @return 0 on success, non-0 on error
481 int disorder_register(disorder_client *c, const char *username, const char *password, const char *email, char **confirmationp);
483 /** @brief Send a password reminder.
485 * 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.
488 * @param username User to remind
489 * @return 0 on success, non-0 on error
491 int disorder_reminder(disorder_client *c, const char *username);
493 /** @brief Remove a track form the queue.
495 * Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.
499 * @return 0 on success, non-0 on error
501 int disorder_remove(disorder_client *c, const char *id);
503 /** @brief Rescan all collections for new or obsolete tracks.
505 * Requires the 'rescan' right.
508 * @return 0 on success, non-0 on error
510 int disorder_rescan(disorder_client *c);
512 /** @brief Resolve a track name
514 * Converts aliases to non-alias track names
517 * @param track Track name (might be an alias)
518 * @param resolvedp Resolve track name (definitely not an alias)
519 * @return 0 on success, non-0 on error
521 int disorder_resolve(disorder_client *c, const char *track, char **resolvedp);
523 /** @brief Resume the currently playing track
525 * Requires the 'pause' right.
528 * @return 0 on success, non-0 on error
530 int disorder_resume(disorder_client *c);
532 /** @brief Revoke a cookie.
534 * It will not subsequently be possible to log in with the cookie.
537 * @return 0 on success, non-0 on error
539 int disorder_revoke(disorder_client *c);
541 /** @brief Get the server's RTP address information
546 * @param addressp Where to store hostname or address
547 * @param portp Where to store service name or port number
548 * @return 0 on success, non-0 on error
550 int disorder_rtp_address(disorder_client *c, char **addressp, char **portp);
552 /** @brief Cancel RTP stream
557 * @return 0 on success, non-0 on error
559 int disorder_rtp_cancel(disorder_client *c);
561 /** @brief Request a unicast RTP stream
566 * @param address Destination address
567 * @param port Destination port number
568 * @return 0 on success, non-0 on error
570 int disorder_rtp_request(disorder_client *c, const char *address, const char *port);
572 /** @brief Terminate the playing track.
574 * Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.
577 * @param id Track ID (optional)
578 * @return 0 on success, non-0 on error
580 int disorder_scratch(disorder_client *c, const char *id);
582 /** @brief Schedule a track to play in the future
587 * @param when When to play the track
588 * @param priority Event priority ("normal" or "junk")
589 * @param track Track to play
590 * @return 0 on success, non-0 on error
592 int disorder_schedule_add_play(disorder_client *c, time_t when, const char *priority, const char *track);
594 /** @brief Schedule a global setting to be changed in the future
599 * @param when When to change the setting
600 * @param priority Event priority ("normal" or "junk")
601 * @param pref Global preference to set
602 * @param value New value of global preference
603 * @return 0 on success, non-0 on error
605 int disorder_schedule_add_set_global(disorder_client *c, time_t when, const char *priority, const char *pref, const char *value);
607 /** @brief Schedule a global setting to be unset in the future
612 * @param when When to change the setting
613 * @param priority Event priority ("normal" or "junk")
614 * @param pref Global preference to set
615 * @return 0 on success, non-0 on error
617 int disorder_schedule_add_unset_global(disorder_client *c, time_t when, const char *priority, const char *pref);
619 /** @brief Delete a scheduled event.
621 * Users can always delete their own scheduled events; with the admin right you can delete any event.
624 * @param event ID of event to delete
625 * @return 0 on success, non-0 on error
627 int disorder_schedule_del(disorder_client *c, const char *event);
629 /** @brief Get the details of scheduled event
635 * @param actiondatap Details of event
636 * @return 0 on success, non-0 on error
638 int disorder_schedule_get(disorder_client *c, const char *id, struct kvp **actiondatap);
640 /** @brief List scheduled events
642 * This just lists IDs. Use 'schedule-get' to retrieve more detail
645 * @param idsp List of event IDs
646 * @param nidsp Number of elements in idsp
647 * @return 0 on success, non-0 on error
649 int disorder_schedule_list(disorder_client *c, char ***idsp, int *nidsp);
651 /** @brief Search for tracks
653 * Terms are either keywords or tags formatted as 'tag:TAG-NAME'.
656 * @param terms List of search terms
657 * @param tracksp List of matching tracks
658 * @param ntracksp Number of elements in tracksp
659 * @return 0 on success, non-0 on error
661 int disorder_search(disorder_client *c, const char *terms, char ***tracksp, int *ntracksp);
663 /** @brief Set a track preference
665 * Requires the 'prefs' right.
668 * @param track Track name
669 * @param pref Preference name
670 * @param value New value
671 * @return 0 on success, non-0 on error
673 int disorder_set(disorder_client *c, const char *track, const char *pref, const char *value);
675 /** @brief Set a global preference
677 * Requires the 'global prefs' right.
680 * @param pref Preference name
681 * @param value New value
682 * @return 0 on success, non-0 on error
684 int disorder_set_global(disorder_client *c, const char *pref, const char *value);
686 /** @brief Request server shutdown
688 * Requires the 'admin' right.
691 * @return 0 on success, non-0 on error
693 int disorder_shutdown(disorder_client *c);
695 /** @brief Get server statistics
697 * The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line.
700 * @param statsp List of server information strings.
701 * @param nstatsp Number of elements in statsp
702 * @return 0 on success, non-0 on error
704 int disorder_stats(disorder_client *c, char ***statsp, int *nstatsp);
706 /** @brief Get a list of known tags
708 * Only tags which apply to at least one track are returned.
711 * @param tagsp List of tags
712 * @param ntagsp Number of elements in tagsp
713 * @return 0 on success, non-0 on error
715 int disorder_tags(disorder_client *c, char ***tagsp, int *ntagsp);
717 /** @brief Unset a track preference
719 * Requires the 'prefs' right.
722 * @param track Track name
723 * @param pref Preference name
724 * @return 0 on success, non-0 on error
726 int disorder_unset(disorder_client *c, const char *track, const char *pref);
728 /** @brief Set a global preference
730 * Requires the 'global prefs' right.
733 * @param pref Preference name
734 * @return 0 on success, non-0 on error
736 int disorder_unset_global(disorder_client *c, const char *pref);
738 /** @brief Get a user property.
740 * 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.
743 * @param username User to read
744 * @param property Property to read
745 * @param valuep Value of property
746 * @return 0 on success, non-0 on error
748 int disorder_userinfo(disorder_client *c, const char *username, const char *property, char **valuep);
750 /** @brief Get a list of users
755 * @param usersp List of users
756 * @param nusersp Number of elements in usersp
757 * @return 0 on success, non-0 on error
759 int disorder_users(disorder_client *c, char ***usersp, int *nusersp);
761 /** @brief Get the server version
766 * @param versionp Server version string
767 * @return 0 on success, non-0 on error
769 int disorder_version(disorder_client *c, char **versionp);
771 /** @brief Set the volume
776 * @param left Left channel volume
777 * @param right Right channel volume
778 * @return 0 on success, non-0 on error
780 int disorder_set_volume(disorder_client *c, long left, long right);
782 /** @brief Get the volume
787 * @param leftp Left channel volume
788 * @param rightp Right channel volume
789 * @return 0 on success, non-0 on error
791 int disorder_get_volume(disorder_client *c, long *leftp, long *rightp);