X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/200adb00f0319d35b9c512eadff714bb6933b9a9..74b9b6ddb1f1d80a5b1d75e4953cc36cf75799ee:/scripts/protocol

diff --git a/scripts/protocol b/scripts/protocol
index ad712d5..46a1cbf 100755
--- a/scripts/protocol
+++ b/scripts/protocol
@@ -30,15 +30,15 @@ sub Write {
     (open(F, ">$path")
      and print F @$lines
      and close F)
-	or die "$0: $path: $!\n";
+        or die "$0: $path: $!\n";
 }
 
 # Command classes -------------------------------------------------------------
 
-# simple_string_command(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],)
+# simple(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],)
 #
 # Response is simply success/failure
-sub simple_string_command {
+sub simple {
     my $cmd = shift;
     my $summary = shift;
     my $detail = shift;
@@ -48,21 +48,21 @@ sub simple_string_command {
     $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");
+         " *\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");
+         map(", const char *$_->[0]", @$args), ") {\n",
+         "  return disorder_simple(c, 0, \"$cmd\"",
+         map(", $_->[0]", @$args),
+         ", (char *)0);\n",
+         "}\n\n");
 
     # Asynchronous C API
     # TODO
@@ -74,99 +74,320 @@ sub simple_string_command {
     # TODO
 }
 
-# TODO other command classes
+# string(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+#
+# Response is a string, or failure, or 555 for "none".
+sub string {
+    my $cmd = shift;
+    my $summary = shift;
+    my $detail = shift;
+    my $args = shift;
+    my $return = shift;
 
-# Front matter ----------------------------------------------------------------
+    my $cmdc = $cmd;
+    $cmdc =~ s/-/_/g;
+    # Synchronous C API
+    push(@h, "/** \@brief $summary\n",
+         " *\n",
+         " * $detail\n",
+         " *\n",
+         map(" * \@param $_->[0] $_->[1]\n", @$args),
+         " * \@param $return->[0]p $return->[1]\n",
+         " * \@return 0 on success, non-0 on error\n",
+         " */\n",
+         "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+         ", char **$return->[0]p);\n",
+         "\n");
+    push(@c, "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+         ", char **$return->[0]p) {\n",
+         "  return dequote(disorder_simple(c, $return->[0]p, \"$cmd\"",
+         map(", $_->[0]", @$args),
+         ", (char *)0), $return->[0]p);\n",
+         "}\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");
+    # Asynchronous C API
+    # TODO
 
+    # Python API
+    # TODO
 
-push(@h, @gpl,
-     "#ifndef CLIENT_STUBS_H\n",
-     "#define CLIENT_STUBS_H\n",
-     "\n");
+    # Java API
+    # TODO
+}
 
-push(@c, @gpl,
-     "\n");
+# string_login(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...])
+#
+# Like string(), but the server returns a username, which we squirrel
+# away rather than returning to the caller.
+sub string_login {
+    my $cmd = shift;
+    my $summary = shift;
+    my $detail = shift;
+    my $args = shift;
+    my $return = shift;
 
-# The protocol ----------------------------------------------------------------
+    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");
+    push(@c, "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+	 ") {\n",
+	 "  char *u;\n",
+	 "  int rc;\n",
+         "  if((rc = disorder_simple(c, &u, \"$cmd\"",
+         map(", $_->[0]", @$args),
+	 "  )))\n",
+	 "    return rc;\n",
+	 "  c->user = u;\n",
+	 "  return 0;\n",
+         "}\n\n");
 
-simple_string_command("adopt",
-		      "Adopt a track",
-		      "Makes the calling user owner of a randomly picked track.",
-		      [["id", "Track ID"]]);
+    # Asynchronous C API
+    # TODO
 
-simple_string_command("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)"]]);
+    # Python API
+    # TODO
 
-# TODO allfiles
+    # Java API
+    # TODO
+}
 
-simple_string_command("confirm",
-		      "Confirm user registration",
-		      "The confirmation string is as returned by the register command.",
-		      [["confirmation", "Confirmnation string"]]);
+# boolean(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+#
+# Response is yes/no or failure
+sub boolean {
+    my $cmd = shift;
+    my $summary = shift;
+    my $detail = shift;
+    my $args = shift;
+    my $return = shift;
 
-# TODO cookie
+    my $cmdc = $cmd;
+    $cmdc =~ s/-/_/g;
+    # Synchronous C API
+    push(@h, "/** \@brief $summary\n",
+         " *\n",
+         " * $detail\n",
+         " *\n",
+         map(" * \@param $_->[0] $_->[1]\n", @$args),
+         " * \@param $return->[0]p $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]p);\n",
+         "\n");
+    push(@c, "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+         ", int *$return->[0]p) {\n",
+         "  char *v;\n",
+         "  int rc;\n",
+         "  if((rc = disorder_simple(c, &v, \"$cmd\"",
+         map(", $_->[0]", @$args),
+         ", (char *)0)))\n",
+         "    return rc;\n",
+         "  return boolean(\"$cmd\", v, $return->[0]p);\n",
+         "}\n\n");
 
-simple_string_command("deluser",
-		      "Delete user",
-		      "Requires the 'admin' right.",
-		      [["user", "User to delete"]]);
+    # Asynchronous C API
+    # TODO
 
-# TODO dirs
+    # Python API
+    # TODO
 
-simple_string_command("disable",
-		      "Disable play",
-		      "Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.",
-		      []);
+    # Java API
+    # TODO
+}
+
+# list(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+#
+# Response is a a list of strings in a dot-stuffed body
+sub list {
+    my $cmd = shift;
+    my $summary = shift;
+    my $detail = shift;
+    my $args = shift;
+    my $return = 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),
+         " * \@param $return->[0]p $return->[1]\n",
+         " * \@param n$return->[0]p Number of elements in $return->[0]p\n",
+         " * \@return 0 on success, non-0 on error\n",
+         " */\n",
+         "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+         ", char ***$return->[0]p, int *n$return->[0]p);\n",
+         "\n");
+    push(@c, "int disorder_$cmdc(disorder_client *c",
+         map(", const char *$_->[0]", @$args),
+         ", char ***$return->[0]p, int *n$return->[0]p) {\n",
+         "  return disorder_simple_list(c, $return->[0]p, n$return->[0]p, \"$cmd\"",
+         map(", $_->[0]", @$args),
+         ", (char *)0);\n",
+         "}\n\n");
+
+    # Asynchronous C API
+    # TODO
 
-simple_string_command("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"]]);
+    # Python API
+    # TODO
 
-simple_string_command("enable",
-		      "Enable play",
-		      "Requires the 'global prefs' right.",
-		      []);
+    # Java API
+    # TODO
+}
 
-# TODO enabled
+# TODO other command classes
 
-# TODO exists
+# Front matter ----------------------------------------------------------------
 
-# TODO files
+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");
 
-# TODO get
 
-# TODO get-global
+push(@h, @gpl,
+     "#ifndef CLIENT_STUBS_H\n",
+     "#define CLIENT_STUBS_H\n",
+     "\n");
+
+push(@c, @gpl,
+     "\n");
+
+# The protocol ----------------------------------------------------------------
+
+simple("adopt",
+       "Adopt a track",
+       "Makes the calling user owner of a randomly picked track.",
+       [["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)"]]);
+
+list("allfiles",
+     "List files and directories in a directory",
+     "See 'files' and 'dirs' for more specific lists.",
+     [["dir", "Directory to list (optional)"],
+      ["re", "Regexp that results must match (optional)"]],
+     ["files", "List of matching files and directories"]);
+
+string_login("confirm",
+	     "Confirm registration",
+	     "The confirmation string must have been created with 'register'.  The username is returned so the caller knows who they are.",
+	     [["confirmation", "Confirmation string"]]);
+#TODO update docs - this logs you in
+
+string_login("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.",
+	     [["cookie", "Cookie string"]]);
+
+simple("deluser",
+       "Delete user",
+       "Requires the 'admin' right.",
+       [["user", "User to delete"]]);
+
+list("dirs",
+     "List directories in a directory",
+     "",
+     [["dir", "Directory to list (optional)"],
+      ["re", "Regexp that results must match (optional)"]],
+     ["files", "List of matching directories"]);
+
+simple("disable",
+       "Disable play",
+       "Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.",
+       []);
+
+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"]]);
+
+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"]);
+
+list("files",
+     "List files in a directory",
+     "",
+     [["dir", "Directory to list (optional)"],
+      ["re", "Regexp that results must match (optional)"]],
+     ["files", "List of matching files"]);
+
+string("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.",
+       [["track", "Track name"],
+        ["pref", "Preference name"]],
+       ["value", "Preference value"]);
+
+string("get-global",
+       "Get a global preference",
+       "If the preference does exist not then a null value is returned.",
+       [["pref", "Global preference name"]],
+       ["value", "Preference value"]);
 
 # TODO length
 
 # TODO log
 
-# TODO make-cookie
+string("make-cookie",
+       "Create a login cookie for this user",
+       "The cookie may be redeemed via the 'cookie' command",
+       [],
+       ["cookie", "Newly created cookie"]);
 
 # TODO move
 
@@ -174,158 +395,219 @@ simple_string_command("enable",
 
 # TODO new
 
-simple_string_command("nop",
-		      "Do nothing",
-		      "Used as a keepalive.  No authentication required.",
-		      []);
+simple("nop",
+       "Do nothing",
+       "Used as a keepalive.  No authentication required.",
+       []);
 
-# TODO part
+string("part",
+       "Get a track name part",
+       "If the name part cannot be constructed an empty string is returned.",
+       [["track", "Track name"],
+        ["context", "Context (\"sort\" or \"display\")"],
+        ["part", "Name part (\"artist\", \"album\" or \"title\")"]],
+       ["part", "Value of name part"]);
 
-simple_string_command("pause",
-		      "Pause the currently playing track",
-		      "Requires the 'pause' right.",
-		      []);
+simple("pause",
+       "Pause the currently playing track",
+       "Requires the 'pause' right.",
+       []);
 
 # TODO playafter
 
 # TODO playing
 
-simple_string_command("playlist-delete",
-		      "Delete a playlist",
-		      "Requires the 'play' right and permission to modify the playlist.",
-		      [["playlist", "Playlist to delete"]]);
-
-# TODO playlist-get
-
-# TODO playlist-get-share
-
-simple_string_command("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"]]);
-
-# TODO playlist-set
-
-simple_string_command("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')"]]);
-
-simple_string_command("playlist-unlock",
-		      "Unlock the locked playlist playlist",
-		      "The playlist to unlock is implicit in the connection.",
-		      []);
-
-# TODO playlists
+simple("playlist-delete",
+       "Delete a playlist",
+       "Requires the 'play' right and permission to modify the playlist.",
+       [["playlist", "Playlist to delete"]]);
+
+list("playlist-get",
+     "List the contents of a playlist",
+     "Requires the 'read' right and oermission to read the playlist.",
+     [["playlist", "Playlist name"]],
+     ["tracks", "List of tracks in playlist"]);
+
+string("playlist-get-share",
+       "Get a playlist's sharing status",
+       "Requires the 'read' right and permission to read the playlist.",
+       [["playlist", "Playlist to read"]],
+       ["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"]]);
+
+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\")"]]);
+
+simple("playlist-unlock",
+       "Unlock the locked playlist playlist",
+       "The playlist to unlock is implicit in the connection.",
+       []);
+
+list("playlists",
+     "List playlists",
+     "Requires the 'read' right.  Only playlists that you have permission to read are returned.",
+     [],
+     ["playlists", "Playlist names"]);
 
 # TODO prefs
 
 # TODO queue
 
-simple_string_command("random-disable",
-		      "Disable random play",
-		      "Requires the 'global prefs' right.",
-		      []);
+simple("random-disable",
+       "Disable random play",
+       "Requires the 'global prefs' right.",
+       []);
 
-simple_string_command("random-enable",
-		      "Enable random play",
-		      "Requires the 'global prefs' right.",
-		      []);
+simple("random-enable",
+       "Enable random play",
+       "Requires the 'global prefs' right.",
+       []);
 
-# TODO random-enabled
+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 recent
 
-simple_string_command("reconfigure",
-		      "Re-read configuraiton file.",
-		      "Requires the 'admin' right.",
-		      []);
-
-# TODO register
-
-simple_string_command("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"]]);
-
-simple_string_command("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"]]);
-
-simple_string_command("rescan",
-		      "Rescan all collections for new or obsolete tracks.",
-		      "Requires the 'rescan' right.",
-		      []);	# TODO wait/fresh flags
-
-# TODO resolve
-
-simple_string_command("resume",
-		      "Resume the currently playing track",
-		      "Requires the 'pause' right.",
-		      []);
-
-simple_string_command("revoke",
-		      "Revoke a cookie.",
-		      "It will not subsequently be possible to log in with the cookie..",
-		      [["cookie", "Cookie to revoke"]]);
+simple("reconfigure",
+       "Re-read configuraiton file.",
+       "Requires the 'admin' right.",
+       []);
+
+string("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.",
+       [["username", "Requested new username"],
+        ["password", "Requested initial password"],
+        ["email", "New user's email address"]],
+       ["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"]]);
+
+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"]]);
+
+simple("rescan",
+       "Rescan all collections for new or obsolete tracks.",
+       "Requires the 'rescan' right.",
+       []);     # TODO wait/fresh flags
+
+string("resolve",
+       "Resolve a track name",
+       "Converts aliases to non-alias track names",
+       [["track", "Track name (might be an alias)"]],
+       ["resolved", "Resolve track name (definitely not an alias)"]);
+
+simple("resume",
+       "Resume the currently playing track",
+       "Requires the 'pause' right.",
+       []);
+
+simple("revoke",
+       "Revoke a cookie.",
+       "It will not subsequently be possible to log in with the cookie.",
+       []);                     # TODO fix docs!
 
 # TODO rtp-address
 
-simple_string_command("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)"]]);
+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)"]]);
 
 # TODO schedule-add
 
-simple_string_command("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"]]);
+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
-
-simple_string_command("set",
-		      "Set a track preference",
-		      "Requires the 'prefs' right.",
-		      [["track", "Track name"],
-		       ["pref", "Preference name"],
-		       ["value", "New value"]]);
-
-simple_string_command("set-global",
-		      "Set a global preference",
-		      "Requires the 'global prefs' right.",
-		      [["pref", "Preference name"],
-		       ["value", "New value"]]);
-
-# TODO stats
-
-# TODO tags
-
-simple_string_command("unset",
-		      "Unset a track preference",
-		      "Requires the 'prefs' right.",
-		      [["track", "Track name"],
-		       ["pref", "Preference name"]]);
-
-simple_string_command("unset-global",
-		      "Set a global preference",
-		      "Requires the 'global prefs' right.",
-		      [["pref", "Preference name"]]);
-
-# user is only used by connect functions
-
-# TODO userinfo
-
-# TODO users
-
-# TODO version
+list("schedule-list",
+     "List scheduled events",
+     "This just lists IDs.  Use 'schedule-get' to retrieve more detail",
+     [],
+     ["ids", "List of event IDs"]);
+
+list("search",
+     "Search for tracks",
+     "Terms are either keywords or tags formatted as 'tag:TAG-NAME'.",
+     [["terms", "List of search terms"]],
+     ["tracks", "List of matching tracks"]);
+
+simple("set",
+       "Set a track preference",
+       "Requires the 'prefs' right.",
+       [["track", "Track name"],
+        ["pref", "Preference name"],
+	["value", "New value"]]);
+
+simple("set-global",
+       "Set a global preference",
+       "Requires the 'global prefs' right.",
+       [["pref", "Preference name"],
+	["value", "New value"]]);
+
+# TODO shutdown (also needs documenting)
+
+list("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..",
+     [],
+     ["stats", "List of server information strings."]);
+
+list("tags",
+     "Get a list of known tags",
+     "Only tags which apply to at least one track are returned.",
+     [],
+     ["tags", "List of tags"]);
+
+simple("unset",
+       "Unset a track preference",
+       "Requires the 'prefs' right.",
+       [["track", "Track name"],
+        ["pref", "Preference name"]]);
+
+simple("unset-global",
+       "Set a global preference",
+       "Requires the 'global prefs' right.",
+       [["pref", "Preference name"]]);
+
+# TODO user?
+
+string("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.",
+       [["username", "User to read"],
+        ["property", "Property to read"]],
+       ["value", "Value of property"]);
+
+list("users",
+     "Get a list of users",
+     "",
+     [],
+     ["users", "List of users"]);
+
+string("version",
+       "Get the server version",
+       "",
+       [],
+       ["version", "Server version string"]);
 
 # TODO volume
 
@@ -335,5 +617,5 @@ push(@h, "#endif\n");
 
 # 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);