X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/3680ef53ec6a3d5769c8703caed4a58e18a91bc6..eff6238fcaa690773dc292816fa47b8767efa00c:/scripts/protocol

diff --git a/scripts/protocol b/scripts/protocol
index 46a1cbf..0704942 100755
--- a/scripts/protocol
+++ b/scripts/protocol
@@ -1,7 +1,7 @@
 #! /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
@@ -18,11 +18,34 @@
 #
 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;
@@ -35,215 +58,224 @@ sub Write {
 
 # 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");
-
-    # Asynchronous C API
-    # TODO
-
-    # Python API
-    # TODO
-
-    # Java API
-    # TODO
+# 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";
+    }
 }
 
-# string(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+# c_out_decl([TYPE, NAME])
 #
-# 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;
-
-    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");
-
-    # Asynchronous C API
-    # TODO
-
-    # Python API
-    # TODO
-
-    # Java API
-    # TODO
+# 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";
+    }
 }
 
-# string_login(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...])
+# c_param_docs([TYPE, NAME})
 #
-# 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;
+# Return the doc string for a C input parameter.
+sub c_param_docs {
     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),
-         " * \@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");
-
-    # Asynchronous C API
-    # TODO
-
-    # Python API
-    # TODO
-
-    # Java API
-    # TODO
+    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;
 }
 
-# boolean(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+# c_param_docs([TYPE, NAME})
 #
-# Response is yes/no or failure
-sub boolean {
-    my $cmd = shift;
-    my $summary = shift;
-    my $detail = shift;
-    my $args = shift;
+# Return the doc string for a C output parameter.
+sub c_return_docs {
     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",
-         " * \@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");
-
-    # Asynchronous C API
-    # TODO
-
-    # Python API
-    # TODO
-
-    # Java API
-    # TODO
+    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";
+    }
 }
 
-# list(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 a a list of strings in a dot-stuffed body
-sub list {
+# 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]p $return->[1]\n",
-         " * \@param n$return->[0]p Number of elements in $return->[0]p\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(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");
+         "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
@@ -253,15 +285,22 @@ sub list {
 
     # 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",
+            " * 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",
@@ -278,12 +317,12 @@ our @gpl = ("/*\n",
             " */\n");
 
 
-push(@h, @gpl,
+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 ----------------------------------------------------------------
@@ -291,44 +330,45 @@ push(@c, @gpl,
 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)"]]);
-
-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"]]);
+       [["string", "user", "New username"],
+        ["string", "password", "Initial password"],
+        ["string", "rights", "Initial rights (optional)"]]);
+
+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 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"]);
+
+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"]]);
 
-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("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",
@@ -338,127 +378,171 @@ simple("disable",
 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"]);
-
-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",
+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.",
-       [["track", "Track name"],
-        ["pref", "Preference name"]],
-       ["value", "Preference value"]);
+       [["string", "track", "Track name"],
+        ["string", "pref", "Preference name"]],
+       ["string", "value", "Preference value"]);
 
-string("get-global",
+simple("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"]);
+       [["string", "pref", "Global preference name"]],
+       ["string", "value", "Preference value"]);
 
-# TODO length
+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
 
-string("make-cookie",
+simple("make-cookie",
        "Create a login cookie for this user",
        "The cookie may be redeemed via the 'cookie' command",
        [],
-       ["cookie", "Newly created cookie"]);
-
-# TODO move
-
-# TODO moveafter
-
-# TODO new
+       ["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.",
        []);
 
-string("part",
+simple("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"]);
+       [["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"]]);
 
-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"]);
+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"]);
 
-string("playlist-get-share",
+simple("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\")"]);
+       [["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"]]);
+
+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\")"]]);
+       [["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.",
        []);
 
-list("playlists",
-     "List playlists",
-     "Requires the 'read' right.  Only playlists that you have permission to read are returned.",
-     [],
-     ["playlists", "Playlist names"]);
+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",
@@ -470,47 +554,51 @@ simple("random-enable",
        "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"]);
+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.",
        []);
 
-string("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.",
-       [["username", "Requested new username"],
-        ["password", "Requested initial password"],
-        ["email", "New user's email address"]],
-       ["confirmation", "Confirmation string"]);
+       [["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
 
-string("resolve",
+simple("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)"]);
+       [["string", "track", "Track name (might be an alias)"]],
+       ["string", "resolved", "Resolve track name (definitely not an alias)"]);
 
 simple("resume",
        "Resume the currently playing track",
@@ -520,94 +608,101 @@ simple("resume",
 simple("revoke",
        "Revoke a cookie.",
        "It will not subsequently be possible to log in with the cookie.",
-       []);                     # TODO fix docs!
+       []);
 
 # 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"]]);
+       [["string", "event", "ID of event to delete"]]);
 
-# TODO schedule-get
+simple("schedule-get",
+       "Get the details of scheduled event",
+       "",
+       [["string", "id", "Event ID"]],
+       ["pair-list", "actiondata", "Details of event"]);
 
-list("schedule-list",
-     "List scheduled events",
-     "This just lists IDs.  Use 'schedule-get' to retrieve more detail",
-     [],
-     ["ids", "List of event IDs"]);
+simple("schedule-list",
+       "List scheduled events",
+       "This just lists IDs.  Use 'schedule-get' to retrieve more detail",
+       [],
+       ["body", "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("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"]]);
 
-# TODO shutdown (also needs documenting)
+simple("shutdown",
+       "Request server shutdown",
+       "Requires the 'admin' right.",
+       []);
 
-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."]);
+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."]);
 
-list("tags",
-     "Get a list of known tags",
-     "Only tags which apply to at least one track are returned.",
-     [],
-     ["tags", "List of 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"]]);
 
-# TODO user?
+# 'user' only used for authentication
 
-string("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.",
-       [["username", "User to read"],
-        ["property", "Property to read"]],
-       ["value", "Value of property"]);
+       [["string", "username", "User to read"],
+        ["string", "property", "Property to read"]],
+       ["string", "value", "Value of property"]);
 
-list("users",
-     "Get a list of users",
-     "",
-     [],
-     ["users", "List of users"]);
+simple("users",
+       "Get a list of users",
+       "",
+       [],
+       ["body", "users", "List of users"]);
 
-string("version",
+simple("version",
        "Get the server version",
        "",
        [],
-       ["version", "Server version string"]);
+       ["string", "version", "Server version string"]);
 
 # TODO volume