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