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

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