#! /usr/bin/perl -w
#
# This file is part of DisOrder.
-# Copyright (C) 2010 Richard Kettlewell
+# Copyright (C) 2010-11 Richard Kettlewell
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
#
use strict;
+# This file contains the definition of the disorder protocol, plus
+# code to generates stubs for it in the various supported languages.
+#
+# At the time of writing it is a work in progress!
+
+#
+# Types:
+#
+# string A (Unicode) string.
+# integer An integer. Decimal on the wire.
+# boolean True or false. "yes" or "no" on the wire.
+# list In commands: a list of strings in the command.
+# In returns: a list of lines in the response.
+# pair-list In returns: a list of key-value pairs in a response body.
+# body In commands: a list of strings as a command body.
+# In returns: a list of strings as a response body.
+# queue In returns: a list of queue entries in a response body.
+# queue-one In returns: a queue entry in the response.
+#
+
# Variables and utilities -----------------------------------------------------
our @h = ();
our @c = ();
+# Write(PATH, LINES)
+#
+# Write array ref LINES to file PATH.
sub Write {
my $path = shift;
my $lines = shift;
(open(F, ">$path")
and print F @$lines
and close F)
- or die "$0: $path: $!\n";
+ or die "$0: $path: $!\n";
}
# Command classes -------------------------------------------------------------
-# simple(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],)
+# c_in_decl([TYPE, NAME])
#
-# Response is simply success/failure
-sub simple {
- my $cmd = shift;
- my $summary = shift;
- my $detail = shift;
- my $args = shift;
-
- my $cmdc = $cmd;
- $cmdc =~ s/-/_/g;
- # Synchronous C API
- push(@h, "/** \@brief $summary\n",
- " *\n",
- " * $detail\n",
- " *\n",
- map(" * \@param $_->[0] $_->[1]\n", @$args),
- " * \@return 0 on success, non-0 on error\n",
- " */\n",
- "int disorder_$cmdc(disorder_client *c",
- map(", const char *$_->[0]", @$args), ");\n",
- "\n");
- push(@c, "int disorder_$cmdc(disorder_client *c",
- map(", const char *$_->[0]", @$args), ") {\n",
- " return disorder_simple(c, 0, \"$cmd\"",
- map(", $_->[0]", @$args),
- ", (char *)0);\n",
- "}\n\n");
+# Return the C declaration for an input parameter of type TYPE with
+# name NAME.
+sub c_in_decl {
+ my $arg = shift;
+
+ my $type = $arg->[0];
+ my $name = $arg->[1];
+ if($type eq 'string') {
+ return "const char *$name";
+ } elsif($type eq 'integer') {
+ return "long $name";
+ } elsif($type eq 'list' or $type eq 'body') {
+ return ("char **$name",
+ "int n$name");
+ } else {
+ die "$0: c_in_decl: unknown type '$type'\n";
+ }
+}
- # Asynchronous C API
- # TODO
+# c_out_decl([TYPE, NAME])
+#
+# Return the C declaration for an output (reference) parameter of type
+# TYPE with name NAME.
+sub c_out_decl {
+ my $arg = shift;
+
+ return () unless defined $arg;
+ my $type = $arg->[0];
+ my $name = $arg->[1];
+ if($type eq 'string') {
+ return ("char **${name}p");
+ } elsif($type eq 'integer') {
+ return ("long *${name}p");
+ } elsif($type eq 'boolean') {
+ return ("int *${name}p");
+ } elsif($type eq 'list' or $type eq 'body') {
+ return ("char ***${name}p",
+ "int *n${name}p");
+ } elsif($type eq 'pair-list') {
+ return ("struct kvp **${name}p");
+ } elsif($type eq 'queue' or $type eq 'queue-one') {
+ return ("struct queue_entry **${name}p");
+ } elsif($type eq 'user') {
+ return ();
+ } else {
+ die "$0: c_out_decl: unknown type '$type'\n";
+ }
+}
- # Python API
- # TODO
+# c_param_docs([TYPE, NAME})
+#
+# Return the doc string for a C input parameter.
+sub c_param_docs {
+ my $args = shift;
+ my @d = ();
+ for my $arg (@$args) {
+ if($arg->[0] eq 'body' or $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;
+}
- # Java API
- # TODO
+# c_param_docs([TYPE, NAME})
+#
+# Return the doc string for a C output parameter.
+sub c_return_docs {
+ my $return = shift;
+ return () unless defined $return;
+ my $type = $return->[0];
+ my $name = $return->[1];
+ my $descr = $return->[2];
+ if($type eq 'string'
+ or $type eq 'integer'
+ or $type eq 'boolean') {
+ return (" * \@param ${name}p $descr\n");
+ } elsif($type eq 'list' or $type eq 'body') {
+ return (" * \@param ${name}p $descr\n",
+ " * \@param n${name}p Number of elements in ${name}p\n");
+ } elsif($type eq 'pair-list') {
+ return (" * \@param ${name}p $descr\n");
+ } elsif($type eq 'queue' or $type eq 'queue-one') {
+ return (" * \@param ${name}p $descr\n");
+ } elsif($type eq 'user') {
+ return ();
+ } else {
+ die "$0: c_return_docs: unknown type '$type'\n";
+ }
}
-# boolean(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+# simple(CMD, SUMMARY, DETAIL,
+# [[TYPE,NAME,DESCR], [TYPE,NAME,DESCR], ...],
+# [RETURN-TYPE, RETURN-NAME, RETURN_DESCR])
#
-# Response is yes/no or failure
-sub boolean {
+# CMD is normally just the name of the command, but can
+# be [COMMAND,FUNCTION] if the function name should differ
+# from the protocol command.
+sub simple {
my $cmd = shift;
my $summary = shift;
my $detail = shift;
my $args = shift;
my $return = shift;
- my $cmdc = $cmd;
- $cmdc =~ s/-/_/g;
+ my $cmdc;
+ if(ref $cmd eq 'ARRAY') {
+ $cmdc = $$cmd[1];
+ $cmd = $$cmd[0];
+ } else {
+ $cmdc = $cmd;
+ $cmdc =~ s/-/_/g;
+ }
+ print STDERR "Processing $cmd... ";
# Synchronous C API
+ print STDERR "H ";
push(@h, "/** \@brief $summary\n",
- " *\n",
- " * $detail\n",
- " *\n",
- map(" * \@param $_->[0] $_->[1]\n", @$args),
- " * \@param $return->[0] $return->[1]\n",
- " * \@return 0 on success, non-0 on error\n",
- " */\n",
- "int disorder_$cmdc(disorder_client *c",
- map(", const char *$_->[0]", @$args),
- ", int *$return->[0]);\n",
- "\n");
- push(@c, "int disorder_$cmdc(disorder_client *c",
- map(", const char *$_->[0]", @$args),
- ", int *$return->[0]) {\n",
- " char *v;\n",
- " int rc = disorder_simple(c, &v, \"$cmd\"",
- map(", $_->[0]", @$args),
- ", (char *)0);\n",
- " if(rc) return rc;\n",
- " if(!strcmp(v, \"yes\")) *$return->[0] = 1;\n",
- " if(!strcmp(v, \"no\")) *$return->[0] = 0;\n",
- " else {\n",
- " disorder_error(0, \"malformed response to '$cmd' command\");\n",
- " rc = -1;\n",
- " }\n",
- " xfree(v);\n",
- " return 0;\n",
- "}\n\n");
+ " *\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",
+ " */\n",
+ "int disorder_$cmdc(",
+ join(", ", "disorder_client *c",
+ map(c_in_decl($_), @$args),
+ c_out_decl($return)),
+ ");\n\n");
+ print STDERR "C ";
+ push(@c, "int disorder_$cmdc(",
+ join(", ", "disorder_client *c",
+ map(c_in_decl($_), @$args),
+ c_out_decl($return)),
+ ") {\n");
+ my @cargs = ();
+ for my $arg (@$args) {
+ if($arg->[0] eq 'body' or $arg->[0] eq 'list') {
+ push(@cargs, "disorder_$arg->[0]", $arg->[1], "n$arg->[1]");
+ } elsif($arg->[0] eq 'string') {
+ push(@cargs, $arg->[1]);
+ } elsif($arg->[0] eq 'integer') {
+ push(@cargs, "buf_$arg->[1]");
+ push(@c, " char buf_$arg->[1]\[16];\n",
+ " byte_snprintf(buf_$arg->[1], sizeof buf_$arg->[1], \"%ld\", $arg->[1]);\n");
+ } else {
+ die "$0: unsupported arg type '$arg->[0]' for '$cmd'\n";
+ }
+ }
+ if(!defined $return) {
+ push(@c, " return disorder_simple(",
+ join(", ", "c", 0, "\"$cmd\"", @cargs, "(char *)0"),
+ ");\n");
+ } elsif($return->[0] eq 'string') {
+ push(@c, " return dequote(disorder_simple(",
+ join(", ", "c", "$return->[1]p", "\"$cmd\"",
+ @cargs,
+ "(char *)0"),
+ "), $return->[1]p);\n");
+ } elsif($return->[0] eq 'boolean') {
+ push(@c, " char *v;\n",
+ " int rc;\n",
+ " if((rc = disorder_simple(",
+ join(", ", "c", "&v", "\"$cmd\"",
+ @cargs,
+ "(char *)0"),
+ ")))\n",
+ " return rc;\n",
+ " return boolean(\"$cmd\", v, $return->[1]p);\n");
+ } elsif($return->[0] eq 'integer') {
+ push(@c, " char *v;\n",
+ " int rc;\n",
+ "\n",
+ " if((rc = disorder_simple(",
+ join(", ", "c", "&v", "\"$cmd\"",
+ @cargs,
+ "(char *)0"),
+ ")))\n",
+ " return rc;\n",
+ " *$return->[1]p = atol(v);\n",
+ " xfree(v);\n",
+ " return 0;\n");
+ } elsif($return->[0] eq 'user') {
+ push(@c, " char *u;\n",
+ " int rc;\n",
+ " if((rc = disorder_simple(",
+ join(", ", "c", "&u", "\"$cmd\"",
+ @cargs, "(char *)0"),
+ ")))\n",
+ " return rc;\n",
+ " c->user = u;\n",
+ " return 0;\n");
+ } elsif($return->[0] eq 'body') {
+ push(@c, " return disorder_simple_list(",
+ join(", ", "c", "$return->[1]p", "n$return->[1]p", "\"$cmd\"",
+ @cargs,
+ "(char *)0"),
+ ");\n");
+ } elsif($return->[0] eq 'queue') {
+ push(@c, " return somequeue(c, \"$cmd\", $return->[1]p);\n");
+ } elsif($return->[0] eq 'queue-one') {
+ push(@c, " return onequeue(c, \"$cmd\", $return->[1]p);\n");
+ } elsif($return->[0] eq 'pair-list') {
+ push(@c, " return pairlist(",
+ join(", ", "c", "$return->[1]p", "\"$cmd\"",
+ @cargs,
+ "(char *)0"),
+ ");\n");
+ } else {
+ die "$0: C API: unknown type '$return->[0]' for '$cmd'\n";
+ }
+ push(@c, "}\n\n");
# Asynchronous C API
# TODO
# Java API
# TODO
+ print STDERR "\n";
}
# TODO other command classes
# Front matter ----------------------------------------------------------------
+our @generated = ("/*\n",
+ " * Automatically generated file, see scripts/protocol\n",
+ " *\n",
+ " * DO NOT EDIT.\n",
+ " */\n");
+
our @gpl = ("/*\n",
- " * This file is part of DisOrder.\n",
- " * Copyright (C) 2010 Richard Kettlewell\n",
- " *\n",
- " * This program is free software: you can redistribute it and/or modify\n",
- " * it under the terms of the GNU General Public License as published by\n",
- " * the Free Software Foundation, either version 3 of the License, or\n",
- " * (at your option) any later version.\n",
- " *\n",
- " * This program is distributed in the hope that it will be useful,\n",
- " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
- " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n",
- " * GNU General Public License for more details.\n",
- " *\n",
- " * You should have received a copy of the GNU General Public License\n",
- " * along with this program. If not, see <http://www.gnu.org/licenses/>.\n",
- " */\n");
-
-
-push(@h, @gpl,
+ " * This file is part of DisOrder.\n",
+ " * Copyright (C) 2010-11 Richard Kettlewell\n",
+ " *\n",
+ " * This program is free software: you can redistribute it and/or modify\n",
+ " * it under the terms of the GNU General Public License as published by\n",
+ " * the Free Software Foundation, either version 3 of the License, or\n",
+ " * (at your option) any later version.\n",
+ " *\n",
+ " * This program is distributed in the hope that it will be useful,\n",
+ " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
+ " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n",
+ " * GNU General Public License for more details.\n",
+ " *\n",
+ " * You should have received a copy of the GNU General Public License\n",
+ " * along with this program. If not, see <http://www.gnu.org/licenses/>.\n",
+ " */\n");
+
+
+push(@h, @generated, @gpl,
"#ifndef CLIENT_STUBS_H\n",
"#define CLIENT_STUBS_H\n",
"\n");
-push(@c, @gpl,
+push(@c, @generated, @gpl,
"\n");
# The protocol ----------------------------------------------------------------
simple("adopt",
"Adopt a track",
"Makes the calling user owner of a randomly picked track.",
- [["id", "Track ID"]]);
+ [["string", "id", "Track ID"]]);
simple("adduser",
"Create a user",
"Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.",
- [["user", "New username"],
- ["password", "Initial password"],
- ["rights", "Initial rights (optional)"]]);
+ [["string", "user", "New username"],
+ ["string", "password", "Initial password"],
+ ["string", "rights", "Initial rights (optional)"]]);
-# TODO allfiles
+simple("allfiles",
+ "List files and directories in a directory",
+ "See 'files' and 'dirs' for more specific lists.",
+ [["string", "dir", "Directory to list (optional)"],
+ ["string", "re", "Regexp that results must match (optional)"]],
+ ["body", "files", "List of matching files and directories"]);
simple("confirm",
- "Confirm user registration",
- "The confirmation string is as returned by the register command.",
- [["confirmation", "Confirmnation string"]]);
+ "Confirm registration",
+ "The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are.",
+ [["string", "confirmation", "Confirmation string"]],
+ ["user"]);
-# TODO cookie
+simple("cookie",
+ "Log in with a cookie",
+ "The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.",
+ [["string", "cookie", "Cookie string"]],
+ ["user"]);
simple("deluser",
"Delete user",
"Requires the 'admin' right.",
- [["user", "User to delete"]]);
+ [["string", "user", "User to delete"]]);
-# TODO dirs
+simple("dirs",
+ "List directories in a directory",
+ "",
+ [["string", "dir", "Directory to list (optional)"],
+ ["string", "re", "Regexp that results must match (optional)"]],
+ ["body", "files", "List of matching directories"]);
simple("disable",
"Disable play",
simple("edituser",
"Set a user property",
"With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.",
- [["username", "User to modify"],
- ["property", "Property name"],
- ["value", "New property value"]]);
+ [["string", "username", "User to modify"],
+ ["string", "property", "Property name"],
+ ["string", "value", "New property value"]]);
simple("enable",
"Enable play",
"Requires the 'global prefs' right.",
[]);
-boolean("enabled",
- "Detect whether play is enabled",
- "",
- [],
- ["enabled", "1 if play is enabled and 0 otherwise"]);
-
-boolean("exists",
- "Test whether a track exists",
- "",
- [["track", "Track name"]],
- ["exists", "1 if the track exists and 0 otherwise"]);
-
-# TODO files
-
-# TODO get
-
-# TODO get-global
-
-# TODO length
+simple("enabled",
+ "Detect whether play is enabled",
+ "",
+ [],
+ ["boolean", "enabled", "1 if play is enabled and 0 otherwise"]);
+
+simple("exists",
+ "Test whether a track exists",
+ "",
+ [["string", "track", "Track name"]],
+ ["boolean", "exists", "1 if the track exists and 0 otherwise"]);
+
+simple("files",
+ "List files in a directory",
+ "",
+ [["string", "dir", "Directory to list (optional)"],
+ ["string", "re", "Regexp that results must match (optional)"]],
+ ["body", "files", "List of matching files"]);
+
+simple("get",
+ "Get a track preference",
+ "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.",
+ [["string", "track", "Track name"],
+ ["string", "pref", "Preference name"]],
+ ["string", "value", "Preference value"]);
+
+simple("get-global",
+ "Get a global preference",
+ "If the preference does exist not then a null value is returned.",
+ [["string", "pref", "Global preference name"]],
+ ["string", "value", "Preference value"]);
+
+simple("length",
+ "Get a track's length",
+ "If the track does not exist an error is returned.",
+ [["string", "track", "Track name"]],
+ ["integer", "length", "Track length in seconds"]);
# TODO log
-# TODO make-cookie
-
-# TODO move
-
-# TODO moveafter
-
-# TODO new
+simple("make-cookie",
+ "Create a login cookie for this user",
+ "The cookie may be redeemed via the 'cookie' command",
+ [],
+ ["string", "cookie", "Newly created cookie"]);
+
+simple("move",
+ "Move a track",
+ "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
+ [["string", "track", "Track ID or name"],
+ ["integer", "delta", "How far to move the track towards the head of the queue"]]);
+
+simple("moveafter",
+ "Move multiple tracks",
+ "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
+ [["string", "target", "Move after this track, or to head if \"\""],
+ ["list", "ids", "List of tracks to move by ID"]]);
+
+simple(["new", "new_tracks"],
+ "List recently added tracks",
+ "",
+ [["integer", "max", "Maximum tracks to fetch, or 0 for all available"]],
+ ["body", "tracks", "Recently added tracks"]);
simple("nop",
"Do nothing",
"Used as a keepalive. No authentication required.",
[]);
-# TODO part
+simple("part",
+ "Get a track name part",
+ "If the name part cannot be constructed an empty string is returned.",
+ [["string", "track", "Track name"],
+ ["string", "context", "Context (\"sort\" or \"display\")"],
+ ["string", "part", "Name part (\"artist\", \"album\" or \"title\")"]],
+ ["string", "part", "Value of name part"]);
simple("pause",
"Pause the currently playing track",
"Requires the 'pause' right.",
[]);
-# TODO playafter
+simple("play",
+ "Play a track",
+ "Requires the 'play' right.",
+ [["string", "track", "Track to play"]],
+ ["string", "id", "Queue ID of new track"]);
+
+simple("playafter",
+ "Play multiple tracks",
+ "Requires the 'play' right.",
+ [["string", "target", "Insert into queue after this track, or at head if \"\""],
+ ["list", "tracks", "List of track names to play"]]);
-# TODO playing
+simple("playing",
+ "Retrieve the playing track",
+ "",
+ [],
+ ["queue-one", "playing", "Details of the playing track"]);
simple("playlist-delete",
"Delete a playlist",
"Requires the 'play' right and permission to modify the playlist.",
- [["playlist", "Playlist to delete"]]);
+ [["string", "playlist", "Playlist to delete"]]);
-# TODO playlist-get
+simple("playlist-get",
+ "List the contents of a playlist",
+ "Requires the 'read' right and oermission to read the playlist.",
+ [["string", "playlist", "Playlist name"]],
+ ["body", "tracks", "List of tracks in playlist"]);
-# TODO playlist-get-share
+simple("playlist-get-share",
+ "Get a playlist's sharing status",
+ "Requires the 'read' right and permission to read the playlist.",
+ [["string", "playlist", "Playlist to read"]],
+ ["string", "share", "Sharing status (\"public\", \"private\" or \"shared\")"]);
simple("playlist-lock",
"Lock a playlist",
"Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.",
- [["playlist", "Playlist to delete"]]);
+ [["string", "playlist", "Playlist to delete"]]);
-# TODO playlist-set
+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"],
+ ["body", "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. ",
- [["playlist", "Playlist to modify"],
- ["share", "New sharing status ('public', 'private' or 'shared')"]]);
+ "Requires the 'play' right and permission to modify the playlist.",
+ [["string", "playlist", "Playlist to modify"],
+ ["string", "share", "New sharing status (\"public\", \"private\" or \"shared\")"]]);
simple("playlist-unlock",
"Unlock the locked playlist playlist",
"The playlist to unlock is implicit in the connection.",
[]);
-# TODO playlists
+simple("playlists",
+ "List playlists",
+ "Requires the 'read' right. Only playlists that you have permission to read are returned.",
+ [],
+ ["body", "playlists", "Playlist names"]);
-# TODO prefs
+simple("prefs",
+ "Get all the preferences for a track",
+ "",
+ [["string", "track", "Track name"]],
+ ["pair-list", "prefs", "Track preferences"]);
-# TODO queue
+simple("queue",
+ "List the queue",
+ "",
+ [],
+ ["queue", "queue", "Current queue contents"]);
simple("random-disable",
"Disable random play",
"Requires the 'global prefs' right.",
[]);
-boolean("random-enabled",
- "Detect whether random play is enabled",
- "Random play counts as enabled even if play is disabled.",
- [],
- ["enabled", "1 if random play is enabled and 0 otherwise"]);
-
-# TODO random-enabled
+simple("random-enabled",
+ "Detect whether random play is enabled",
+ "Random play counts as enabled even if play is disabled.",
+ [],
+ ["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.",
"Requires the 'admin' right.",
[]);
-# TODO register
+simple("register",
+ "Register a new user",
+ "Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.",
+ [["string", "username", "Requested new username"],
+ ["string", "password", "Requested initial password"],
+ ["string", "email", "New user's email address"]],
+ ["string", "confirmation", "Confirmation string"]);
simple("reminder",
"Send a password reminder.",
"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.",
- [["username", "User to remind"]]);
+ [["string", "username", "User to remind"]]);
simple("remove",
"Remove a track form the queue.",
"Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.",
- [["id", "Track ID"]]);
+ [["string", "id", "Track ID"]]);
simple("rescan",
"Rescan all collections for new or obsolete tracks.",
"Requires the 'rescan' right.",
- []); # TODO wait/fresh flags
+ []); # TODO wait/fresh flags
-# TODO resolve
+simple("resolve",
+ "Resolve a track name",
+ "Converts aliases to non-alias track names",
+ [["string", "track", "Track name (might be an alias)"]],
+ ["string", "resolved", "Resolve track name (definitely not an alias)"]);
simple("resume",
"Resume the currently playing track",
simple("revoke",
"Revoke a cookie.",
"It will not subsequently be possible to log in with the cookie.",
- [["cookie", "Cookie to revoke"]]);
+ []);
# TODO rtp-address
simple("scratch",
"Terminate the playing track.",
"Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.",
- [["id", "Track ID (optional)"]]);
+ [["string", "id", "Track ID (optional)"]]);
# TODO schedule-add
simple("schedule-del",
"Delete a scheduled event.",
"Users can always delete their own scheduled events; with the admin right you can delete any event.",
- [["event", "ID of event to delete"]]);
-
-# TODO schedule-get
-
-# TODO schedule-list
-
-# TODO search
+ [["string", "event", "ID of event to delete"]]);
+
+simple("schedule-get",
+ "Get the details of scheduled event",
+ "",
+ [["string", "id", "Event ID"]],
+ ["pair-list", "actiondata", "Details of event"]);
+
+simple("schedule-list",
+ "List scheduled events",
+ "This just lists IDs. Use 'schedule-get' to retrieve more detail",
+ [],
+ ["body", "ids", "List of event IDs"]);
+
+simple("search",
+ "Search for tracks",
+ "Terms are either keywords or tags formatted as 'tag:TAG-NAME'.",
+ [["string", "terms", "List of search terms"]],
+ ["body", "tracks", "List of matching tracks"]);
simple("set",
"Set a track preference",
"Requires the 'prefs' right.",
- [["track", "Track name"],
- ["pref", "Preference name"],
- ["value", "New value"]]);
+ [["string", "track", "Track name"],
+ ["string", "pref", "Preference name"],
+ ["string", "value", "New value"]]);
simple("set-global",
"Set a global preference",
"Requires the 'global prefs' right.",
- [["pref", "Preference name"],
- ["value", "New value"]]);
+ [["string", "pref", "Preference name"],
+ ["string", "value", "New value"]]);
+
+simple("shutdown",
+ "Request server shutdown",
+ "Requires the 'admin' right.",
+ []);
-# TODO stats
+simple("stats",
+ "Get server statistics",
+ "The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line..",
+ [],
+ ["body", "stats", "List of server information strings."]);
-# TODO tags
+simple("tags",
+ "Get a list of known tags",
+ "Only tags which apply to at least one track are returned.",
+ [],
+ ["body", "tags", "List of tags"]);
simple("unset",
"Unset a track preference",
"Requires the 'prefs' right.",
- [["track", "Track name"],
- ["pref", "Preference name"]]);
+ [["string", "track", "Track name"],
+ ["string", "pref", "Preference name"]]);
simple("unset-global",
"Set a global preference",
"Requires the 'global prefs' right.",
- [["pref", "Preference name"]]);
+ [["string", "pref", "Preference name"]]);
-# user is only used by connect functions
+# 'user' only used for authentication
-# TODO userinfo
+simple("userinfo",
+ "Get a user property.",
+ "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.",
+ [["string", "username", "User to read"],
+ ["string", "property", "Property to read"]],
+ ["string", "value", "Value of property"]);
-# TODO users
+simple("users",
+ "Get a list of users",
+ "",
+ [],
+ ["body", "users", "List of users"]);
-# TODO version
+simple("version",
+ "Get the server version",
+ "",
+ [],
+ ["string", "version", "Server version string"]);
# TODO volume
# Write it all out ------------------------------------------------------------
-Write("client-stubs.h", \@h);
-Write("client-stubs.c", \@c);
+Write("lib/client-stubs.h", \@h);
+Write("lib/client-stubs.c", \@c);
~mdw / disorder / blobdiff