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