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 yes/no or failure
  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(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...])
 121 #
 122 # Response is yes/no or failure
 123 sub string_login {
 124     my $cmd = shift;
 125     my $summary = shift;
 126     my $detail = shift;
 127     my $args = shift;
 128     my $return = shift;
 129
 130     my $cmdc = $cmd;
 131     $cmdc =~ s/-/_/g;
 132     # Synchronous C API
 133     push(@h, "/** \@brief $summary\n",
 134          " *\n",
 135          " * $detail\n",
 136          " *\n",
 137          map(" * \@param $_->[0] $_->[1]\n", @$args),
 138          " * \@return 0 on success, non-0 on error\n",
 139          " */\n",
 140          "int disorder_$cmdc(disorder_client *c",
 141          map(", const char *$_->[0]", @$args),
 142          ");\n");
 143     push(@c, "int disorder_$cmdc(disorder_client *c",
 144          map(", const char *$_->[0]", @$args),
 145          ") {\n",
 146          "  char *u;\n",
 147          "  int rc;\n",
 148          "  if((rc = disorder_simple(c, &u, \"$cmd\"",
 149          map(", $_->[0]", @$args),
 150          "  )))\n",
 151          "    return rc;\n",
 152          "  c->user = u;\n",
 153          "  return 0;\n",
 154          "}\n\n");
 155
 156     # Asynchronous C API
 157     # TODO
 158
 159     # Python API
 160     # TODO
 161
 162     # Java API
 163     # TODO
 164 }
 165
 166 # boolean(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...], [RETURN, DESCR])
 167 #
 168 # Response is yes/no or failure
 169 sub boolean {
 170     my $cmd = shift;
 171     my $summary = shift;
 172     my $detail = shift;
 173     my $args = shift;
 174     my $return = shift;
 175
 176     my $cmdc = $cmd;
 177     $cmdc =~ s/-/_/g;
 178     # Synchronous C API
 179     push(@h, "/** \@brief $summary\n",
 180          " *\n",
 181          " * $detail\n",
 182          " *\n",
 183          map(" * \@param $_->[0] $_->[1]\n", @$args),
 184          " * \@param $return->[0]p $return->[1]\n",
 185          " * \@return 0 on success, non-0 on error\n",
 186          " */\n",
 187          "int disorder_$cmdc(disorder_client *c",
 188          map(", const char *$_->[0]", @$args),
 189          ", int *$return->[0]p);\n",
 190          "\n");
 191     push(@c, "int disorder_$cmdc(disorder_client *c",
 192          map(", const char *$_->[0]", @$args),
 193          ", int *$return->[0]p) {\n",
 194          "  char *v;\n",
 195          "  int rc;\n",
 196          "  if((rc = disorder_simple(c, &v, \"$cmd\"",
 197          map(", $_->[0]", @$args),
 198          ", (char *)0)))\n",
 199          "    return rc;\n",
 200          "  return boolean(\"$cmd\", v, $return->[0]p);\n",
 201          "}\n\n");
 202
 203     # Asynchronous C API
 204     # TODO
 205
 206     # Python API
 207     # TODO
 208
 209     # Java API
 210     # TODO
 211 }
 212
 213 # TODO other command classes
 214
 215 # Front matter ----------------------------------------------------------------
 216
 217 our @gpl = ("/*\n",
 218             " * This file is part of DisOrder.\n",
 219             " * Copyright (C) 2010 Richard Kettlewell\n",
 220             " *\n",
 221             " * This program is free software: you can redistribute it and/or modify\n",
 222             " * it under the terms of the GNU General Public License as published by\n",
 223             " * the Free Software Foundation, either version 3 of the License, or\n",
 224             " * (at your option) any later version.\n",
 225             " *\n",
 226             " * This program is distributed in the hope that it will be useful,\n",
 227             " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
 228             " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n",
 229             " * GNU General Public License for more details.\n",
 230             " *\n",
 231             " * You should have received a copy of the GNU General Public License\n",
 232             " * along with this program.  If not, see <http://www.gnu.org/licenses/>.\n",
 233             " */\n");
 234
 235
 236 push(@h, @gpl,
 237      "#ifndef CLIENT_STUBS_H\n",
 238      "#define CLIENT_STUBS_H\n",
 239      "\n");
 240
 241 push(@c, @gpl,
 242      "\n");
 243
 244 # The protocol ----------------------------------------------------------------
 245
 246 simple("adopt",
 247        "Adopt a track",
 248        "Makes the calling user owner of a randomly picked track.",
 249        [["id", "Track ID"]]);
 250
 251 simple("adduser",
 252        "Create a user",
 253        "Create a new user.  Requires the 'admin' right.  Email addresses etc must be filled in in separate commands.",
 254        [["user", "New username"],
 255         ["password", "Initial password"],
 256         ["rights", "Initial rights (optional)"]]);
 257
 258 # TODO allfiles
 259
 260 string_login("confirm",
 261              "Confirm registration",
 262              "The confirmation string must have been created with 'register'.  The username is returned so the caller knows who they are.",
 263              [["confirmation", "Confirmation string"]]);
 264 #TODO update docs - this logs you in
 265
 266 string_login("cookie",
 267              "Log in with a cookie",
 268              "The cookie must have been created with 'make-cookie'.  The username is returned so the caller knows who they are.",
 269              [["cookie", "Cookie string"]]);
 270
 271 simple("deluser",
 272        "Delete user",
 273        "Requires the 'admin' right.",
 274        [["user", "User to delete"]]);
 275
 276 # TODO dirs
 277
 278 simple("disable",
 279        "Disable play",
 280        "Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.",
 281        []);
 282
 283 simple("edituser",
 284        "Set a user property",
 285        "With the 'admin' right you can do anything.  Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.",
 286        [["username", "User to modify"],
 287         ["property", "Property name"],
 288         ["value", "New property value"]]);
 289
 290 simple("enable",
 291        "Enable play",
 292        "Requires the 'global prefs' right.",
 293        []);
 294
 295 boolean("enabled",
 296         "Detect whether play is enabled",
 297         "",
 298         [],
 299         ["enabled", "1 if play is enabled and 0 otherwise"]);
 300
 301 boolean("exists",
 302         "Test whether a track exists",
 303         "",
 304         [["track", "Track name"]],
 305         ["exists", "1 if the track exists and 0 otherwise"]);
 306
 307 # TODO files
 308
 309 string("get",
 310        "Get a track preference",
 311        "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.",
 312        [["track", "Track name"],
 313         ["pref", "Preference name"]],
 314        ["value", "Preference value"]);
 315
 316 string("get-global",
 317        "Get a global preference",
 318        "If the preference does exist not then a null value is returned.",
 319        [["pref", "Global preference name"]],
 320        ["value", "Preference value"]);
 321
 322 # TODO length
 323
 324 # TODO log
 325
 326 string("make-cookie",
 327        "Create a login cookie for this user",
 328        "The cookie may be redeemed via the 'cookie' command",
 329        [],
 330        ["cookie", "Newly created cookie"]);
 331
 332 # TODO move
 333
 334 # TODO moveafter
 335
 336 # TODO new
 337
 338 simple("nop",
 339        "Do nothing",
 340        "Used as a keepalive.  No authentication required.",
 341        []);
 342
 343 string("part",
 344        "Get a track name part",
 345        "If the name part cannot be constructed an empty string is returned.",
 346        [["track", "Track name"],
 347         ["context", "Context (\"sort\" or \"display\")"],
 348         ["part", "Name part (\"artist\", \"album\" or \"title\")"]],
 349        ["part", "Value of name part"]);
 350
 351 simple("pause",
 352        "Pause the currently playing track",
 353        "Requires the 'pause' right.",
 354        []);
 355
 356 # TODO playafter
 357
 358 # TODO playing
 359
 360 simple("playlist-delete",
 361        "Delete a playlist",
 362        "Requires the 'play' right and permission to modify the playlist.",
 363        [["playlist", "Playlist to delete"]]);
 364
 365 # TODO playlist-get
 366
 367 # TODO playlist-get-share
 368
 369 simple("playlist-lock",
 370        "Lock a playlist",
 371        "Requires the 'play' right and permission to modify the playlist.  A given connection may lock at most one playlist.",
 372        [["playlist", "Playlist to delete"]]);
 373
 374 string("playlist-get-share",
 375        "Get a playlist's sharing status",
 376        "Requires the 'read' right and permission to read the playlist.",
 377        [["playlist", "Playlist to read"]],
 378        ["share", "Sharing status (\"public\", \"private\" or \"shared\")"]);
 379
 380 simple("playlist-set-share",
 381        "Set a playlist's sharing status",
 382        "Requires the 'play' right and permission to modify the playlist.",
 383        [["playlist", "Playlist to modify"],
 384         ["share", "New sharing status (\"public\", \"private\" or \"shared\")"]]);
 385
 386 simple("playlist-unlock",
 387        "Unlock the locked playlist playlist",
 388        "The playlist to unlock is implicit in the connection.",
 389        []);
 390
 391 # TODO playlists
 392
 393 # TODO prefs
 394
 395 # TODO queue
 396
 397 simple("random-disable",
 398        "Disable random play",
 399        "Requires the 'global prefs' right.",
 400        []);
 401
 402 simple("random-enable",
 403        "Enable random play",
 404        "Requires the 'global prefs' right.",
 405        []);
 406
 407 boolean("random-enabled",
 408         "Detect whether random play is enabled",
 409         "Random play counts as enabled even if play is disabled.",
 410         [],
 411         ["enabled", "1 if random play is enabled and 0 otherwise"]);
 412
 413 # TODO recent
 414
 415 simple("reconfigure",
 416        "Re-read configuraiton file.",
 417        "Requires the 'admin' right.",
 418        []);
 419
 420 string("register",
 421        "Register a new user",
 422        "Requires the 'register' right which is usually only available to the 'guest' user.  Redeem the confirmation string via 'confirm' to complete registration.",
 423        [["username", "Requested new username"],
 424         ["password", "Requested initial password"],
 425         ["email", "New user's email address"]],
 426        ["confirmation", "Confirmation string"]);
 427
 428 simple("reminder",
 429        "Send a password reminder.",
 430        "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.",
 431        [["username", "User to remind"]]);
 432
 433 simple("remove",
 434        "Remove a track form the queue.",
 435        "Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.",
 436        [["id", "Track ID"]]);
 437
 438 simple("rescan",
 439        "Rescan all collections for new or obsolete tracks.",
 440        "Requires the 'rescan' right.",
 441        []);     # TODO wait/fresh flags
 442
 443 string("resolve",
 444        "Resolve a track name",
 445        "Converts aliases to non-alias track names",
 446        [["track", "Track name (might be an alias)"]],
 447        ["resolved", "Resolve track name (definitely not an alias)"]);
 448
 449 simple("resume",
 450        "Resume the currently playing track",
 451        "Requires the 'pause' right.",
 452        []);
 453
 454 simple("revoke",
 455        "Revoke a cookie.",
 456        "It will not subsequently be possible to log in with the cookie.",
 457        []);                     # TODO fix docs!
 458
 459 # TODO rtp-address
 460
 461 simple("scratch",
 462        "Terminate the playing track.",
 463        "Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.",
 464        [["id", "Track ID (optional)"]]);
 465
 466 # TODO schedule-add
 467
 468 simple("schedule-del",
 469        "Delete a scheduled event.",
 470        "Users can always delete their own scheduled events; with the admin right you can delete any event.",
 471        [["event", "ID of event to delete"]]);
 472
 473 # TODO schedule-get
 474
 475 # TODO schedule-list
 476
 477 # TODO search
 478
 479 simple("set",
 480        "Set a track preference",
 481        "Requires the 'prefs' right.",
 482        [["track", "Track name"],
 483         ["pref", "Preference name"],
 484         ["value", "New value"]]);
 485
 486 simple("set-global",
 487        "Set a global preference",
 488        "Requires the 'global prefs' right.",
 489        [["pref", "Preference name"],
 490         ["value", "New value"]]);
 491
 492 # TODO shutdown (also needs documenting)
 493
 494 # TODO stats
 495
 496 # TODO tags
 497
 498 simple("unset",
 499        "Unset a track preference",
 500        "Requires the 'prefs' right.",
 501        [["track", "Track name"],
 502         ["pref", "Preference name"]]);
 503
 504 simple("unset-global",
 505        "Set a global preference",
 506        "Requires the 'global prefs' right.",
 507        [["pref", "Preference name"]]);
 508
 509 # TODO user?
 510
 511 string("userinfo",
 512        "Get a user property.",
 513        "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.",
 514        [["username", "User to read"],
 515         ["property", "Property to read"]],
 516        ["value", "Value of property"]);
 517
 518 # TODO users
 519
 520 string("version",
 521        "Get the server version",
 522        "",
 523        [],
 524        ["version", "Server version string"]);
 525
 526 # TODO volume
 527
 528 # End matter ------------------------------------------------------------------
 529
 530 push(@h, "#endif\n");
 531
 532 # Write it all out ------------------------------------------------------------
 533
 534 Write("lib/client-stubs.h", \@h);
 535 Write("lib/client-stubs.c", \@c);