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_string_command(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],)
  39 #
  40 # Response is simply success/failure
  41 sub simple_string_command {
  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 # TODO other command classes
  78
  79 # Front matter ----------------------------------------------------------------
  80
  81 our @gpl = ("/*\n",
  82             " * This file is part of DisOrder.\n",
  83             " * Copyright (C) 2010 Richard Kettlewell\n",
  84             " *\n",
  85             " * This program is free software: you can redistribute it and/or modify\n",
  86             " * it under the terms of the GNU General Public License as published by\n",
  87             " * the Free Software Foundation, either version 3 of the License, or\n",
  88             " * (at your option) any later version.\n",
  89             " *\n",
  90             " * This program is distributed in the hope that it will be useful,\n",
  91             " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
  92             " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n",
  93             " * GNU General Public License for more details.\n",
  94             " *\n",
  95             " * You should have received a copy of the GNU General Public License\n",
  96             " * along with this program.  If not, see <http://www.gnu.org/licenses/>.\n",
  97             " */\n");
  98
  99
 100 push(@h, @gpl,
 101      "#ifndef CLIENT_STUBS_H\n",
 102      "#define CLIENT_STUBS_H\n",
 103      "\n");
 104
 105 push(@c, @gpl,
 106      "\n");
 107
 108 # The protocol ----------------------------------------------------------------
 109
 110 simple_string_command("adopt",
 111                       "Adopt a track",
 112                       "Makes the calling user owner of a randomly picked track.",
 113                       [["id", "Track ID"]]);
 114
 115 simple_string_command("adduser",
 116                       "Create a user",
 117                       "Create a new user.  Requires the 'admin' right.  Email addresses etc must be filled in in separate commands.",
 118                       [["user", "New username"],
 119                        ["password", "Initial password"],
 120                        ["rights", "Initial rights (optional)"]]);
 121
 122 # TODO allfiles
 123
 124 simple_string_command("confirm",
 125                       "Confirm user registration",
 126                       "The confirmation string is as returned by the register command.",
 127                       [["confirmation", "Confirmnation string"]]);
 128
 129 # TODO cookie
 130
 131 simple_string_command("deluser",
 132                       "Delete user",
 133                       "Requires the 'admin' right.",
 134                       [["user", "User to delete"]]);
 135
 136 # TODO dirs
 137
 138 simple_string_command("disable",
 139                       "Disable play",
 140                       "Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.",
 141                       []);
 142
 143 simple_string_command("edituser",
 144                       "Set a user property",
 145                       "With the 'admin' right you can do anything.  Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.",
 146                       [["username", "User to modify"],
 147                        ["property", "Property name"],
 148                        ["value", "New property value"]]);
 149
 150 simple_string_command("enable",
 151                       "Enable play",
 152                       "Requires the 'global prefs' right.",
 153                       []);
 154
 155 # TODO enabled
 156
 157 # TODO exists
 158
 159 # TODO files
 160
 161 # TODO get
 162
 163 # TODO get-global
 164
 165 # TODO length
 166
 167 # TODO log
 168
 169 # TODO make-cookie
 170
 171 # TODO move
 172
 173 # TODO moveafter
 174
 175 # TODO new
 176
 177 simple_string_command("nop",
 178                       "Do nothing",
 179                       "Used as a keepalive.  No authentication required.",
 180                       []);
 181
 182 # TODO part
 183
 184 simple_string_command("pause",
 185                       "Pause the currently playing track",
 186                       "Requires the 'pause' right.",
 187                       []);
 188
 189 # TODO playafter
 190
 191 # TODO playing
 192
 193 simple_string_command("playlist-delete",
 194                       "Delete a playlist",
 195                       "Requires the 'play' right and permission to modify the playlist.",
 196                       [["playlist", "Playlist to delete"]]);
 197
 198 # TODO playlist-get
 199
 200 # TODO playlist-get-share
 201
 202 simple_string_command("playlist-lock",
 203                       "Lock a playlist",
 204                       "Requires the 'play' right and permission to modify the playlist.  A given connection may lock at most one playlist.",
 205                       [["playlist", "Playlist to delete"]]);
 206
 207 # TODO playlist-set
 208
 209 simple_string_command("playlist-set-share",
 210                       "Set a playlist's sharing status",
 211                       "Requires the 'play' right and permission to modify the playlist.  ",
 212                       [["playlist", "Playlist to modify"],
 213                        ["share", "New sharing status ('public', 'private' or 'shared')"]]);
 214
 215 simple_string_command("playlist-unlock",
 216                       "Unlock the locked playlist playlist",
 217                       "The playlist to unlock is implicit in the connection.",
 218                       []);
 219
 220 # TODO playlists
 221
 222 # TODO prefs
 223
 224 # TODO queue
 225
 226 simple_string_command("random-disable",
 227                       "Disable random play",
 228                       "Requires the 'global prefs' right.",
 229                       []);
 230
 231 simple_string_command("random-enable",
 232                       "Enable random play",
 233                       "Requires the 'global prefs' right.",
 234                       []);
 235
 236 # TODO random-enabled
 237
 238 # TODO recent
 239
 240 simple_string_command("reconfigure",
 241                       "Re-read configuraiton file.",
 242                       "Requires the 'admin' right.",
 243                       []);
 244
 245 # TODO register
 246
 247 simple_string_command("reminder",
 248                       "Send a password reminder.",
 249                       "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.",
 250                       [["username", "User to remind"]]);
 251
 252 simple_string_command("remove",
 253                       "Remove a track form the queue.",
 254                       "Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.",
 255                       [["id", "Track ID"]]);
 256
 257 simple_string_command("rescan",
 258                       "Rescan all collections for new or obsolete tracks.",
 259                       "Requires the 'rescan' right.",
 260                       []);      # TODO wait/fresh flags
 261
 262 # TODO resolve
 263
 264 simple_string_command("resume",
 265                       "Resume the currently playing track",
 266                       "Requires the 'pause' right.",
 267                       []);
 268
 269 simple_string_command("revoke",
 270                       "Revoke a cookie.",
 271                       "It will not subsequently be possible to log in with the cookie..",
 272                       [["cookie", "Cookie to revoke"]]);
 273
 274 # TODO rtp-address
 275
 276 simple_string_command("scratch",
 277                       "Terminate the playing track.",
 278                       "Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.",
 279                       [["id", "Track ID (optional)"]]);
 280
 281 # TODO schedule-add
 282
 283 simple_string_command("schedule-del",
 284                       "Delete a scheduled event.",
 285                       "Users can always delete their own scheduled events; with the admin right you can delete any event.",
 286                       [["event", "ID of event to delete"]]);
 287
 288 # TODO schedule-get
 289
 290 # TODO schedule-list
 291
 292 # TODO search
 293
 294 simple_string_command("set",
 295                       "Set a track preference",
 296                       "Requires the 'prefs' right.",
 297                       [["track", "Track name"],
 298                        ["pref", "Preference name"],
 299                        ["value", "New value"]]);
 300
 301 simple_string_command("set-global",
 302                       "Set a global preference",
 303                       "Requires the 'global prefs' right.",
 304                       [["pref", "Preference name"],
 305                        ["value", "New value"]]);
 306
 307 # TODO stats
 308
 309 # TODO tags
 310
 311 simple_string_command("unset",
 312                       "Unset a track preference",
 313                       "Requires the 'prefs' right.",
 314                       [["track", "Track name"],
 315                        ["pref", "Preference name"]]);
 316
 317 simple_string_command("unset-global",
 318                       "Set a global preference",
 319                       "Requires the 'global prefs' right.",
 320                       [["pref", "Preference name"]]);
 321
 322 # user is only used by connect functions
 323
 324 # TODO userinfo
 325
 326 # TODO users
 327
 328 # TODO version
 329
 330 # TODO volume
 331
 332 # End matter ------------------------------------------------------------------
 333
 334 push(@h, "#endif\n");
 335
 336 # Write it all out ------------------------------------------------------------
 337
 338 Write("client-stubs.h", \@h);
 339 Write("client-stubs.c", \@c);