Implement more commands.

[disorder] / scripts / protocol

diff --git a/scripts/protocol b/scripts/protocol
index 88d6266f22f84838339f20cb6c327eac47f6e473..b3ba0fc705a468f3f8f2fbeee2be4b817d76f651 100755 (executable)
--- a/scripts/protocol
+++ b/scripts/protocol
@@ -30,7 +30,7 @@ sub Write {
     (open(F, ">$path")
      and print F @$lines
      and close F)
     (open(F, ">$path")
      and print F @$lines
      and close F)

-       or die "$0: $path: $!\n";
+        or die "$0: $path: $!\n";

 }
 
 # Command classes -------------------------------------------------------------
 }
 
 # Command classes -------------------------------------------------------------


@@ -48,21 +48,110 @@ sub simple {
     $cmdc =~ s/-/_/g;
     # Synchronous C API
     push(@h, "/** \@brief $summary\n",
     $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",
     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
+
+    # Python API
+    # TODO
+
+    # Java API
+    # TODO
+}
+
+# string(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
+#
+# Response is yes/no or failure
+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
+}
+
+# string(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...])
+#
+# Response is yes/no or failure
+sub string_login {
+    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),
+         " * \@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
 
     # Asynchronous C API
     # TODO


@@ -88,34 +177,28 @@ sub boolean {
     $cmdc =~ s/-/_/g;
     # Synchronous C API
     push(@h, "/** \@brief $summary\n",
     $cmdc =~ s/-/_/g;
     # Synchronous C API
     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");
+         " *\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",
     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");
+         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
 
     # Asynchronous C API
     # TODO


@@ -132,22 +215,22 @@ sub boolean {
 # Front matter ----------------------------------------------------------------
 
 our @gpl = ("/*\n",
 # Front matter ----------------------------------------------------------------
 
 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");
+            " * 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,
 
 
 push(@h, @gpl,


@@ -169,17 +252,21 @@ 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"],
        "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)"]]);
+        ["password", "Initial password"],
+        ["rights", "Initial rights (optional)"]]);

 
 # TODO allfiles
 
 
 # TODO allfiles
 

-simple("confirm",
-       "Confirm user registration",
-       "The confirmation string is as returned by the register command.",
-       [["confirmation", "Confirmnation string"]]);
+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

 
 

-# TODO cookie
+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",
 
 simple("deluser",
        "Delete user",


@@ -197,7 +284,7 @@ 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"],
        "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"],
+        ["property", "Property name"],

        ["value", "New property value"]]);
 
 simple("enable",
        ["value", "New property value"]]);
 
 simple("enable",


@@ -206,28 +293,41 @@ simple("enable",
        []);
 
 boolean("enabled",
        []);
 
 boolean("enabled",

-       "Detect whether play is enabled",
-       "",
-       [],
-       ["enabled", "1 if play is enabled and 0 otherwise"]);
+        "Detect whether play is enabled",
+        "",
+        [],
+        ["enabled", "1 if play is enabled and 0 otherwise"]);

 
 boolean("exists",
 
 boolean("exists",

-       "Test whether a track exists",
-       "",
-       [["track", "Track name"]],
-       ["exists", "1 if the track exists and 0 otherwise"]);
+        "Test whether a track exists",
+        "",
+        [["track", "Track name"]],
+        ["exists", "1 if the track exists and 0 otherwise"]);

 
 # TODO files
 
 
 # TODO files
 

-# TODO get
+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"]);

 
 

-# TODO get-global
+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 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
 
 
 # TODO move
 


@@ -240,7 +340,13 @@ simple("nop",
        "Used as a keepalive.  No authentication required.",
        []);
 
        "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("pause",
        "Pause the currently playing track",
 
 simple("pause",
        "Pause the currently playing track",


@@ -265,13 +371,17 @@ simple("playlist-lock",
        "Requires the 'play' right and permission to modify the playlist.  A given connection may lock at most one playlist.",
        [["playlist", "Playlist to delete"]]);
 
        "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
+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-set-share",
        "Set a playlist's sharing status",
 
 simple("playlist-set-share",
        "Set a playlist's sharing status",

-       "Requires the 'play' right and permission to modify the playlist.  ",
+       "Requires the 'play' right and permission to modify the playlist.",

        [["playlist", "Playlist to modify"],
        [["playlist", "Playlist to modify"],

-       ["share", "New sharing status ('public', 'private' or 'shared')"]]);
+        ["share", "New sharing status (\"public\", \"private\" or \"shared\")"]]);

 
 simple("playlist-unlock",
        "Unlock the locked playlist playlist",
 
 simple("playlist-unlock",
        "Unlock the locked playlist playlist",


@@ -295,12 +405,10 @@ simple("random-enable",
        []);
 
 boolean("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 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
 
 
 # TODO recent
 


@@ -309,7 +417,13 @@ simple("reconfigure",
        "Requires the 'admin' right.",
        []);
 
        "Requires the 'admin' right.",
        []);
 

-# TODO register
+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.",
 
 simple("reminder",
        "Send a password reminder.",


@@ -324,9 +438,13 @@ simple("remove",
 simple("rescan",
        "Rescan all collections for new or obsolete tracks.",
        "Requires the 'rescan' right.",
 simple("rescan",
        "Rescan all collections for new or obsolete tracks.",
        "Requires the 'rescan' right.",

-       []);    # TODO wait/fresh flags
+       []);     # TODO wait/fresh flags

 
 

-# TODO resolve
+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",
 
 simple("resume",
        "Resume the currently playing track",


@@ -336,7 +454,7 @@ simple("resume",
 simple("revoke",
        "Revoke a cookie.",
        "It will not subsequently be possible to log in with the cookie.",
 simple("revoke",
        "Revoke a cookie.",
        "It will not subsequently be possible to log in with the cookie.",

-       [["cookie", "Cookie to revoke"]]);
+       []);                     # TODO fix docs!

 
 # TODO rtp-address
 
 
 # TODO rtp-address
 


@@ -362,7 +480,7 @@ simple("set",
        "Set a track preference",
        "Requires the 'prefs' right.",
        [["track", "Track name"],
        "Set a track preference",
        "Requires the 'prefs' right.",
        [["track", "Track name"],

-       ["pref", "Preference name"],
+        ["pref", "Preference name"],

        ["value", "New value"]]);
 
 simple("set-global",
        ["value", "New value"]]);
 
 simple("set-global",


@@ -371,6 +489,8 @@ simple("set-global",
        [["pref", "Preference name"],
        ["value", "New value"]]);
 
        [["pref", "Preference name"],
        ["value", "New value"]]);
 

+# TODO shutdown (also needs documenting)
+

 # TODO stats
 
 # TODO tags
 # TODO stats
 
 # TODO tags


@@ -379,20 +499,29 @@ simple("unset",
        "Unset a track preference",
        "Requires the 'prefs' right.",
        [["track", "Track name"],
        "Unset a track preference",
        "Requires the 'prefs' right.",
        [["track", "Track name"],

-       ["pref", "Preference name"]]);
+        ["pref", "Preference name"]]);

 
 simple("unset-global",
        "Set a global preference",
        "Requires the 'global prefs' right.",
        [["pref", "Preference name"]]);
 
 
 simple("unset-global",
        "Set a global preference",
        "Requires the 'global prefs' right.",
        [["pref", "Preference name"]]);
 

-# user is only used by connect functions
+# TODO user?

 
 

-# TODO userinfo
+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"]);

 
 # TODO users
 
 
 # TODO users
 

-# TODO version
+string("version",
+       "Get the server version",
+       "",
+       [],
+       ["version", "Server version string"]);

 
 # TODO volume
 
 
 # TODO volume
 


@@ -402,5 +531,5 @@ push(@h, "#endif\n");
 
 # Write it all out ------------------------------------------------------------
 
 
 # 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);