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