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