Changeset 5827

Timestamp:

May 12, 2008, 11:51:17 PM (14 years ago)

Author:

charles

Message:

make the request/response messages a little terser. add per-torrent speed limit toggles. rename ipc -> rpc.

Location:

trunk

Files:

• doc/rpc-json-spec.txt (moved) (moved from trunk/doc/ipc-json-spec.txt) (10 diffs)
• libtransmission/Makefile.am (modified) (4 diffs)
• libtransmission/rpc.c (moved) (moved from trunk/libtransmission/ipc.c) (9 diffs)
• libtransmission/rpc.h (moved) (moved from trunk/libtransmission/ipc.h) (1 diff)

trunk/doc/rpc-json-spec.txt

@@ -19 +19 @@
    booleans are represented as integers where 0 is false and 1 is true.
 
-   There are only two message types: request and response.  Both
-   are JSON objects with two members:  "headers" (described in 2.1)
-   and "body" (described in 2.2 - 2.3).
-
-2.1.  Headers
-
-   Message headers support two members:
-   (1) A required "type" string whose value must be "request" or "response".
-   (2) An optional "tag" integer supplied by requests for their own use.
-       Responses MUST include the request tag's verbatim.
-
-2.2.  Request Body
-
-   Request bodies support two members:
-   (1) A required "name" string telling the name of the request.
-   (2) An optional "arguments" object of name/value pairs.
-
-2.3.  Response Body
-
-   All response bodies support two members:
+   Messages are represented as a JSON objects.  There are two types:
+   requests (described in 2.1) and responses (described in 2.2).
+
+2.1.  Requests
+
+   Requests supports three keys:
+
+   (1) A required "method" string telling the name of the method to invoke
+   (2) An optional "arguments" object of name/value pairs
+   (3) An optional "tag" integer used for clients to track responses.
+       If provided by a request, the response MUST include the same tag.
+
+2.2.  Responses
+
+   Reponses support three keys:
+
    (1) A required "result" string whose value must be "success" on success,
-       and may be "no-permission", "bad-format", or "error" on failure.
-   (2) An optional "arguments" object of name/value pairs.
-       The contents of these arguments depend on the request's name.
+       or an error string on failure.
+   (2) An optional "arguments" object of name/value pairs
+   (3) An optional "tag" integer as described in 2.1.
 
 3.  Torrent Requests
@@ -48 +44 @@
 3.1.  Torrent Action Requests
 
-   Request names: "torrent-start", "torrent-stop",
-                  "torrent-remove", "torrent-verify"
+   Method names: "torrent-start", "torrent-stop",
+                 "torrent-remove", "torrent-verify"
+
    Request arguments: "ids", a list of unique torrent ids, sha1 hash strings,
                       or both.  These are the torrents that the request will
                       be applied to.  If "ids" is ommitted, the request is
                       applied to all torrents.
+
    Response arguments: none.
 
 3.2.  Torrent Info Requests
 
-   Request name: "torrent-info".
+   Method name: "torrent-info".
+
    Request arguments: 3.1's optional "ids" argument.
 
@@ -71 +70 @@
 
       {
-         "headers": {
-            "type": "request",
-            "tag": 666
-         },
-         "body": {
-            "name": "torrent-info",
-            "arguments": {
-               "ids": [ 7, 10 ]
-            }
+         "arguments": { "ids": [ 7, 10 ] }
+         "method": "torrent-info",
+         "tag": 666
+      }
+
+   Example Response:
+
+      {
+         "tag": 666
+         "result": "success",
+         "arguments": {
+            "info": [
+               {
+                  "id": 7,
+                  "totalSize": 9803930483,
+                  "pieceCount": 1209233,
+                  "pieceSize": 4096,
+                  "name": "Ubuntu x86_64 DVD",
+                  ...
+               },
+               {
+                  "id": 10,
+                  "totalSize": 2398480394,
+                  "pieceCount": 83943,
+                  "pieceSize": 12345,
+                  "name": "Ubuntu i386 DVD",
+                  ...
+               }
+            ]
          }
       }
 
-   Example Response:
-
-      {
-         "headers": {
-            "type": "response",
-            "tag": 666
-         }
-         "body": {
-            "result": "success",
-            "arguments": {
-               "info": [
-                  {
-                     "id": 7,
-                     "totalSize": 9803930483,
-                     "pieceCount": 1209233,
-                     "pieceSize": 4096,
-                     "name": "Ubuntu x86_64 DVD",
-                     ...
-                  }
-                  {
-                     "id": 10,
-                     "totalSize": 2398480394,
-                     "pieceCount": 83943,
-                     "pieceSize": 12345,
-                     "name": "Ubuntu i386 DVD",
-                     ...
-                  }
-               ]
-            }
-         }
-      }
-
 3.3.  Torrent Status Requests
 
-   Request name is "torrent-status".
+   Method name: "torrent-status"
+
    Request arguments: 3.1's optional "ids" argument.
 
@@ -129 +117 @@
 3.4.  Adding a Torrent
 
-   Request name: "torrent-add"
+   Method name: "torrent-add"
+
    Request arguments:
 
    string             | value type & description
    -------------------+-------------------------------------------------
-   "autostart"        | boolean   true means to auto-start torrents
+   "paused"           | boolean   if true, don't start the torrent
    "destination"      | string    path to download the torrent to
    "filename"         | string    location of the .torrent file
@@ -148 +137 @@
    Common arguments:
 
-   string             | value type & description
-   -------------------+-------------------------------------------------
-   "peer-limit"       | int            maximum number of peers
-   "speed-limit-down" | int            maximum download speed (in KiB/s)
-   "speed-limit-up"   | int            maximum upload speed (in KiB/s)
+   string                     | value type & description
+   ---------------------------+-------------------------------------------------
+   "peer-limit"               | int       maximum number of peers
+   "speed-limit-down"         | int       maximum download speed (in KiB/s)
+   "speed-limit-down-enabled" | boolean   true if the download speed is limited
+   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
+   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
 
 3.5.1.  Mutators
 
-   Request name: "torrent-set"
+   Method name: "torrent-set"
    Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
    Response arguments: none
@@ -162 +153 @@
 3.5.2.  Accessors
 
-   Request name: "torrent-get"
+   Method name: "torrent-get"
    Request arguments: none
    Response arguments: A "torrents" list of objects containing all
@@ -182 +173 @@
 3.6.1.  Mutators
 
-    Request name: "torrent-set-file"
+    Method name: "torrent-set-file"
     Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
     Response arguments: none
@@ -188 +179 @@
 3.6.2.  Accessors
 
-    Request name: "torrent-get-file"
+    Method name: "torrent-get-file"
     Request arguments: none
    Response arguments: A "torrents" list of objects containing all
@@ -211 +202 @@
 4.2.  Mutators
 
-   Request name: "session-set"
+   Method name: "session-set"
    Request arguments: one or more of 4.1's arguments
    Response arguments: none
@@ -217 +208 @@
 4.2.  Accessors
 
-   Request name: "session-get"
+   Method name: "session-get"
    Request arguments: none
    Response arguments: all of 4.1's arguments

trunk/libtransmission/Makefile.am

@@ -17 +17 @@
     handshake.c \
     inout.c \
-    ipc.c \
     ipcparse.c \
     json.c \
@@ -34 +33 @@
     ratecontrol.c \
     resume.c \
+    rpc.c \
     session.c \
     stats.c \
@@ -58 +58 @@
     handshake.h \
     inout.h \
-    ipc.h \
     ipcparse.h \
     list.h \
@@ -75 +74 @@
     ratecontrol.h \
     resume.h \
+    rpc.h \
     session.h \
     stats.h \

trunk/libtransmission/rpc.c

@@ -16 +16 @@
 #include "transmission.h"
 #include "bencode.h"
-#include "ipc.h"
+#include "rpc.h"
 #include "torrent.h"
 #include "utils.h"
@@ -246 +246 @@
     {
         tr_torrent * tor = torrents[i];
-        tr_benc * d = tr_bencListAddDict( list, 4 );
+        tr_benc * d = tr_bencListAddDict( list, 6 );
         tr_bencDictAddInt( d, "id", tor->uniqueId );
         tr_bencDictAddInt( d, "peer-limit",
@@ -252 +252 @@
         tr_bencDictAddInt( d, "speed-limit-down",
                            tr_torrentGetSpeedLimit( tor, TR_DOWN ) );
+        tr_bencDictAddInt( d, "speed-limit-down-enabled",
+                           tr_torrentGetSpeedMode( tor, TR_DOWN )
+                               == TR_SPEEDLIMIT_SINGLE );
         tr_bencDictAddInt( d, "speed-limit-up",
                            tr_torrentGetSpeedLimit( tor, TR_UP ) );
+        tr_bencDictAddInt( d, "speed-limit-up-enabled",
+                           tr_torrentGetSpeedMode( tor, TR_UP )
+                               == TR_SPEEDLIMIT_SINGLE );
     }
 
@@ -274 +280 @@
         if( tr_bencDictFindInt( args_in, "speed-limit-down", &tmp ) )
             tr_torrentSetSpeedLimit( tor, TR_DOWN, tmp );
+        if( tr_bencDictFindInt( args_in, "speed-limit-down-enabled", &tmp ) )
+            tr_torrentSetSpeedMode( tor, TR_DOWN, tmp ? TR_SPEEDLIMIT_SINGLE
+                                                      : TR_SPEEDLIMIT_GLOBAL );
         if( tr_bencDictFindInt( args_in, "speed-limit-up", &tmp ) )
             tr_torrentSetSpeedLimit( tor, TR_UP, tmp );
+        if( tr_bencDictFindInt( args_in, "speed-limit-up-enabled", &tmp ) )
+            tr_torrentSetSpeedMode( tor, TR_UP, tmp ? TR_SPEEDLIMIT_SINGLE
+                                                    : TR_SPEEDLIMIT_GLOBAL );
     }
 
@@ -439 +451 @@
         ctor = tr_ctorNew( h );
         tr_ctorSetMetainfoFromFile( ctor, filename );
-        if( tr_bencDictFindInt( args_in, "autostart", &i ) )
-            tr_ctorSetPaused( ctor, TR_FORCE, !i );
+        if( tr_bencDictFindInt( args_in, "paused", &i ) )
+            tr_ctorSetPaused( ctor, TR_FORCE, i );
         if( tr_bencDictFindInt( args_in, "peer-limit", &i ) )
             tr_ctorSetPeerLimit( ctor, TR_FORCE, i );
@@ -539 +551 @@
 struct request_handler
 {
-    const char * name;
+    const char * method;
     handler * func;
 } request_handlers[] = { 
@@ -566 +578 @@
     char * out;
     tr_benc response;
-    tr_benc * headers_in = NULL;
-    tr_benc * body_in = NULL;
-    tr_benc * args_in = NULL;
-    tr_benc * headers_out = NULL;
-    tr_benc * body_out = NULL;
+    tr_benc * args_in = tr_bencDictFind( request, "args" );
     tr_benc * args_out = NULL;
     const char * result = NULL;
 
-    headers_in = tr_bencDictFind( request, "headers" );
-    body_in = tr_bencDictFind( request, "body" );
-    args_in = tr_bencDictFind( body_in, "args" );
-
     /* build the response skeleton */
-    tr_bencInitDict( &response, 2 );
-    headers_out = tr_bencDictAddDict( &response, "headers", 2 );
-    tr_bencDictAddStr( headers_out, "type", "response" );
-    if( tr_bencDictFindInt( headers_in, "tag", &i ) )
-        tr_bencDictAddInt( headers_out, "tag", i );
-    body_out = tr_bencDictAddDict( &response, "body", 2 );
-    args_out = tr_bencDictAddDict( body_out, "args", 0 );
+    tr_bencInitDict( &response, 3 );
+    if( tr_bencDictFindInt( request, "tag", &i ) )
+        tr_bencDictAddInt( request, "tag", i );
+    args_out = tr_bencDictAddDict( &response, "args", 0 );
 
     /* parse the request */
-    if( !tr_bencDictFindStr( body_in, "name", &str ) )
-        result = "no request name given";
+    if( !tr_bencDictFindStr( request, "method", &str ) )
+        result = "no method name";
     else {
         const int n = TR_N_ELEMENTS( request_handlers );
         for( i=0; i<n; ++i )
-            if( !strcmp( str, request_handlers[i].name ) )
+            if( !strcmp( str, request_handlers[i].method ) )
                 break;
         result = i==n
-            ? "request name not recognized"
+            ? "method name not recognized"
             : (*request_handlers[i].func)( handle, args_in, args_out );
     }
@@ -602 +603 @@
     /* serialize & return the response */
     if( !result )
-        result = "success";
-    tr_bencDictAddStr( body_out, "result", result );
-    out = tr_bencSave( &response, response_len ); /* TODO: json, not benc */
+         result = "success";
+    tr_bencDictAddStr( &response, "result", result );
+    out = tr_bencSaveAsJSON( &response, response_len );
     tr_bencFree( &response );
     return out;
@@ -610 +611 @@
 
 char*
-tr_ipc_request_exec( struct tr_handle  * handle,
+tr_rpc_request_exec( struct tr_handle  * handle,
                      const void        * request_json,
                      int                 request_len,

trunk/libtransmission/rpc.h

@@ -11 +11 @@
  */
 
-#ifndef TR_IPC_H
-#define TR_IPC_H
+#ifndef TR_RPC_H
+#define TR_RPC_H
 
 struct tr_handle;
 
 char*
-tr_ipc_request_exec( struct tr_handle  * handle,
+tr_rpc_request_exec( struct tr_handle  * handle,
                      const void        * request_json,
                      int                 request_len,