Stub + document shutdown command

[disorder] / scripts / protocol

#! /usr/bin/perl -w
#
# This file is part of DisOrder.
# Copyright (C) 2010 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
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
use strict;

# Variables and utilities -----------------------------------------------------

our @h = ();
our @c = ();

sub Write {
    my $path = shift;
    my $lines = shift;

    (open(F, ">$path")
     and print F @$lines
     and close F)
        or die "$0: $path: $!\n";
}

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

# simple(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],)
#
# 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
}

# 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;

    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_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;

    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

    # Python API
    # TODO

    # 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

    # Python API
    # TODO

    # Java API
    # TODO
}

# TODO other command classes

# 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");


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"]]);

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

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 moveafter

# TODO new

simple("nop",
       "Do nothing",
       "Used as a keepalive.  No authentication required.",
       []);

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",
       "Requires the 'pause' right.",
       []);

# TODO playafter

# TODO playing

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("random-disable",
       "Disable random play",
       "Requires the 'global prefs' right.",
       []);

simple("random-enable",
       "Enable random play",
       "Requires the 'global prefs' right.",
       []);

boolean("random-enabled",
        "Detect whether random play is enabled",
        "Random play counts as enabled even if play is disabled.",
        [],
        ["enabled", "1 if random play is enabled and 0 otherwise"]);

# TODO recent

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("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("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

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"]]);

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."]);

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

# End matter ------------------------------------------------------------------

push(@h, "#endif\n");

# Write it all out ------------------------------------------------------------

Write("lib/client-stubs.h", \@h);
Write("lib/client-stubs.c", \@c);