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