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