chiark - git - mdw - disorder/blob - scripts/protocol

   1 #! /usr/bin/perl -w
   2 #
   3 # This file is part of DisOrder.
   4 # Copyright (C) 2010-11, 13 Richard Kettlewell
   5 #
   6 # This program is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 #
  19 use strict;
  20
  21 # This file contains the definition of the disorder protocol, plus
  22 # code to generates stubs for it in the various supported languages.
  23 #
  24 # At the time of writing it is a work in progress!
  25
  26 #
  27 # Types:
  28 #
  29 #    string         A (Unicode) string.
  30 #    string-raw     A string that is not subject to de-quoting (return only)
  31 #    integer        An integer.  Decimal on the wire.
  32 #    time           A timestamp.  Decimal on the wire.
  33 #    boolean        True or false.  "yes" or "no" on the wire.
  34 #    list           In commands: a list of strings in the command.
  35 #                   In returns: a list of lines in the response.
  36 #    pair-list      In returns: a list of key-value pairs in a response body.
  37 #    body           In commands: a list of strings as a command body.
  38 #                   In returns: a list of strings as a response body.
  39 #    queue          In returns: a list of queue entries in a response body.
  40 #    queue-one      In returns: a queue entry in the response.
  41 #    literal        Constant string sent in sequence
  42 #
  43
  44 # Variables and utilities -----------------------------------------------------
  45
  46 our @h = ();
  47 our @c = ();
  48 our @ah = ();
  49 our @ac = ();
  50 our @missing = ();
  51
  52 # Mapping of return type sequences to eclient callbacks
  53 our @eclient_return = (
  54     ["no_response" => []],
  55     ["string_response" => ["string"]],
  56     ["string_response" => ["string-raw"]],
  57     ["integer_response" => ["integer"]],
  58     ["integer_response" => ["boolean"]],
  59     ["time_response" => ["time"]],
  60     ["pair_integer_response" => ["integer", "integer"]],
  61     ["queue_response" => ["queue"]],
  62     ["playing_response" => ["queue-one"]],
  63     ["list_response" => ["body"]],
  64     );
  65
  66 # eclient_response_matces(RETURNS, VARIANT)
  67 #
  68 # Return true if VARIANT matches RETURNS
  69 sub eclient_response_matches {
  70     my $returns = shift;
  71     my $variant = shift;
  72     my $types = $variant->[1];
  73     if(scalar @$returns != scalar @$types) { return 0; }
  74     for my $n (0 .. $#$returns) {
  75         my $return = $returns->[$n];
  76         my $type = $return->[0];
  77         if($type ne $types->[$n]) { return 0; }
  78     }
  79     return 1;
  80 }
  81
  82 # find_eclient_type(RETURNS)
  83 #
  84 # Find the result type for an eclient call
  85 sub find_eclient_response {
  86     my $returns = shift;
  87     if(!defined $returns) {
  88         $returns = [];
  89     }
  90     for my $variant (@eclient_return) {
  91         if(eclient_response_matches($returns, $variant)) {
  92             return $variant->[0];
  93         }
  94     }
  95     return undef;
  96 }
  97
  98 # Write(PATH, LINES)
  99 #
 100 # Write array ref LINES to file PATH.
 101 sub Write {
 102     my $path = shift;
 103     my $lines = shift;
 104
 105     (open(F, ">$path")
 106      and print F @$lines
 107      and close F)
 108         or die "$0: $path: $!\n";
 109 }
 110
 111 # Command classes -------------------------------------------------------------
 112
 113 # c_in_decl([TYPE, NAME])
 114 #
 115 # Return the C declaration for an input parameter of type TYPE with
 116 # name NAME.
 117 sub c_in_decl {
 118     my $arg = shift;
 119
 120     my $type = $arg->[0];
 121     my $name = $arg->[1];
 122     if($type eq 'string') {
 123         return "const char *$name";
 124     } elsif($type eq 'integer') {
 125         return "long $name";
 126     } elsif($type eq 'time') {
 127         return "time_t $name";
 128     } elsif($type eq 'list' or $type eq 'body') {
 129         return ("char **$name",
 130                 "int n$name");
 131     } elsif($type eq 'literal') {
 132         return ();
 133     } else {
 134         die "$0: c_in_decl: unknown type '$type'\n";
 135     }
 136 }
 137
 138 # c_out_decl([TYPE, NAME])
 139 #
 140 # Return the C declaration for an output (reference) parameter of type
 141 # TYPE with name NAME.
 142 sub c_out_decl {
 143     my $arg = shift;
 144
 145     return () unless defined $arg;
 146     my $type = $arg->[0];
 147     my $name = $arg->[1];
 148     if($type eq 'string' or $type eq 'string-raw') {
 149         return ("char **${name}p");
 150     } elsif($type eq 'integer') {
 151         return ("long *${name}p");
 152     } elsif($type eq 'time') {
 153         return ("time_t *${name}p");
 154     } elsif($type eq 'boolean') {
 155         return ("int *${name}p");
 156     } elsif($type eq 'list' or $type eq 'body') {
 157         return ("char ***${name}p",
 158                 "int *n${name}p");
 159     } elsif($type eq 'pair-list') {
 160         return ("struct kvp **${name}p");
 161     } elsif($type eq 'queue' or $type eq 'queue-one') {
 162         return ("struct queue_entry **${name}p");
 163     } elsif($type eq 'user') {
 164         return ();
 165     } else {
 166         die "$0: c_out_decl: unknown type '$type'\n";
 167     }
 168 }
 169
 170 # c_param_docs([TYPE, NAME})
 171 #
 172 # Return the doc string for a C input parameter.
 173 sub c_param_docs {
 174     my $args = shift;
 175     my @d = ();
 176     for my $arg (@$args) {
 177         my $type = $arg->[0];
 178         my $name = $arg->[1];
 179         my $description = $arg->[2];
 180         if($type eq 'body' or $type eq 'list') {
 181             push(@d,
 182                  " * \@param $name $description\n",
 183                  " * \@param n$name Length of $name\n");
 184         } elsif($type ne 'literal') {
 185             push(@d, " * \@param $name $description\n");
 186         }
 187     }
 188     return @d;
 189 }
 190
 191 # c_param_docs([TYPE, NAME})
 192 #
 193 # Return the doc string for a C output parameter.
 194 sub c_return_docs {
 195     my $returns = shift;
 196     return () unless defined $returns;
 197     my @docs = ();
 198     for my $return (@$returns) {
 199         my $type = $return->[0];
 200         my $name = $return->[1];
 201         my $descr = $return->[2];
 202         if($type eq 'string'
 203            or $type eq 'string-raw'
 204            or $type eq 'integer'
 205            or $type eq 'time'
 206            or $type eq 'boolean') {
 207             push(@docs,
 208                  " * \@param ${name}p $descr\n");
 209         } elsif($type eq 'list' or $type eq 'body') {
 210             push(@docs,
 211                  " * \@param ${name}p $descr\n",
 212                  " * \@param n${name}p Number of elements in ${name}p\n");
 213         } elsif($type eq 'pair-list') {
 214             push(@docs,
 215                  " * \@param ${name}p $descr\n");
 216         } elsif($type eq 'queue' or $type eq 'queue-one') {
 217             push(@docs,
 218                  " * \@param ${name}p $descr\n");
 219         } elsif($type eq 'user') {
 220             # nothing
 221         } else {
 222             die "$0: c_return_docs: unknown type '$type'\n";
 223         }
 224     }
 225     return @docs;
 226 }
 227
 228 # simple(CMD, SUMMARY, DETAIL,
 229 #        [[TYPE,NAME,DESCR], [TYPE,NAME,DESCR], ...],
 230 #        [[RETURN-TYPE, RETURN-NAME, RETURN_DESCR]])
 231 #
 232 # CMD is normally just the name of the command, but can
 233 # be [COMMAND,FUNCTION] if the function name should differ
 234 # from the protocol command.
 235 sub simple {
 236     my $cmd = shift;
 237     my $summary = shift;
 238     my $detail = shift;
 239     my $args = shift;
 240     my $returns = shift;
 241
 242     my $cmdc;
 243     if(ref $cmd eq 'ARRAY') {
 244         $cmdc = $$cmd[1];
 245         $cmd = $$cmd[0];
 246     } else {
 247         $cmdc = $cmd;
 248         $cmdc =~ s/-/_/g;
 249     }
 250     print STDERR "Processing $cmd... ";
 251     # C argument types
 252     my @cargs = ();
 253     for my $arg (@$args) {
 254         if($arg->[0] eq 'body' or $arg->[0] eq 'list') {
 255             push(@cargs, "disorder__$arg->[0]", $arg->[1], "n$arg->[1]");
 256         } elsif($arg->[0] eq 'string') {
 257             push(@cargs, $arg->[1]);
 258         } elsif($arg->[0] eq 'integer'
 259                 or $arg->[0] eq 'time') {
 260             push(@cargs, "disorder__$arg->[0]", "$arg->[1]");
 261         } elsif($arg->[0] eq 'literal') {
 262             push(@cargs, "\"$arg->[1]\"");
 263         } else {
 264             die "$0: unsupported arg type '$arg->[0]' for '$cmd'\n";
 265         }
 266     }
 267     # Synchronous C API
 268     print STDERR "H ";
 269     push(@h, "/** \@brief $summary\n",
 270          " *\n",
 271          " * $detail\n",
 272          " *\n",
 273          " * \@param c Client\n",
 274          c_param_docs($args),
 275          c_return_docs($returns),
 276          " * \@return 0 on success, non-0 on error\n",
 277          " */\n",
 278          "int disorder_$cmdc(",
 279          join(", ", "disorder_client *c",
 280                     map(c_in_decl($_), @$args),
 281                     map(c_out_decl($_), @$returns)),
 282          ");\n\n");
 283     print STDERR "C ";
 284     push(@c, "int disorder_$cmdc(",
 285          join(", ", "disorder_client *c",
 286                     map(c_in_decl($_), @$args),
 287                     map(c_out_decl($_), @$returns)),
 288          ") {\n");
 289     if(!defined $returns or scalar @$returns == 0) {
 290         # Simple case
 291         push(@c, "  return disorder_simple(",
 292              join(", ", "c", "NULL", "\"$cmd\"", @cargs, "(char *)NULL"),
 293              ");\n");
 294     } elsif(scalar @$returns == 1
 295             and $returns->[0]->[0] eq 'queue-one') {
 296         # Special case
 297         my $return = $$returns[0];
 298         push(@c, "  return onequeue(c, \"$cmd\", $return->[1]p);\n");
 299     } elsif(scalar @$returns == 1
 300             and $returns->[0]->[0] eq 'string-raw') {
 301         # Special case
 302         my $return = $$returns[0];
 303         push(@c, "  return disorder_simple(",
 304              join(", ", "c", "$return->[1]p", "\"$cmd\"", @cargs, "(char *)NULL"),
 305              ");\n");
 306     } elsif(scalar @$returns == 1
 307             and $returns->[0]->[0] eq 'pair-list') {
 308         # Special case
 309         my $return = $$returns[0];
 310         push(@c, "  return pairlist(",
 311              join(", ", "c", "$return->[1]p", "\"$cmd\"",
 312                   @cargs,
 313                   "(char *)NULL"),
 314              ");\n");
 315     } else {
 316         my $expected = 0;
 317         for(my $n = 0; $n < scalar @$returns; ++$n) {
 318             my $return = $returns->[$n];
 319             my $type = $return->[0];
 320             my $name = $return->[1];
 321             if($type eq 'string'
 322                or $type eq 'boolean'
 323                or $type eq 'integer'
 324                or $type eq 'time'
 325                or $type eq 'user') {
 326                 ++$expected;
 327             }
 328         }
 329         if($expected) {
 330             push(@c, "  char **v;\n",
 331                  "  int nv, rc = disorder_simple_split(",
 332                  join(", ",
 333                       "c",
 334                       "&v",
 335                       "&nv",
 336                       $expected,
 337                       "\"$cmd\"",
 338                       @cargs,
 339                       "(char *)NULL"),
 340                  ");\n",
 341                  "  if(rc)\n",
 342                  "    return rc;\n");
 343         } else {
 344             push(@c,
 345                  "  int rc = disorder_simple(",
 346                  join(", ",
 347                       "c",
 348                       "NULL",
 349                       "\"$cmd\"",
 350                       @cargs,
 351                       "(char *)NULL"),
 352                  ");\n",
 353                  "  if(rc)\n",
 354                  "    return rc;\n");
 355         }
 356         for(my $n = 0; $n < scalar @$returns; ++$n) {
 357             my $return = $returns->[$n];
 358             my $type = $return->[0];
 359             my $name = $return->[1];
 360             if($type eq 'string') {
 361                 push(@c,
 362                      "  *${name}p = v[$n];\n",
 363                      "  v[$n] = NULL;\n");
 364             } elsif($type eq 'boolean') {
 365                 push(@c,
 366                      "  if(boolean(\"$cmd\", v[$n], ${name}p))\n",
 367                      "    return -1;\n");
 368             } elsif($type eq 'integer') {
 369                 push(@c,
 370                      "  *${name}p = atol(v[$n]);\n");
 371             } elsif($type eq 'time') {
 372                 push(@c,
 373                      "  *${name}p = atoll(v[$n]);\n");
 374             } elsif($type eq 'user') {
 375                 push(@c,
 376                      "  c->user = v[$n];\n",
 377                      "  v[$n] = NULL;\n");
 378             } elsif($type eq 'body') {
 379                 push(@c,
 380                      "  if(readlist(c, ${name}p, n${name}p))\n",
 381                      "    return -1;\n");
 382             } elsif($type eq 'queue') {
 383                 push(@c,
 384                      "  if(readqueue(c, ${name}p))\n",
 385                      "    return -1;\n");
 386             } else {
 387                 die "$0: C API: unknown return type '$type' for '$name'\n";
 388             }
 389         }
 390         if($expected) {
 391             push(@c,
 392                  "  free_strings(nv, v);\n");
 393         }
 394         push(@c, "  return 0;\n");
 395     }
 396     push(@c, "}\n\n");
 397
 398     # Asynchronous C API
 399     my $variant = find_eclient_response($returns);
 400     if(defined $variant) {
 401         print STDERR "AH ";
 402         push(@ah,
 403              "/** \@brief $summary\n",
 404              " *\n",
 405              " * $detail\n",
 406              " *\n",
 407              " * \@param c Client\n",
 408              " * \@param completed Called upon completion\n",
 409              c_param_docs($args),
 410              " * \@param v Passed to \@p completed\n",
 411              " * \@return 0 if the command was queued successfuly, non-0 on error\n",
 412              " */\n",
 413              "int disorder_eclient_$cmdc(",
 414              join(", ", "disorder_eclient *c",
 415                   "disorder_eclient_$variant *completed",
 416                   map(c_in_decl($_), @$args),
 417                   "void *v"),
 418              ");\n\n");
 419
 420         print STDERR "AC ";
 421         push(@ac,
 422              "int disorder_eclient_$cmdc(",
 423              join(", ", "disorder_eclient *c",
 424                   "disorder_eclient_$variant *completed",
 425                   map(c_in_decl($_), @$args),
 426                   "void *v"),
 427              ") {\n");
 428         push(@ac, "  return simple(",
 429              join(", ",
 430                   "c",
 431                   "${variant}_opcallback",
 432                   "(void (*)())completed",
 433                   "v",
 434                   "\"$cmd\"",
 435                   @cargs,
 436                   "(char *)0"),
 437              ");\n");
 438         push(@ac, "}\n\n");
 439     } else {
 440         push(@missing, "disorder_eclient_$cmdc");
 441     }
 442
 443     # Python API
 444     # TODO
 445
 446     # Java API
 447     # TODO
 448     print STDERR "\n";
 449 }
 450
 451 # TODO other command classes
 452
 453 # Front matter ----------------------------------------------------------------
 454
 455 our @generated = ("/*\n",
 456                   " * Automatically generated file, see scripts/protocol\n",
 457                   " *\n",
 458                   " * DO NOT EDIT.\n",
 459                   " */\n");
 460
 461 our @gpl = ("/*\n",
 462             " * This file is part of DisOrder.\n",
 463             " * Copyright (C) 2010-11 Richard Kettlewell\n",
 464             " *\n",
 465             " * This program is free software: you can redistribute it and/or modify\n",
 466             " * it under the terms of the GNU General Public License as published by\n",
 467             " * the Free Software Foundation, either version 3 of the License, or\n",
 468             " * (at your option) any later version.\n",
 469             " *\n",
 470             " * This program is distributed in the hope that it will be useful,\n",
 471             " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
 472             " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n",
 473             " * GNU General Public License for more details.\n",
 474             " *\n",
 475             " * You should have received a copy of the GNU General Public License\n",
 476             " * along with this program.  If not, see <http://www.gnu.org/licenses/>.\n",
 477             " */\n");
 478
 479
 480 push(@h, @generated, @gpl,
 481      "#ifndef CLIENT_STUBS_H\n",
 482      "#define CLIENT_STUBS_H\n",
 483      "/** \@file lib/client-stubs.h\n",
 484      " * \@brief Generated client API\n",
 485      " *\n",
 486      " * Don't include this file directly - use \@ref lib/client.h instead.\n",
 487      " */\n",
 488      "\n");
 489
 490 push(@c, @generated, @gpl,
 491      "/** \@file lib/client-stubs.c\n",
 492      " * \@brief Generated client API implementation\n",
 493      " */\n",
 494      "\n");
 495
 496 push(@ah, @generated, @gpl,
 497      "#ifndef ECLIENT_STUBS_H\n",
 498      "#define ECLIENT_STUBS_H\n",
 499      "/** \@file lib/client-stubs.h\n",
 500      " * \@brief Generated asynchronous client API\n",
 501      " *\n",
 502      " * Don't include this file directly - use \@ref lib/eclient.h instead.\n",
 503      " */\n",
 504      "\n");
 505
 506 push(@ac, @generated, @gpl,
 507      "/** \@file lib/client-stubs.c\n",
 508      " * \@brief Generated asynchronous client API implementation\n",
 509      " */\n",
 510      "\n");
 511
 512 # The protocol ----------------------------------------------------------------
 513
 514 simple("adopt",
 515        "Adopt a track",
 516        "Makes the calling user owner of a randomly picked track.",
 517        [["string", "id", "Track ID"]]);
 518
 519 simple("adduser",
 520        "Create a user",
 521        "Create a new user.  Requires the 'admin' right.  Email addresses etc must be filled in in separate commands.",
 522        [["string", "user", "New username"],
 523         ["string", "password", "Initial password"],
 524         ["string", "rights", "Initial rights (optional)"]]);
 525
 526 simple("allfiles",
 527        "List files and directories in a directory",
 528        "See 'files' and 'dirs' for more specific lists.",
 529        [["string", "dir", "Directory to list (optional)"],
 530         ["string", "re", "Regexp that results must match (optional)"]],
 531        [["body", "files", "List of matching files and directories"]]);
 532
 533 simple("confirm",
 534        "Confirm registration",
 535        "The confirmation string must have been created with 'register'.  The username is returned so the caller knows who they are.",
 536        [["string", "confirmation", "Confirmation string"]],
 537        [["user"]]);
 538
 539 simple("cookie",
 540        "Log in with a cookie",
 541        "The cookie must have been created with 'make-cookie'.  The username is returned so the caller knows who they are.",
 542        [["string", "cookie", "Cookie string"]],
 543        [["user"]]);
 544
 545 simple("deluser",
 546        "Delete user",
 547        "Requires the 'admin' right.",
 548        [["string", "user", "User to delete"]]);
 549
 550 simple("dirs",
 551        "List directories in a directory",
 552        "",
 553        [["string", "dir", "Directory to list (optional)"],
 554         ["string", "re", "Regexp that results must match (optional)"]],
 555        [["body", "files", "List of matching directories"]]);
 556
 557 simple("disable",
 558        "Disable play",
 559        "Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.",
 560        []);
 561
 562 simple("edituser",
 563        "Set a user property",
 564        "With the 'admin' right you can do anything.  Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.",
 565        [["string", "username", "User to modify"],
 566         ["string", "property", "Property name"],
 567         ["string", "value", "New property value"]]);
 568
 569 simple("enable",
 570        "Enable play",
 571        "Requires the 'global prefs' right.",
 572        []);
 573
 574 simple("enabled",
 575        "Detect whether play is enabled",
 576        "",
 577        [],
 578        [["boolean", "enabled", "1 if play is enabled and 0 otherwise"]]);
 579
 580 simple("exists",
 581        "Test whether a track exists",
 582        "",
 583        [["string", "track", "Track name"]],
 584        [["boolean", "exists", "1 if the track exists and 0 otherwise"]]);
 585
 586 simple("files",
 587        "List files in a directory",
 588        "",
 589        [["string", "dir", "Directory to list (optional)"],
 590         ["string", "re", "Regexp that results must match (optional)"]],
 591        [["body", "files", "List of matching files"]]);
 592
 593 simple("get",
 594        "Get a track preference",
 595        "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.",
 596        [["string", "track", "Track name"],
 597         ["string", "pref", "Preference name"]],
 598        [["string", "value", "Preference value"]]);
 599
 600 simple("get-global",
 601        "Get a global preference",
 602        "If the preference does exist not then a null value is returned.",
 603        [["string", "pref", "Global preference name"]],
 604        [["string", "value", "Preference value"]]);
 605
 606 simple("length",
 607        "Get a track's length",
 608        "If the track does not exist an error is returned.",
 609        [["string", "track", "Track name"]],
 610        [["integer", "length", "Track length in seconds"]]);
 611
 612 # TODO log
 613
 614 simple("make-cookie",
 615        "Create a login cookie for this user",
 616        "The cookie may be redeemed via the 'cookie' command",
 617        [],
 618        [["string", "cookie", "Newly created cookie"]]);
 619
 620 simple("move",
 621        "Move a track",
 622        "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
 623        [["string", "track", "Track ID or name"],
 624         ["integer", "delta", "How far to move the track towards the head of the queue"]]);
 625
 626 simple("moveafter",
 627        "Move multiple tracks",
 628        "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
 629        [["string", "target", "Move after this track, or to head if \"\""],
 630         ["list", "ids", "List of tracks to move by ID"]]);
 631
 632 simple(["new", "new_tracks"],
 633        "List recently added tracks",
 634        "",
 635        [["integer", "max", "Maximum tracks to fetch, or 0 for all available"]],
 636        [["body", "tracks", "Recently added tracks"]]);
 637
 638 simple("nop",
 639        "Do nothing",
 640        "Used as a keepalive.  No authentication required.",
 641        []);
 642
 643 simple("part",
 644        "Get a track name part",
 645        "If the name part cannot be constructed an empty string is returned.",
 646        [["string", "track", "Track name"],
 647         ["string", "context", "Context (\"sort\" or \"display\")"],
 648         ["string", "part", "Name part (\"artist\", \"album\" or \"title\")"]],
 649        [["string", "part", "Value of name part"]]);
 650
 651 simple("pause",
 652        "Pause the currently playing track",
 653        "Requires the 'pause' right.",
 654        []);
 655
 656 simple("play",
 657        "Play a track",
 658        "Requires the 'play' right.",
 659        [["string", "track", "Track to play"]],
 660        [["string-raw", "id", "Queue ID of new track"]]);
 661
 662 simple("playafter",
 663        "Play multiple tracks",
 664        "Requires the 'play' right.",
 665        [["string", "target", "Insert into queue after this track, or at head if \"\""],
 666         ["list", "tracks", "List of track names to play"]]);
 667
 668 simple("playing",
 669        "Retrieve the playing track",
 670        "",
 671        [],
 672        [["queue-one", "playing", "Details of the playing track"]]);
 673
 674 simple("playlist-delete",
 675        "Delete a playlist",
 676        "Requires the 'play' right and permission to modify the playlist.",
 677        [["string", "playlist", "Playlist to delete"]]);
 678
 679 simple("playlist-get",
 680        "List the contents of a playlist",
 681        "Requires the 'read' right and oermission to read the playlist.",
 682        [["string", "playlist", "Playlist name"]],
 683        [["body", "tracks", "List of tracks in playlist"]]);
 684
 685 simple("playlist-get-share",
 686        "Get a playlist's sharing status",
 687        "Requires the 'read' right and permission to read the playlist.",
 688        [["string", "playlist", "Playlist to read"]],
 689        [["string-raw", "share", "Sharing status (\"public\", \"private\" or \"shared\")"]]);
 690
 691 simple("playlist-lock",
 692        "Lock a playlist",
 693        "Requires the 'play' right and permission to modify the playlist.  A given connection may lock at most one playlist.",
 694        [["string", "playlist", "Playlist to delete"]]);
 695
 696 simple("playlist-set",
 697        "Set the contents of a playlist",
 698        "Requires the 'play' right and permission to modify the playlist, which must be locked.",
 699        [["string", "playlist", "Playlist to modify"],
 700         ["body", "tracks", "New list of tracks for playlist"]]);
 701
 702 simple("playlist-set-share",
 703        "Set a playlist's sharing status",
 704        "Requires the 'play' right and permission to modify the playlist.",
 705        [["string", "playlist", "Playlist to modify"],
 706         ["string", "share", "New sharing status (\"public\", \"private\" or \"shared\")"]]);
 707
 708 simple("playlist-unlock",
 709        "Unlock the locked playlist playlist",
 710        "The playlist to unlock is implicit in the connection.",
 711        []);
 712
 713 simple("playlists",
 714        "List playlists",
 715        "Requires the 'read' right.  Only playlists that you have permission to read are returned.",
 716        [],
 717        [["body", "playlists", "Playlist names"]]);
 718
 719 simple("prefs",
 720        "Get all the preferences for a track",
 721        "",
 722        [["string", "track", "Track name"]],
 723        [["pair-list", "prefs", "Track preferences"]]);
 724
 725 simple("queue",
 726        "List the queue",
 727        "",
 728        [],
 729        [["queue", "queue", "Current queue contents"]]);
 730
 731 simple("random-disable",
 732        "Disable random play",
 733        "Requires the 'global prefs' right.",
 734        []);
 735
 736 simple("random-enable",
 737        "Enable random play",
 738        "Requires the 'global prefs' right.",
 739        []);
 740
 741 simple("random-enabled",
 742        "Detect whether random play is enabled",
 743        "Random play counts as enabled even if play is disabled.",
 744        [],
 745        [["boolean", "enabled", "1 if random play is enabled and 0 otherwise"]]);
 746
 747 simple("recent",
 748        "List recently played tracks",
 749        "",
 750        [],
 751        [["queue", "recent", "Recently played tracks"]]);
 752
 753 simple("reconfigure",
 754        "Re-read configuraiton file.",
 755        "Requires the 'admin' right.",
 756        []);
 757
 758 simple("register",
 759        "Register a new user",
 760        "Requires the 'register' right which is usually only available to the 'guest' user.  Redeem the confirmation string via 'confirm' to complete registration.",
 761        [["string", "username", "Requested new username"],
 762         ["string", "password", "Requested initial password"],
 763         ["string", "email", "New user's email address"]],
 764        [["string", "confirmation", "Confirmation string"]]);
 765
 766 simple("reminder",
 767        "Send a password reminder.",
 768        "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.",
 769        [["string", "username", "User to remind"]]);
 770
 771 simple("remove",
 772        "Remove a track form the queue.",
 773        "Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.",
 774        [["string", "id", "Track ID"]]);
 775
 776 simple("rescan",
 777        "Rescan all collections for new or obsolete tracks.",
 778        "Requires the 'rescan' right.",
 779        []);     # TODO wait/fresh flags
 780
 781 simple("resolve",
 782        "Resolve a track name",
 783        "Converts aliases to non-alias track names",
 784        [["string", "track", "Track name (might be an alias)"]],
 785        [["string", "resolved", "Resolve track name (definitely not an alias)"]]);
 786
 787 simple("resume",
 788        "Resume the currently playing track",
 789        "Requires the 'pause' right.",
 790        []);
 791
 792 simple("revoke",
 793        "Revoke a cookie.",
 794        "It will not subsequently be possible to log in with the cookie.",
 795        []);
 796
 797 simple("rtp-address",
 798        "Get the server's RTP address information",
 799        "",
 800        [],
 801        [["string", "address", "Where to store hostname or address"],
 802         ["string", "port", "Where to store service name or port number"]]);
 803
 804 simple("rtp-cancel",
 805        "Cancel RTP stream",
 806        "",
 807        []);
 808
 809 simple("rtp-request",
 810        "Request a unicast RTP stream",
 811        "",
 812        [["string", "address", "Destination address"],
 813         ["string", "port", "Destination port number"]]);
 814
 815 simple("scratch",
 816        "Terminate the playing track.",
 817        "Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.",
 818        [["string", "id", "Track ID (optional)"]]);
 819
 820 simple(["schedule-add", "schedule_add_play"],
 821        "Schedule a track to play in the future",
 822        "",
 823        [["time", "when", "When to play the track"],
 824         ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
 825         ["literal", "play", ""],
 826         ["string", "track", "Track to play"]]);
 827
 828 simple(["schedule-add", "schedule_add_set_global"],
 829        "Schedule a global setting to be changed in the future",
 830        "",
 831        [["time", "when", "When to change the setting"],
 832         ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
 833         ["literal", "set-global", ""],
 834         ["string", "pref", "Global preference to set"],
 835         ["string", "value", "New value of global preference"]]);
 836
 837 simple(["schedule-add", "schedule_add_unset_global"],
 838        "Schedule a global setting to be unset in the future",
 839        "",
 840        [["time", "when", "When to change the setting"],
 841         ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
 842         ["literal", "set-global", ""],
 843         ["string", "pref", "Global preference to set"]]);
 844
 845 simple("schedule-del",
 846        "Delete a scheduled event.",
 847        "Users can always delete their own scheduled events; with the admin right you can delete any event.",
 848        [["string", "event", "ID of event to delete"]]);
 849
 850 simple("schedule-get",
 851        "Get the details of scheduled event",
 852        "",
 853        [["string", "id", "Event ID"]],
 854        [["pair-list", "actiondata", "Details of event"]]);
 855
 856 simple("schedule-list",
 857        "List scheduled events",
 858        "This just lists IDs.  Use 'schedule-get' to retrieve more detail",
 859        [],
 860        [["body", "ids", "List of event IDs"]]);
 861
 862 simple("search",
 863        "Search for tracks",
 864        "Terms are either keywords or tags formatted as 'tag:TAG-NAME'.",
 865        [["string", "terms", "List of search terms"]],
 866        [["body", "tracks", "List of matching tracks"]]);
 867
 868 simple("set",
 869        "Set a track preference",
 870        "Requires the 'prefs' right.",
 871        [["string", "track", "Track name"],
 872         ["string", "pref", "Preference name"],
 873         ["string", "value", "New value"]]);
 874
 875 simple("set-global",
 876        "Set a global preference",
 877        "Requires the 'global prefs' right.",
 878        [["string", "pref", "Preference name"],
 879         ["string", "value", "New value"]]);
 880
 881 simple("shutdown",
 882        "Request server shutdown",
 883        "Requires the 'admin' right.",
 884        []);
 885
 886 simple("stats",
 887        "Get server statistics",
 888        "The details of what the server reports are not really defined.  The returned strings are intended to be printed out one to a line.",
 889        [],
 890        [["body", "stats", "List of server information strings."]]);
 891
 892 simple("tags",
 893        "Get a list of known tags",
 894        "Only tags which apply to at least one track are returned.",
 895        [],
 896        [["body", "tags", "List of tags"]]);
 897
 898 simple("unset",
 899        "Unset a track preference",
 900        "Requires the 'prefs' right.",
 901        [["string", "track", "Track name"],
 902         ["string", "pref", "Preference name"]]);
 903
 904 simple("unset-global",
 905        "Set a global preference",
 906        "Requires the 'global prefs' right.",
 907        [["string", "pref", "Preference name"]]);
 908
 909 # 'user' only used for authentication
 910
 911 simple("userinfo",
 912        "Get a user property.",
 913        "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.",
 914        [["string", "username", "User to read"],
 915         ["string", "property", "Property to read"]],
 916        [["string", "value", "Value of property"]]);
 917
 918 simple("users",
 919        "Get a list of users",
 920        "",
 921        [],
 922        [["body", "users", "List of users"]]);
 923
 924 simple("version",
 925        "Get the server version",
 926        "",
 927        [],
 928        [["string", "version", "Server version string"]]);
 929
 930 simple(["volume", "set_volume"],
 931        "Set the volume",
 932        "",
 933        [["integer", "left", "Left channel volume"],
 934         ["integer", "right", "Right channel volume"]]);
 935
 936 simple(["volume", "get_volume"],
 937        "Get the volume",
 938        "",
 939        [],
 940        [["integer", "left", "Left channel volume"],
 941         ["integer", "right", "Right channel volume"]]);
 942
 943 # End matter ------------------------------------------------------------------
 944
 945 push(@h, "#endif\n");
 946
 947 push(@ah, "#endif\n");
 948
 949 # Write it all out ------------------------------------------------------------
 950
 951 Write("lib/client-stubs.h", \@h);
 952 Write("lib/client-stubs.c", \@c);
 953
 954 Write("lib/eclient-stubs.h", \@ah);
 955 Write("lib/eclient-stubs.c", \@ac);
 956
 957 if(scalar @missing) {
 958   print "Missing:\n";
 959   print map("  $_\n", @missing);
 960 }