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