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