(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;
$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
+
+ # 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
+
+ # Python API
+ # TODO
+
+ # Java API
+ # TODO
+}
+
+# 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;
+
+ 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
# 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,
# The protocol ----------------------------------------------------------------
-simple_string_command("adopt",
- "Adopt a track",
- "Makes the calling user owner of a randomly picked track.",
- [["id", "Track ID"]]);
+simple("adopt",
+ "Adopt a track",
+ "Makes the calling user owner of a randomly picked track.",
+ [["id", "Track ID"]]);
-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)"]]);
+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)"]]);
# TODO allfiles
-simple_string_command("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_string_command("deluser",
- "Delete user",
- "Requires the 'admin' right.",
- [["user", "User to delete"]]);
+simple("deluser",
+ "Delete user",
+ "Requires the 'admin' right.",
+ [["user", "User to delete"]]);
# TODO dirs
-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.",
- []);
-
-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"]]);
-
-simple_string_command("enable",
- "Enable play",
- "Requires the 'global prefs' right.",
- []);
-
-# TODO enabled
-
-# TODO exists
+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"]);
# 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 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 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"]]);
+simple("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"]]);
+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"]]);
-# 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_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("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.",
- []);
+simple("playlist-unlock",
+ "Unlock the locked playlist playlist",
+ "The playlist to unlock is implicit in the connection.",
+ []);
# TODO playlists
# 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 search
-simple_string_command("set",
- "Set a track preference",
- "Requires the 'prefs' right.",
- [["track", "Track name"],
- ["pref", "Preference name"],
- ["value", "New value"]]);
+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"]]);
-simple_string_command("set-global",
- "Set a global preference",
- "Requires the 'global prefs' right.",
- [["pref", "Preference name"],
- ["value", "New value"]]);
+# TODO shutdown (also needs documenting)
# TODO stats
# TODO tags
-simple_string_command("unset",
- "Unset a track preference",
- "Requires the 'prefs' right.",
- [["track", "Track name"],
- ["pref", "Preference name"]]);
+simple("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"]]);
+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 version
+string("version",
+ "Get the server version",
+ "",
+ [],
+ ["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