*
* Makes the calling user owner of a randomly picked track.
*
+ * @param c Client
* @param id Track ID
* @return 0 on success, non-0 on error
*/
*
* Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.
*
+ * @param c Client
* @param user New username
* @param password Initial password
* @param rights Initial rights (optional)
*
* See 'files' and 'dirs' for more specific lists.
*
+ * @param c Client
* @param dir Directory to list (optional)
* @param re Regexp that results must match (optional)
* @param filesp List of matching files and directories
*
* Requires the 'admin' right.
*
+ * @param c Client
* @param user User to delete
* @return 0 on success, non-0 on error
*/
*
*
*
+ * @param c Client
* @param dir Directory to list (optional)
* @param re Regexp that results must match (optional)
* @param filesp List of matching directories
*
* Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_disable(disorder_client *c);
*
* With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
*
+ * @param c Client
* @param username User to modify
* @param property Property name
* @param value New property value
*
* Requires the 'global prefs' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_enable(disorder_client *c);
*
*
*
+ * @param c Client
* @param enabledp 1 if play is enabled and 0 otherwise
* @return 0 on success, non-0 on error
*/
*
*
*
+ * @param c Client
* @param track Track name
* @param existsp 1 if the track exists and 0 otherwise
* @return 0 on success, non-0 on error
*
*
*
+ * @param c Client
* @param dir Directory to list (optional)
* @param re Regexp that results must match (optional)
* @param filesp List of matching files
*
* 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.
*
+ * @param c Client
* @param track Track name
* @param pref Preference name
* @param valuep Preference value
*
* If the preference does exist not then a null value is returned.
*
+ * @param c Client
* @param pref Global preference name
* @param valuep Preference value
* @return 0 on success, non-0 on error
*
* If the track does not exist an error is returned.
*
+ * @param c Client
* @param track Track name
* @param lengthp Track length in seconds
* @return 0 on success, non-0 on error
*
* The cookie may be redeemed via the 'cookie' command
*
+ * @param c Client
* @param cookiep Newly created cookie
* @return 0 on success, non-0 on error
*/
*
* Used as a keepalive. No authentication required.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_nop(disorder_client *c);
*
* If the name part cannot be constructed an empty string is returned.
*
+ * @param c Client
* @param track Track name
* @param context Context ("sort" or "display")
* @param part Name part ("artist", "album" or "title")
*
* Requires the 'pause' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_pause(disorder_client *c);
*
* Requires the 'play' right.
*
+ * @param c Client
* @param track Track to play
* @param idp Queue ID of new track
* @return 0 on success, non-0 on error
*
* Requires the 'play' right and permission to modify the playlist.
*
+ * @param c Client
* @param playlist Playlist to delete
* @return 0 on success, non-0 on error
*/
*
* Requires the 'read' right and oermission to read the playlist.
*
+ * @param c Client
* @param playlist Playlist name
* @param tracksp List of tracks in playlist
* @param ntracksp Number of elements in tracksp
*
* Requires the 'read' right and permission to read the playlist.
*
+ * @param c Client
* @param playlist Playlist to read
* @param sharep Sharing status ("public", "private" or "shared")
* @return 0 on success, non-0 on error
*
* Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.
*
+ * @param c Client
* @param playlist Playlist to delete
* @return 0 on success, non-0 on error
*/
int disorder_playlist_lock(disorder_client *c, const char *playlist);
+/** @brief Set the contents of a playlist
+ *
+ * Requires the 'play' right and permission to modify the playlist, which must be locked.
+ *
+ * @param c Client
+ * @param playlist Playlist to modify
+ * @param tracks New list of tracks for playlist
+ * @param ntracks Length of tracks
+ * @return 0 on success, non-0 on error
+ */
+int disorder_playlist_set(disorder_client *c, const char *playlist, char **tracks, int ntracks);
+
/** @brief Set a playlist's sharing status
*
* Requires the 'play' right and permission to modify the playlist.
*
+ * @param c Client
* @param playlist Playlist to modify
* @param share New sharing status ("public", "private" or "shared")
* @return 0 on success, non-0 on error
*
* The playlist to unlock is implicit in the connection.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_playlist_unlock(disorder_client *c);
*
* Requires the 'read' right. Only playlists that you have permission to read are returned.
*
+ * @param c Client
* @param playlistsp Playlist names
* @param nplaylistsp Number of elements in playlistsp
* @return 0 on success, non-0 on error
*/
int disorder_playlists(disorder_client *c, char ***playlistsp, int *nplaylistsp);
+/** @brief List the queue
+ *
+ *
+ *
+ * @param c Client
+ * @param queuep Current queue contents
+ * @return 0 on success, non-0 on error
+ */
+int disorder_queue(disorder_client *c, struct queue_entry **queuep);
+
/** @brief Disable random play
*
* Requires the 'global prefs' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_random_disable(disorder_client *c);
*
* Requires the 'global prefs' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_random_enable(disorder_client *c);
*
* Random play counts as enabled even if play is disabled.
*
+ * @param c Client
* @param enabledp 1 if random play is enabled and 0 otherwise
* @return 0 on success, non-0 on error
*/
int disorder_random_enabled(disorder_client *c, int *enabledp);
+/** @brief List recently played tracks
+ *
+ *
+ *
+ * @param c Client
+ * @param recentp Recently played tracks
+ * @return 0 on success, non-0 on error
+ */
+int disorder_recent(disorder_client *c, struct queue_entry **recentp);
+
/** @brief Re-read configuraiton file.
*
* Requires the 'admin' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_reconfigure(disorder_client *c);
*
* Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.
*
+ * @param c Client
* @param username Requested new username
* @param password Requested initial password
* @param email New user's email address
*
* 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.
*
+ * @param c Client
* @param username User to remind
* @return 0 on success, non-0 on error
*/
*
* Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.
*
+ * @param c Client
* @param id Track ID
* @return 0 on success, non-0 on error
*/
*
* Requires the 'rescan' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_rescan(disorder_client *c);
*
* Converts aliases to non-alias track names
*
+ * @param c Client
* @param track Track name (might be an alias)
* @param resolvedp Resolve track name (definitely not an alias)
* @return 0 on success, non-0 on error
*
* Requires the 'pause' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_resume(disorder_client *c);
*
* It will not subsequently be possible to log in with the cookie.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_revoke(disorder_client *c);
*
* Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.
*
+ * @param c Client
* @param id Track ID (optional)
* @return 0 on success, non-0 on error
*/
*
* Users can always delete their own scheduled events; with the admin right you can delete any event.
*
+ * @param c Client
* @param event ID of event to delete
* @return 0 on success, non-0 on error
*/
*
* This just lists IDs. Use 'schedule-get' to retrieve more detail
*
+ * @param c Client
* @param idsp List of event IDs
* @param nidsp Number of elements in idsp
* @return 0 on success, non-0 on error
*
* Terms are either keywords or tags formatted as 'tag:TAG-NAME'.
*
+ * @param c Client
* @param terms List of search terms
* @param tracksp List of matching tracks
* @param ntracksp Number of elements in tracksp
*
* Requires the 'prefs' right.
*
+ * @param c Client
* @param track Track name
* @param pref Preference name
* @param value New value
*
* Requires the 'global prefs' right.
*
+ * @param c Client
* @param pref Preference name
* @param value New value
* @return 0 on success, non-0 on error
*
* Requires the 'admin' right.
*
+ * @param c Client
* @return 0 on success, non-0 on error
*/
int disorder_shutdown(disorder_client *c);
*
* The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line..
*
+ * @param c Client
* @param statsp List of server information strings.
* @param nstatsp Number of elements in statsp
* @return 0 on success, non-0 on error
*
* Only tags which apply to at least one track are returned.
*
+ * @param c Client
* @param tagsp List of tags
* @param ntagsp Number of elements in tagsp
* @return 0 on success, non-0 on error
*
* Requires the 'prefs' right.
*
+ * @param c Client
* @param track Track name
* @param pref Preference name
* @return 0 on success, non-0 on error
*
* Requires the 'global prefs' right.
*
+ * @param c Client
* @param pref Preference name
* @return 0 on success, non-0 on error
*/
*
* 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.
*
+ * @param c Client
* @param username User to read
* @param property Property to read
* @param valuep Value of property
*
*
*
+ * @param c Client
* @param usersp List of users
* @param nusersp Number of elements in usersp
* @return 0 on success, non-0 on error
*
*
*
+ * @param c Client
* @param versionp Server version string
* @return 0 on success, non-0 on error
*/
}
}
+/** @brief Marker for a command body */
+static const char disorder_body[1];
+
/** @brief Issue a command and parse a simple response
* @param c Client
* @param rp Where to store result, or NULL
* @param cmd Command
- * @param body Body or NULL
- * @param nbody Length of body or -1
* @param ap Arguments (UTF-8), terminated by (char *)0
* @return 0 on success, non-0 on error
*
* NB that the response will NOT be converted to the local encoding
* nor will quotes be stripped. See dequote().
*
- * If @p body is not NULL then the body is sent immediately after the
- * command. @p nbody should be the number of lines or @c -1 to count
- * them if @p body is NULL-terminated.
+ * Put @ref disorder_body in the argument list followed by a char **
+ * and int giving the body to follow the command. If the int is @c -1
+ * then the list is assumed to be NULL-terminated.
*
* Usually you would call this via one of the following interfaces:
* - disorder_simple()
- * - disorder_simple_body()
* - disorder_simple_list()
*/
static int disorder_simple_v(disorder_client *c,
char **rp,
const char *cmd,
- char **body, int nbody,
va_list ap) {
const char *arg;
struct dynstr d;
+ char **body = NULL;
+ int nbody = 0;
+ int has_body = 0;
if(!c->fpout) {
c->last = "not connected";
dynstr_init(&d);
dynstr_append_string(&d, cmd);
while((arg = va_arg(ap, const char *))) {
- dynstr_append(&d, ' ');
- dynstr_append_string(&d, quoteutf8(arg));
+ if(arg == disorder_body) {
+ body = va_arg(ap, char **);
+ nbody = va_arg(ap, int);
+ has_body = 1;
+ } else {
+ dynstr_append(&d, ' ');
+ dynstr_append_string(&d, quoteutf8(arg));
+ }
}
dynstr_append(&d, '\n');
dynstr_terminate(&d);
if(fputs(d.vec, c->fpout) < 0)
goto write_error;
xfree(d.vec);
- if(body) {
+ if(has_body) {
if(nbody < 0)
for(nbody = 0; body[nbody]; ++nbody)
;
int ret;
va_start(ap, cmd);
- ret = disorder_simple_v(c, rp, cmd, 0, 0, ap);
- va_end(ap);
- return ret;
-}
-
-/** @brief Issue a command with a body and parse a simple response
- * @param c Client
- * @param rp Where to store result, or NULL (UTF-8)
- * @param body Pointer to body
- * @param nbody Size of body
- * @param cmd Command
- * @return 0 on success, non-0 on error
- *
- * See disorder_simple().
- */
-static int disorder_simple_body(disorder_client *c,
- char **rp,
- char **body, int nbody,
- const char *cmd, ...) {
- va_list ap;
- int ret;
-
- va_start(ap, cmd);
- ret = disorder_simple_v(c, rp, cmd, body, nbody, ap);
+ ret = disorder_simple_v(c, rp, cmd, ap);
va_end(ap);
return ret;
}
return -1;
}
-/** @brief Get recently played tracks
- * @param c Client
- * @param qp Where to store track information
- * @return 0 on success, non-0 on error
- *
- * The last entry in the list is the most recently played track.
- */
-int disorder_recent(disorder_client *c, struct queue_entry **qp) {
- return disorder_somequeue(c, "recent", qp);
-}
-
-/** @brief Get queue
- * @param c Client
- * @param qp Where to store track information
- * @return 0 on success, non-0 on error
- *
- * The first entry in the list will be played next.
- */
-int disorder_queue(disorder_client *c, struct queue_entry **qp) {
- return disorder_somequeue(c, "queue", qp);
-}
-
/** @brief Read a dot-stuffed list
* @param c Client
* @param vecp Where to store list (UTF-8)
int ret;
va_start(ap, cmd);
- ret = disorder_simple_v(c, 0, cmd, 0, 0, ap);
+ ret = disorder_simple_v(c, 0, cmd, ap);
va_end(ap);
if(ret) return ret;
return readlist(c, vecp, nvecp);
return rc;
}
-/** @brief Set the contents of a playlst
- * @param c Client
- * @param playlist Playlist to modify
- * @param tracks List of tracks
- * @param ntracks Length of @p tracks (or -1 to count up to the first NULL)
- * @return 0 on success, non-0 on error
- */
-int disorder_playlist_set(disorder_client *c,
- const char *playlist,
- char **tracks,
- int ntracks) {
- return disorder_simple_body(c, 0, tracks, ntracks,
- "playlist-set", playlist, (char *)0);
-}
-
#include "client-stubs.c"
/*
return "const char *$name";
} elsif($type eq 'integer') {
return "long $name";
+ } elsif($type eq 'list') {
+ return ("char **$name",
+ "int n$name");
} else {
die "$0: unknown type '$type'\n";
}
} elsif($type eq 'list') {
return ("char ***${name}p",
"int *n${name}p");
+ } elsif($type eq 'queue') {
+ return ("struct queue_entry **${name}p");
} else {
die "$0: unknown type '$type'\n";
}
sub c_param_docs {
my $args = shift;
- return map(" * \@param $_->[1] $_->[2]\n", @$args);
+ my @d = ();
+ for my $arg (@$args) {
+ if($arg->[0] eq 'list') {
+ push(@d,
+ " * \@param $arg->[1] $arg->[2]\n",
+ " * \@param n$arg->[1] Length of $arg->[1]\n");
+ } else {
+ push(@d, " * \@param $arg->[1] $arg->[2]\n");
+ }
+ }
+ return @d;
}
sub c_return_docs {
} elsif($type eq 'list') {
return (" * \@param ${name}p $descr\n",
" * \@param n${name}p Number of elements in ${name}p\n");
+ } elsif($type eq 'queue') {
+ return (" * \@param ${name}p $descr\n");
} else {
die "$0: unknown return type '$type'\n";
}
# simple(CMD, SUMMARY, DETAIL,
# [[TYPE,NAME,DESCR], [TYPE,NAME,DESCR], ...],
-# [RETURN-TYPE, RETURN-NAME, RETURN_DESCR)
+# [RETURN-TYPE, RETURN-NAME, RETURN_DESCR])
sub simple {
my $cmd = shift;
my $summary = shift;
" *\n",
" * $detail\n",
" *\n",
+ " * \@param c Client\n",
c_param_docs($args),
c_return_docs($return),
" * \@return 0 on success, non-0 on error\n",
c_out_decl($return)),
") {\n");
if(!defined $return) {
- push(@c, " return disorder_simple(c, 0, \"$cmd\"",
- map(", $_->[1]", @$args),
- ", (char *)0);\n",
- );
+ my @cargs = ();
+ for my $arg (@$args) {
+ if($arg->[0] eq 'list') {
+ push(@cargs, "disorder_body", $arg->[1], "n$arg->[1]");
+ } else {
+ push(@cargs, $arg->[1]);
+ }
+ }
+ push(@c, " return disorder_simple(",
+ join(", ", "c", 0, "\"$cmd\"", @cargs, "(char *)0"),
+ ");\n");
} elsif($return->[0] eq 'string') {
push(@c, " return dequote(disorder_simple(c, $return->[1]p, \"$cmd\"",
map(", $_->[1]", @$args),
push(@c, " return disorder_simple_list(c, $return->[1]p, n$return->[1]p, \"$cmd\"",
map(", $_->[1]", @$args),
", (char *)0);\n");
+ } elsif($return->[0] eq 'queue') {
+ push(@c, " return disorder_somequeue(c, \"$cmd\", $return->[1]p);\n");
} else {
die "$0: unknown return type '$return->[0]' for '$cmd'\n";
}
"Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.",
[["string", "playlist", "Playlist to delete"]]);
+simple("playlist-set",
+ "Set the contents of a playlist",
+ "Requires the 'play' right and permission to modify the playlist, which must be locked.",
+ [["string", "playlist", "Playlist to modify"],
+ ["list", "tracks", "New list of tracks for playlist"]]);
+
simple("playlist-set-share",
"Set a playlist's sharing status",
"Requires the 'play' right and permission to modify the playlist.",
# TODO prefs
-# TODO queue
+simple("queue",
+ "List the queue",
+ "",
+ [],
+ ["queue", "queue", "Current queue contents"]);
simple("random-disable",
"Disable random play",
[],
["boolean", "enabled", "1 if random play is enabled and 0 otherwise"]);
-# TODO recent
+simple("recent",
+ "List recently played tracks",
+ "",
+ [],
+ ["queue", "recent", "Recently played tracks"]);
simple("reconfigure",
"Re-read configuraiton file.",
simple("revoke",
"Revoke a cookie.",
"It will not subsequently be possible to log in with the cookie.",
- []); # TODO fix docs!
+ []);
# TODO rtp-address
~mdw / disorder / commitdiff