From 200adb00f0319d35b9c512eadff714bb6933b9a9 Mon Sep 17 00:00:00 2001 Message-Id: <200adb00f0319d35b9c512eadff714bb6933b9a9.1716686915.git.mdw@distorted.org.uk> From: Mark Wooding Date: Fri, 4 Jun 2010 20:51:46 +0100 Subject: [PATCH] First steps towards automatic client code generation. Currently supported: - the C synchronous client, only. - simple string commands, only. Organization: Straylight/Edgeware From: Richard Kettlewell --- scripts/protocol | 339 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100755 scripts/protocol diff --git a/scripts/protocol b/scripts/protocol new file mode 100755 index 0000000..ad712d5 --- /dev/null +++ b/scripts/protocol @@ -0,0 +1,339 @@ +#! /usr/bin/perl -w +# +# This file is part of DisOrder. +# Copyright (C) 2010 Richard Kettlewell +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# +use strict; + +# Variables and utilities ----------------------------------------------------- + +our @h = (); +our @c = (); + +sub Write { + my $path = shift; + my $lines = shift; + + (open(F, ">$path") + and print F @$lines + and close F) + or die "$0: $path: $!\n"; +} + +# Command classes ------------------------------------------------------------- + +# simple_string_command(CMD, SUMMARY, DETAIL, [[NAME,DESCR], [NAME,DESCR], ...],) +# +# Response is simply success/failure +sub simple_string_command { + my $cmd = shift; + my $summary = shift; + my $detail = shift; + my $args = shift; + + my $cmdc = $cmd; + $cmdc =~ s/-/_/g; + # Synchronous C API + push(@h, "/** \@brief $summary\n", + " *\n", + " * $detail\n", + " *\n", + map(" * \@param $_->[0] $_->[1]\n", @$args), + " * \@return 0 on success, non-0 on error\n", + " */\n", + "int disorder_$cmdc(disorder_client *c", + map(", const char *$_->[0]", @$args), ");\n", + "\n"); + push(@c, "int disorder_$cmdc(disorder_client *c", + map(", const char *$_->[0]", @$args), ") {\n", + " return disorder_simple(c, 0, \"$cmd\"", + map(", $_->[0]", @$args), + ", (char *)0);\n", + "}\n\n"); + + # Asynchronous C API + # TODO + + # Python API + # TODO + + # Java API + # TODO +} + +# TODO other command classes + +# Front matter ---------------------------------------------------------------- + +our @gpl = ("/*\n", + " * This file is part of DisOrder.\n", + " * Copyright (C) 2010 Richard Kettlewell\n", + " *\n", + " * This program is free software: you can redistribute it and/or modify\n", + " * it under the terms of the GNU General Public License as published by\n", + " * the Free Software Foundation, either version 3 of the License, or\n", + " * (at your option) any later version.\n", + " *\n", + " * This program is distributed in the hope that it will be useful,\n", + " * but WITHOUT ANY WARRANTY; without even the implied warranty of\n", + " * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n", + " * GNU General Public License for more details.\n", + " *\n", + " * You should have received a copy of the GNU General Public License\n", + " * along with this program. If not, see .\n", + " */\n"); + + +push(@h, @gpl, + "#ifndef CLIENT_STUBS_H\n", + "#define CLIENT_STUBS_H\n", + "\n"); + +push(@c, @gpl, + "\n"); + +# The protocol ---------------------------------------------------------------- + +simple_string_command("adopt", + "Adopt a track", + "Makes the calling user owner of a randomly picked track.", + [["id", "Track ID"]]); + +simple_string_command("adduser", + "Create a user", + "Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.", + [["user", "New username"], + ["password", "Initial password"], + ["rights", "Initial rights (optional)"]]); + +# TODO allfiles + +simple_string_command("confirm", + "Confirm user registration", + "The confirmation string is as returned by the register command.", + [["confirmation", "Confirmnation string"]]); + +# TODO cookie + +simple_string_command("deluser", + "Delete user", + "Requires the 'admin' right.", + [["user", "User to delete"]]); + +# TODO dirs + +simple_string_command("disable", + "Disable play", + "Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.", + []); + +simple_string_command("edituser", + "Set a user property", + "With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.", + [["username", "User to modify"], + ["property", "Property name"], + ["value", "New property value"]]); + +simple_string_command("enable", + "Enable play", + "Requires the 'global prefs' right.", + []); + +# TODO enabled + +# TODO exists + +# TODO files + +# TODO get + +# TODO get-global + +# TODO length + +# TODO log + +# TODO make-cookie + +# TODO move + +# TODO moveafter + +# TODO new + +simple_string_command("nop", + "Do nothing", + "Used as a keepalive. No authentication required.", + []); + +# TODO part + +simple_string_command("pause", + "Pause the currently playing track", + "Requires the 'pause' right.", + []); + +# TODO playafter + +# TODO playing + +simple_string_command("playlist-delete", + "Delete a playlist", + "Requires the 'play' right and permission to modify the playlist.", + [["playlist", "Playlist to delete"]]); + +# TODO playlist-get + +# TODO playlist-get-share + +simple_string_command("playlist-lock", + "Lock a playlist", + "Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.", + [["playlist", "Playlist to delete"]]); + +# TODO playlist-set + +simple_string_command("playlist-set-share", + "Set a playlist's sharing status", + "Requires the 'play' right and permission to modify the playlist. ", + [["playlist", "Playlist to modify"], + ["share", "New sharing status ('public', 'private' or 'shared')"]]); + +simple_string_command("playlist-unlock", + "Unlock the locked playlist playlist", + "The playlist to unlock is implicit in the connection.", + []); + +# TODO playlists + +# TODO prefs + +# TODO queue + +simple_string_command("random-disable", + "Disable random play", + "Requires the 'global prefs' right.", + []); + +simple_string_command("random-enable", + "Enable random play", + "Requires the 'global prefs' right.", + []); + +# TODO random-enabled + +# TODO recent + +simple_string_command("reconfigure", + "Re-read configuraiton file.", + "Requires the 'admin' right.", + []); + +# TODO register + +simple_string_command("reminder", + "Send a password reminder.", + "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.", + [["username", "User to remind"]]); + +simple_string_command("remove", + "Remove a track form the queue.", + "Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.", + [["id", "Track ID"]]); + +simple_string_command("rescan", + "Rescan all collections for new or obsolete tracks.", + "Requires the 'rescan' right.", + []); # TODO wait/fresh flags + +# TODO resolve + +simple_string_command("resume", + "Resume the currently playing track", + "Requires the 'pause' right.", + []); + +simple_string_command("revoke", + "Revoke a cookie.", + "It will not subsequently be possible to log in with the cookie..", + [["cookie", "Cookie to revoke"]]); + +# TODO rtp-address + +simple_string_command("scratch", + "Terminate the playing track.", + "Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.", + [["id", "Track ID (optional)"]]); + +# TODO schedule-add + +simple_string_command("schedule-del", + "Delete a scheduled event.", + "Users can always delete their own scheduled events; with the admin right you can delete any event.", + [["event", "ID of event to delete"]]); + +# TODO schedule-get + +# TODO schedule-list + +# TODO search + +simple_string_command("set", + "Set a track preference", + "Requires the 'prefs' right.", + [["track", "Track name"], + ["pref", "Preference name"], + ["value", "New value"]]); + +simple_string_command("set-global", + "Set a global preference", + "Requires the 'global prefs' right.", + [["pref", "Preference name"], + ["value", "New value"]]); + +# TODO stats + +# TODO tags + +simple_string_command("unset", + "Unset a track preference", + "Requires the 'prefs' right.", + [["track", "Track name"], + ["pref", "Preference name"]]); + +simple_string_command("unset-global", + "Set a global preference", + "Requires the 'global prefs' right.", + [["pref", "Preference name"]]); + +# user is only used by connect functions + +# TODO userinfo + +# TODO users + +# TODO version + +# TODO volume + +# End matter ------------------------------------------------------------------ + +push(@h, "#endif\n"); + +# Write it all out ------------------------------------------------------------ + +Write("client-stubs.h", \@h); +Write("client-stubs.c", \@c); -- [mdw]