protogen: The bulk of the eclient code generation.
[disorder] / scripts / protocol
1 #! /usr/bin/perl -w
2 #
3 # This file is part of DisOrder.
4 # Copyright (C) 2010-11 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 # This file contains the definition of the disorder protocol, plus
22 # code to generates stubs for it in the various supported languages.
23 #
24 # At the time of writing it is a work in progress!
25
26 #
27 # Types:
28 #
29 # string A (Unicode) string.
30 # string-raw A string that is not subject to de-quoting (return only)
31 # integer An integer. Decimal on the wire.
32 # time A timestamp. Decimal on the wire.
33 # boolean True or false. "yes" or "no" on the wire.
34 # list In commands: a list of strings in the command.
35 # In returns: a list of lines in the response.
36 # pair-list In returns: a list of key-value pairs in a response body.
37 # body In commands: a list of strings as a command body.
38 # In returns: a list of strings as a response body.
39 # queue In returns: a list of queue entries in a response body.
40 # queue-one In returns: a queue entry in the response.
41 # literal Constant string sent in sequence
42 #
43
44 # Variables and utilities -----------------------------------------------------
45
46 our @h = ();
47 our @c = ();
48 our @ah = ();
49 our @ac = ();
50 our @missing = ();
51
52 # Mapping of return type sequences to eclient callbacks
53 our @eclient_return = (
54 ["no_response" => []],
55 ["string_response" => ["string"]],
56 ["string_response" => ["string-raw"]],
57 ["integer_response" => ["integer"]],
58 ["integer_response" => ["boolean"]],
59 ["time_response" => ["time"]],
60 ["pair_integer_response" => ["integer", "integer"]],
61 ["queue_response" => ["queue"]],
62 ["playing_response" => ["queue-one"]],
63 ["list_response" => ["body"]],
64 );
65
66 # eclient_response_matces(RETURNS, VARIANT)
67 #
68 # Return true if VARIANT matches RETURNS
69 sub eclient_response_matches {
70 my $returns = shift;
71 my $variant = shift;
72 my $types = $variant->[1];
73 if(scalar @$returns != scalar @$types) { return 0; }
74 for my $n (0 .. $#$returns) {
75 my $return = $returns->[$n];
76 my $type = $return->[0];
77 if($type ne $types->[$n]) { return 0; }
78 }
79 return 1;
80 }
81
82 # find_eclient_type(RETURNS)
83 #
84 # Find the result type for an eclient call
85 sub find_eclient_response {
86 my $returns = shift;
87 if(!defined $returns) {
88 $returns = [];
89 }
90 for my $variant (@eclient_return) {
91 if(eclient_response_matches($returns, $variant)) {
92 return $variant->[0];
93 }
94 }
95 return undef;
96 }
97
98 # Write(PATH, LINES)
99 #
100 # Write array ref LINES to file PATH.
101 sub Write {
102 my $path = shift;
103 my $lines = shift;
104
105 (open(F, ">$path")
106 and print F @$lines
107 and close F)
108 or die "$0: $path: $!\n";
109 }
110
111 # Command classes -------------------------------------------------------------
112
113 # c_in_decl([TYPE, NAME])
114 #
115 # Return the C declaration for an input parameter of type TYPE with
116 # name NAME.
117 sub c_in_decl {
118 my $arg = shift;
119
120 my $type = $arg->[0];
121 my $name = $arg->[1];
122 if($type eq 'string') {
123 return "const char *$name";
124 } elsif($type eq 'integer') {
125 return "long $name";
126 } elsif($type eq 'time') {
127 return "time_t $name";
128 } elsif($type eq 'list' or $type eq 'body') {
129 return ("char **$name",
130 "int n$name");
131 } elsif($type eq 'literal') {
132 return ();
133 } else {
134 die "$0: c_in_decl: unknown type '$type'\n";
135 }
136 }
137
138 # c_out_decl([TYPE, NAME])
139 #
140 # Return the C declaration for an output (reference) parameter of type
141 # TYPE with name NAME.
142 sub c_out_decl {
143 my $arg = shift;
144
145 return () unless defined $arg;
146 my $type = $arg->[0];
147 my $name = $arg->[1];
148 if($type eq 'string' or $type eq 'string-raw') {
149 return ("char **${name}p");
150 } elsif($type eq 'integer') {
151 return ("long *${name}p");
152 } elsif($type eq 'time') {
153 return ("time_t *${name}p");
154 } elsif($type eq 'boolean') {
155 return ("int *${name}p");
156 } elsif($type eq 'list' or $type eq 'body') {
157 return ("char ***${name}p",
158 "int *n${name}p");
159 } elsif($type eq 'pair-list') {
160 return ("struct kvp **${name}p");
161 } elsif($type eq 'queue' or $type eq 'queue-one') {
162 return ("struct queue_entry **${name}p");
163 } elsif($type eq 'user') {
164 return ();
165 } else {
166 die "$0: c_out_decl: unknown type '$type'\n";
167 }
168 }
169
170 # c_param_docs([TYPE, NAME})
171 #
172 # Return the doc string for a C input parameter.
173 sub c_param_docs {
174 my $args = shift;
175 my @d = ();
176 for my $arg (@$args) {
177 my $type = $arg->[0];
178 my $name = $arg->[1];
179 my $description = $arg->[2];
180 if($type eq 'body' or $type eq 'list') {
181 push(@d,
182 " * \@param $name $description\n",
183 " * \@param n$name Length of $name\n");
184 } elsif($type ne 'literal') {
185 push(@d, " * \@param $name $description\n");
186 }
187 }
188 return @d;
189 }
190
191 # c_param_docs([TYPE, NAME})
192 #
193 # Return the doc string for a C output parameter.
194 sub c_return_docs {
195 my $returns = shift;
196 return () unless defined $returns;
197 for my $return (@$returns) {
198 my $type = $return->[0];
199 my $name = $return->[1];
200 my $descr = $return->[2];
201 if($type eq 'string'
202 or $type eq 'string-raw'
203 or $type eq 'integer'
204 or $type eq 'time'
205 or $type eq 'boolean') {
206 return (" * \@param ${name}p $descr\n");
207 } elsif($type eq 'list' or $type eq 'body') {
208 return (" * \@param ${name}p $descr\n",
209 " * \@param n${name}p Number of elements in ${name}p\n");
210 } elsif($type eq 'pair-list') {
211 return (" * \@param ${name}p $descr\n");
212 } elsif($type eq 'queue' or $type eq 'queue-one') {
213 return (" * \@param ${name}p $descr\n");
214 } elsif($type eq 'user') {
215 return ();
216 } else {
217 die "$0: c_return_docs: unknown type '$type'\n";
218 }
219 }
220 }
221
222 # simple(CMD, SUMMARY, DETAIL,
223 # [[TYPE,NAME,DESCR], [TYPE,NAME,DESCR], ...],
224 # [[RETURN-TYPE, RETURN-NAME, RETURN_DESCR]])
225 #
226 # CMD is normally just the name of the command, but can
227 # be [COMMAND,FUNCTION] if the function name should differ
228 # from the protocol command.
229 sub simple {
230 my $cmd = shift;
231 my $summary = shift;
232 my $detail = shift;
233 my $args = shift;
234 my $returns = shift;
235
236 my $cmdc;
237 if(ref $cmd eq 'ARRAY') {
238 $cmdc = $$cmd[1];
239 $cmd = $$cmd[0];
240 } else {
241 $cmdc = $cmd;
242 $cmdc =~ s/-/_/g;
243 }
244 print STDERR "Processing $cmd... ";
245 # C argument types and conversions
246 my @cargs = ();
247 my @conversions = ();
248 for my $arg (@$args) {
249 if($arg->[0] eq 'body' or $arg->[0] eq 'list') {
250 push(@cargs, "disorder__$arg->[0]", $arg->[1], "n$arg->[1]");
251 } elsif($arg->[0] eq 'string') {
252 push(@cargs, $arg->[1]);
253 } elsif($arg->[0] eq 'integer') {
254 push(@cargs, "buf_$arg->[1]");
255 push(@conversions,
256 " char buf_$arg->[1]\[16];\n",
257 " byte_snprintf(buf_$arg->[1], sizeof buf_$arg->[1], \"%ld\", $arg->[1]);\n");
258 } elsif($arg->[0] eq 'time') {
259 push(@cargs, "buf_$arg->[1]");
260 push(@conversions,
261 " char buf_$arg->[1]\[16];\n",
262 " byte_snprintf(buf_$arg->[1], sizeof buf_$arg->[1], \"%lld\", (long long)$arg->[1]);\n");
263 } elsif($arg->[0] eq 'literal') {
264 push(@cargs, "\"$arg->[1]\"");
265 } else {
266 die "$0: unsupported arg type '$arg->[0]' for '$cmd'\n";
267 }
268 }
269 # Synchronous C API
270 print STDERR "H ";
271 push(@h, "/** \@brief $summary\n",
272 " *\n",
273 " * $detail\n",
274 " *\n",
275 " * \@param c Client\n",
276 c_param_docs($args),
277 c_return_docs($returns),
278 " * \@return 0 on success, non-0 on error\n",
279 " */\n",
280 "int disorder_$cmdc(",
281 join(", ", "disorder_client *c",
282 map(c_in_decl($_), @$args),
283 map(c_out_decl($_), @$returns)),
284 ");\n\n");
285 print STDERR "C ";
286 push(@c, "int disorder_$cmdc(",
287 join(", ", "disorder_client *c",
288 map(c_in_decl($_), @$args),
289 map(c_out_decl($_), @$returns)),
290 ") {\n",
291 @conversions);
292 if(!defined $returns or scalar @$returns == 0) {
293 # Simple case
294 push(@c, " return disorder_simple(",
295 join(", ", "c", "NULL", "\"$cmd\"", @cargs, "(char *)NULL"),
296 ");\n");
297 } elsif(scalar @$returns == 1
298 and $returns->[0]->[0] eq 'queue-one') {
299 # Special case
300 my $return = $$returns[0];
301 push(@c, " return onequeue(c, \"$cmd\", $return->[1]p);\n");
302 } elsif(scalar @$returns == 1
303 and $returns->[0]->[0] eq 'string-raw') {
304 # Special case
305 my $return = $$returns[0];
306 push(@c, " return disorder_simple(",
307 join(", ", "c", "$return->[1]p", "\"$cmd\"", @cargs, "(char *)NULL"),
308 ");\n");
309 } elsif(scalar @$returns == 1
310 and $returns->[0]->[0] eq 'pair-list') {
311 # Special case
312 my $return = $$returns[0];
313 push(@c, " return pairlist(",
314 join(", ", "c", "$return->[1]p", "\"$cmd\"",
315 @cargs,
316 "(char *)NULL"),
317 ");\n");
318 } else {
319 my $expected = 0;
320 for(my $n = 0; $n < scalar @$returns; ++$n) {
321 my $return = $returns->[$n];
322 my $type = $return->[0];
323 my $name = $return->[1];
324 if($type eq 'string'
325 or $type eq 'boolean'
326 or $type eq 'integer'
327 or $type eq 'time'
328 or $type eq 'user') {
329 ++$expected;
330 }
331 }
332 if($expected) {
333 push(@c, " char **v;\n",
334 " int nv, rc = disorder_simple_split(",
335 join(", ",
336 "c",
337 "&v",
338 "&nv",
339 $expected,
340 "\"$cmd\"",
341 @cargs,
342 "(char *)NULL"),
343 ");\n",
344 " if(rc)\n",
345 " return rc;\n");
346 } else {
347 push(@c,
348 " int rc = disorder_simple(",
349 join(", ",
350 "c",
351 "NULL",
352 "\"$cmd\"",
353 @cargs,
354 "(char *)NULL"),
355 ");\n",
356 " if(rc)\n",
357 " return rc;\n");
358 }
359 for(my $n = 0; $n < scalar @$returns; ++$n) {
360 my $return = $returns->[$n];
361 my $type = $return->[0];
362 my $name = $return->[1];
363 if($type eq 'string') {
364 push(@c,
365 " *${name}p = v[$n];\n",
366 " v[$n] = NULL;\n");
367 } elsif($type eq 'boolean') {
368 push(@c,
369 " if(boolean(\"$cmd\", v[$n], ${name}p))\n",
370 " return -1;\n");
371 } elsif($type eq 'integer') {
372 push(@c,
373 " *${name}p = atol(v[$n]);\n");
374 } elsif($type eq 'time') {
375 push(@c,
376 " *${name}p = atoll(v[$n]);\n");
377 } elsif($type eq 'user') {
378 push(@c,
379 " c->user = v[$n];\n",
380 " v[$n] = NULL;\n");
381 } elsif($type eq 'body') {
382 push(@c,
383 " if(readlist(c, ${name}p, n${name}p))\n",
384 " return -1;\n");
385 } elsif($type eq 'queue') {
386 push(@c,
387 " if(readqueue(c, ${name}p))\n",
388 " return -1;\n");
389 } else {
390 die "$0: C API: unknown return type '$type' for '$name'\n";
391 }
392 }
393 if($expected) {
394 push(@c,
395 " free_strings(nv, v);\n");
396 }
397 push(@c, " return 0;\n");
398 }
399 push(@c, "}\n\n");
400
401 # Asynchronous C API
402 my $variant = find_eclient_response($returns);
403 if(defined $variant) {
404 print STDERR "AH ";
405 push(@ah,
406 "/** \@brief $summary\n",
407 " *\n",
408 " * $detail\n",
409 " *\n",
410 " * \@param c Client\n",
411 " * \@param completed Called upon completion\n",
412 c_param_docs($args),
413 " * \@param v Passed to \@p completed\n",
414 " * \@return 0 if the command was queued successfuly, non-0 on error\n",
415 " */\n",
416 "int disorder_eclient_$cmdc(",
417 join(", ", "disorder_eclient *c",
418 "disorder_eclient_$variant *completed",
419 map(c_in_decl($_), @$args),
420 "void *v"),
421 ");\n\n");
422
423 print STDERR "AC ";
424 push(@ac,
425 "int disorder_eclient_$cmdc(",
426 join(", ", "disorder_eclient *c",
427 "disorder_eclient_$variant *completed",
428 map(c_in_decl($_), @$args),
429 "void *v"),
430 ") {\n",
431 @conversions);
432 push(@ac, " return simple(",
433 join(", ",
434 "c",
435 "${variant}_opcallback",
436 "(void (*)())completed",
437 "v",
438 "\"$cmd\"",
439 @cargs,
440 "(char *)0"),
441 ");\n");
442 push(@ac, "}\n\n");
443 } else {
444 push(@missing, "disorder_eclient_$cmdc");
445 }
446
447 # Python API
448 # TODO
449
450 # Java API
451 # TODO
452 print STDERR "\n";
453 }
454
455 # TODO other command classes
456
457 # Front matter ----------------------------------------------------------------
458
459 our @generated = ("/*\n",
460 " * Automatically generated file, see scripts/protocol\n",
461 " *\n",
462 " * DO NOT EDIT.\n",
463 " */\n");
464
465 our @gpl = ("/*\n",
466 " * This file is part of DisOrder.\n",
467 " * Copyright (C) 2010-11 Richard Kettlewell\n",
468 " *\n",
469 " * This program is free software: you can redistribute it and/or modify\n",
470 " * it under the terms of the GNU General Public License as published by\n",
471 " * the Free Software Foundation, either version 3 of the License, or\n",
472 " * (at your option) any later version.\n",
473 " *\n",
474 " * This program is distributed in the hope that it will be useful,\n",
475 " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n",
476 " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n",
477 " * GNU General Public License for more details.\n",
478 " *\n",
479 " * You should have received a copy of the GNU General Public License\n",
480 " * along with this program. If not, see <http://www.gnu.org/licenses/>.\n",
481 " */\n");
482
483
484 push(@h, @generated, @gpl,
485 "#ifndef CLIENT_STUBS_H\n",
486 "#define CLIENT_STUBS_H\n",
487 "\n");
488
489 push(@c, @generated, @gpl,
490 "\n");
491
492 push(@ah, @generated, @gpl,
493 "#ifndef ECLIENT_STUBS_H\n",
494 "#define ECLIENT_STUBS_H\n",
495 "\n");
496
497 push(@ac, @generated, @gpl,
498 "\n");
499
500 # The protocol ----------------------------------------------------------------
501
502 simple("adopt",
503 "Adopt a track",
504 "Makes the calling user owner of a randomly picked track.",
505 [["string", "id", "Track ID"]]);
506
507 simple("adduser",
508 "Create a user",
509 "Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.",
510 [["string", "user", "New username"],
511 ["string", "password", "Initial password"],
512 ["string", "rights", "Initial rights (optional)"]]);
513
514 simple("allfiles",
515 "List files and directories in a directory",
516 "See 'files' and 'dirs' for more specific lists.",
517 [["string", "dir", "Directory to list (optional)"],
518 ["string", "re", "Regexp that results must match (optional)"]],
519 [["body", "files", "List of matching files and directories"]]);
520
521 simple("confirm",
522 "Confirm registration",
523 "The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are.",
524 [["string", "confirmation", "Confirmation string"]],
525 [["user"]]);
526
527 simple("cookie",
528 "Log in with a cookie",
529 "The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.",
530 [["string", "cookie", "Cookie string"]],
531 [["user"]]);
532
533 simple("deluser",
534 "Delete user",
535 "Requires the 'admin' right.",
536 [["string", "user", "User to delete"]]);
537
538 simple("dirs",
539 "List directories in a directory",
540 "",
541 [["string", "dir", "Directory to list (optional)"],
542 ["string", "re", "Regexp that results must match (optional)"]],
543 [["body", "files", "List of matching directories"]]);
544
545 simple("disable",
546 "Disable play",
547 "Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.",
548 []);
549
550 simple("edituser",
551 "Set a user property",
552 "With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.",
553 [["string", "username", "User to modify"],
554 ["string", "property", "Property name"],
555 ["string", "value", "New property value"]]);
556
557 simple("enable",
558 "Enable play",
559 "Requires the 'global prefs' right.",
560 []);
561
562 simple("enabled",
563 "Detect whether play is enabled",
564 "",
565 [],
566 [["boolean", "enabled", "1 if play is enabled and 0 otherwise"]]);
567
568 simple("exists",
569 "Test whether a track exists",
570 "",
571 [["string", "track", "Track name"]],
572 [["boolean", "exists", "1 if the track exists and 0 otherwise"]]);
573
574 simple("files",
575 "List files in a directory",
576 "",
577 [["string", "dir", "Directory to list (optional)"],
578 ["string", "re", "Regexp that results must match (optional)"]],
579 [["body", "files", "List of matching files"]]);
580
581 simple("get",
582 "Get a track preference",
583 "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.",
584 [["string", "track", "Track name"],
585 ["string", "pref", "Preference name"]],
586 [["string", "value", "Preference value"]]);
587
588 simple("get-global",
589 "Get a global preference",
590 "If the preference does exist not then a null value is returned.",
591 [["string", "pref", "Global preference name"]],
592 [["string", "value", "Preference value"]]);
593
594 simple("length",
595 "Get a track's length",
596 "If the track does not exist an error is returned.",
597 [["string", "track", "Track name"]],
598 [["integer", "length", "Track length in seconds"]]);
599
600 # TODO log
601
602 simple("make-cookie",
603 "Create a login cookie for this user",
604 "The cookie may be redeemed via the 'cookie' command",
605 [],
606 [["string", "cookie", "Newly created cookie"]]);
607
608 simple("move",
609 "Move a track",
610 "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
611 [["string", "track", "Track ID or name"],
612 ["integer", "delta", "How far to move the track towards the head of the queue"]]);
613
614 simple("moveafter",
615 "Move multiple tracks",
616 "Requires one of the 'move mine', 'move random' or 'move any' rights depending on how the track came to be added to the queue.",
617 [["string", "target", "Move after this track, or to head if \"\""],
618 ["list", "ids", "List of tracks to move by ID"]]);
619
620 simple(["new", "new_tracks"],
621 "List recently added tracks",
622 "",
623 [["integer", "max", "Maximum tracks to fetch, or 0 for all available"]],
624 [["body", "tracks", "Recently added tracks"]]);
625
626 simple("nop",
627 "Do nothing",
628 "Used as a keepalive. No authentication required.",
629 []);
630
631 simple("part",
632 "Get a track name part",
633 "If the name part cannot be constructed an empty string is returned.",
634 [["string", "track", "Track name"],
635 ["string", "context", "Context (\"sort\" or \"display\")"],
636 ["string", "part", "Name part (\"artist\", \"album\" or \"title\")"]],
637 [["string", "part", "Value of name part"]]);
638
639 simple("pause",
640 "Pause the currently playing track",
641 "Requires the 'pause' right.",
642 []);
643
644 simple("play",
645 "Play a track",
646 "Requires the 'play' right.",
647 [["string", "track", "Track to play"]],
648 [["string-raw", "id", "Queue ID of new track"]]);
649
650 simple("playafter",
651 "Play multiple tracks",
652 "Requires the 'play' right.",
653 [["string", "target", "Insert into queue after this track, or at head if \"\""],
654 ["list", "tracks", "List of track names to play"]]);
655
656 simple("playing",
657 "Retrieve the playing track",
658 "",
659 [],
660 [["queue-one", "playing", "Details of the playing track"]]);
661
662 simple("playlist-delete",
663 "Delete a playlist",
664 "Requires the 'play' right and permission to modify the playlist.",
665 [["string", "playlist", "Playlist to delete"]]);
666
667 simple("playlist-get",
668 "List the contents of a playlist",
669 "Requires the 'read' right and oermission to read the playlist.",
670 [["string", "playlist", "Playlist name"]],
671 [["body", "tracks", "List of tracks in playlist"]]);
672
673 simple("playlist-get-share",
674 "Get a playlist's sharing status",
675 "Requires the 'read' right and permission to read the playlist.",
676 [["string", "playlist", "Playlist to read"]],
677 [["string-raw", "share", "Sharing status (\"public\", \"private\" or \"shared\")"]]);
678
679 simple("playlist-lock",
680 "Lock a playlist",
681 "Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.",
682 [["string", "playlist", "Playlist to delete"]]);
683
684 simple("playlist-set",
685 "Set the contents of a playlist",
686 "Requires the 'play' right and permission to modify the playlist, which must be locked.",
687 [["string", "playlist", "Playlist to modify"],
688 ["body", "tracks", "New list of tracks for playlist"]]);
689
690 simple("playlist-set-share",
691 "Set a playlist's sharing status",
692 "Requires the 'play' right and permission to modify the playlist.",
693 [["string", "playlist", "Playlist to modify"],
694 ["string", "share", "New sharing status (\"public\", \"private\" or \"shared\")"]]);
695
696 simple("playlist-unlock",
697 "Unlock the locked playlist playlist",
698 "The playlist to unlock is implicit in the connection.",
699 []);
700
701 simple("playlists",
702 "List playlists",
703 "Requires the 'read' right. Only playlists that you have permission to read are returned.",
704 [],
705 [["body", "playlists", "Playlist names"]]);
706
707 simple("prefs",
708 "Get all the preferences for a track",
709 "",
710 [["string", "track", "Track name"]],
711 [["pair-list", "prefs", "Track preferences"]]);
712
713 simple("queue",
714 "List the queue",
715 "",
716 [],
717 [["queue", "queue", "Current queue contents"]]);
718
719 simple("random-disable",
720 "Disable random play",
721 "Requires the 'global prefs' right.",
722 []);
723
724 simple("random-enable",
725 "Enable random play",
726 "Requires the 'global prefs' right.",
727 []);
728
729 simple("random-enabled",
730 "Detect whether random play is enabled",
731 "Random play counts as enabled even if play is disabled.",
732 [],
733 [["boolean", "enabled", "1 if random play is enabled and 0 otherwise"]]);
734
735 simple("recent",
736 "List recently played tracks",
737 "",
738 [],
739 [["queue", "recent", "Recently played tracks"]]);
740
741 simple("reconfigure",
742 "Re-read configuraiton file.",
743 "Requires the 'admin' right.",
744 []);
745
746 simple("register",
747 "Register a new user",
748 "Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.",
749 [["string", "username", "Requested new username"],
750 ["string", "password", "Requested initial password"],
751 ["string", "email", "New user's email address"]],
752 [["string", "confirmation", "Confirmation string"]]);
753
754 simple("reminder",
755 "Send a password reminder.",
756 "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.",
757 [["string", "username", "User to remind"]]);
758
759 simple("remove",
760 "Remove a track form the queue.",
761 "Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.",
762 [["string", "id", "Track ID"]]);
763
764 simple("rescan",
765 "Rescan all collections for new or obsolete tracks.",
766 "Requires the 'rescan' right.",
767 []); # TODO wait/fresh flags
768
769 simple("resolve",
770 "Resolve a track name",
771 "Converts aliases to non-alias track names",
772 [["string", "track", "Track name (might be an alias)"]],
773 [["string", "resolved", "Resolve track name (definitely not an alias)"]]);
774
775 simple("resume",
776 "Resume the currently playing track",
777 "Requires the 'pause' right.",
778 []);
779
780 simple("revoke",
781 "Revoke a cookie.",
782 "It will not subsequently be possible to log in with the cookie.",
783 []);
784
785 simple("rtp-address",
786 "Get the server's RTP address information",
787 "",
788 [],
789 [["string", "address", "Where to store hostname or address"],
790 ["string", "port", "Where to store service name or port number"]]);
791
792 simple("scratch",
793 "Terminate the playing track.",
794 "Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.",
795 [["string", "id", "Track ID (optional)"]]);
796
797 simple(["schedule-add", "schedule_add_play"],
798 "Schedule a track to play in the future",
799 "",
800 [["time", "when", "When to play the track"],
801 ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
802 ["literal", "play", ""],
803 ["string", "track", "Track to play"]]);
804
805 simple(["schedule-add", "schedule_add_set_global"],
806 "Schedule a global setting to be changed in the future",
807 "",
808 [["time", "when", "When to change the setting"],
809 ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
810 ["literal", "set-global", ""],
811 ["string", "pref", "Global preference to set"],
812 ["string", "value", "New value of global preference"]]);
813
814 simple(["schedule-add", "schedule_add_unset_global"],
815 "Schedule a global setting to be unset in the future",
816 "",
817 [["time", "when", "When to change the setting"],
818 ["string", "priority", "Event priority (\"normal\" or \"junk\")"],
819 ["literal", "set-global", ""],
820 ["string", "pref", "Global preference to set"]]);
821
822 simple("schedule-del",
823 "Delete a scheduled event.",
824 "Users can always delete their own scheduled events; with the admin right you can delete any event.",
825 [["string", "event", "ID of event to delete"]]);
826
827 simple("schedule-get",
828 "Get the details of scheduled event",
829 "",
830 [["string", "id", "Event ID"]],
831 [["pair-list", "actiondata", "Details of event"]]);
832
833 simple("schedule-list",
834 "List scheduled events",
835 "This just lists IDs. Use 'schedule-get' to retrieve more detail",
836 [],
837 [["body", "ids", "List of event IDs"]]);
838
839 simple("search",
840 "Search for tracks",
841 "Terms are either keywords or tags formatted as 'tag:TAG-NAME'.",
842 [["string", "terms", "List of search terms"]],
843 [["body", "tracks", "List of matching tracks"]]);
844
845 simple("set",
846 "Set a track preference",
847 "Requires the 'prefs' right.",
848 [["string", "track", "Track name"],
849 ["string", "pref", "Preference name"],
850 ["string", "value", "New value"]]);
851
852 simple("set-global",
853 "Set a global preference",
854 "Requires the 'global prefs' right.",
855 [["string", "pref", "Preference name"],
856 ["string", "value", "New value"]]);
857
858 simple("shutdown",
859 "Request server shutdown",
860 "Requires the 'admin' right.",
861 []);
862
863 simple("stats",
864 "Get server statistics",
865 "The details of what the server reports are not really defined. The returned strings are intended to be printed out one to a line.",
866 [],
867 [["body", "stats", "List of server information strings."]]);
868
869 simple("tags",
870 "Get a list of known tags",
871 "Only tags which apply to at least one track are returned.",
872 [],
873 [["body", "tags", "List of tags"]]);
874
875 simple("unset",
876 "Unset a track preference",
877 "Requires the 'prefs' right.",
878 [["string", "track", "Track name"],
879 ["string", "pref", "Preference name"]]);
880
881 simple("unset-global",
882 "Set a global preference",
883 "Requires the 'global prefs' right.",
884 [["string", "pref", "Preference name"]]);
885
886 # 'user' only used for authentication
887
888 simple("userinfo",
889 "Get a user property.",
890 "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.",
891 [["string", "username", "User to read"],
892 ["string", "property", "Property to read"]],
893 [["string", "value", "Value of property"]]);
894
895 simple("users",
896 "Get a list of users",
897 "",
898 [],
899 [["body", "users", "List of users"]]);
900
901 simple("version",
902 "Get the server version",
903 "",
904 [],
905 [["string", "version", "Server version string"]]);
906
907 simple(["volume", "set_volume"],
908 "Set the volume",
909 "",
910 [["integer", "left", "Left channel volume"],
911 ["integer", "right", "Right channel volume"]]);
912
913 simple(["volume", "get_volume"],
914 "Get the volume",
915 "",
916 [],
917 [["integer", "left", "Left channel volume"],
918 ["integer", "right", "Right channel volume"]]);
919
920 # End matter ------------------------------------------------------------------
921
922 push(@h, "#endif\n");
923
924 push(@ah, "#endif\n");
925
926 # Write it all out ------------------------------------------------------------
927
928 Write("lib/client-stubs.h", \@h);
929 Write("lib/client-stubs.c", \@c);
930
931 Write("lib/eclient-stubs.h", \@ah);
932 Write("lib/eclient-stubs.c", \@ac);
933
934 if(scalar @missing) {
935 print "Missing:\n";
936 print map(" $_\n", @missing);
937 }