Changeset 5827


Ignore:
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:
1 edited
3 moved

Legend:

Unmodified
Added
Removed
  • trunk/doc/rpc-json-spec.txt

    r5819 r5827  
    1919   booleans are represented as integers where 0 is false and 1 is true.
    2020
    21    There are only two message types: request and response.  Both
    22    are JSON objects with two members:  "headers" (described in 2.1)
    23    and "body" (described in 2.2 - 2.3).
    24 
    25 2.1.  Headers
    26 
    27    Message headers support two members:
    28    (1) A required "type" string whose value must be "request" or "response".
    29    (2) An optional "tag" integer supplied by requests for their own use.
    30        Responses MUST include the request tag's verbatim.
    31 
    32 2.2.  Request Body
    33 
    34    Request bodies support two members:
    35    (1) A required "name" string telling the name of the request.
    36    (2) An optional "arguments" object of name/value pairs.
    37 
    38 2.3.  Response Body
    39 
    40    All response bodies support two members:
     21   Messages are represented as a JSON objects.  There are two types:
     22   requests (described in 2.1) and responses (described in 2.2).
     23
     242.1.  Requests
     25
     26   Requests supports three keys:
     27
     28   (1) A required "method" string telling the name of the method to invoke
     29   (2) An optional "arguments" object of name/value pairs
     30   (3) An optional "tag" integer used for clients to track responses.
     31       If provided by a request, the response MUST include the same tag.
     32
     332.2.  Responses
     34
     35   Reponses support three keys:
     36
    4137   (1) A required "result" string whose value must be "success" on success,
    42        and may be "no-permission", "bad-format", or "error" on failure.
    43    (2) An optional "arguments" object of name/value pairs.
    44        The contents of these arguments depend on the request's name.
     38       or an error string on failure.
     39   (2) An optional "arguments" object of name/value pairs
     40   (3) An optional "tag" integer as described in 2.1.
    4541
    46423.  Torrent Requests
     
    48443.1.  Torrent Action Requests
    4945
    50    Request names: "torrent-start", "torrent-stop",
    51                   "torrent-remove", "torrent-verify"
     46   Method names: "torrent-start", "torrent-stop",
     47                 "torrent-remove", "torrent-verify"
     48
    5249   Request arguments: "ids", a list of unique torrent ids, sha1 hash strings,
    5350                      or both.  These are the torrents that the request will
    5451                      be applied to.  If "ids" is ommitted, the request is
    5552                      applied to all torrents.
     53
    5654   Response arguments: none.
    5755
    58563.2.  Torrent Info Requests
    5957
    60    Request name: "torrent-info".
     58   Method name: "torrent-info".
     59
    6160   Request arguments: 3.1's optional "ids" argument.
    6261
     
    7170
    7271      {
    73          "headers": {
    74             "type": "request",
    75             "tag": 666
    76          },
    77          "body": {
    78             "name": "torrent-info",
    79             "arguments": {
    80                "ids": [ 7, 10 ]
    81             }
     72         "arguments": { "ids": [ 7, 10 ] }
     73         "method": "torrent-info",
     74         "tag": 666
     75      }
     76
     77   Example Response:
     78
     79      {
     80         "tag": 666
     81         "result": "success",
     82         "arguments": {
     83            "info": [
     84               {
     85                  "id": 7,
     86                  "totalSize": 9803930483,
     87                  "pieceCount": 1209233,
     88                  "pieceSize": 4096,
     89                  "name": "Ubuntu x86_64 DVD",
     90                  ...
     91               },
     92               {
     93                  "id": 10,
     94                  "totalSize": 2398480394,
     95                  "pieceCount": 83943,
     96                  "pieceSize": 12345,
     97                  "name": "Ubuntu i386 DVD",
     98                  ...
     99               }
     100            ]
    82101         }
    83102      }
    84103
    85    Example Response:
    86 
    87       {
    88          "headers": {
    89             "type": "response",
    90             "tag": 666
    91          }
    92          "body": {
    93             "result": "success",
    94             "arguments": {
    95                "info": [
    96                   {
    97                      "id": 7,
    98                      "totalSize": 9803930483,
    99                      "pieceCount": 1209233,
    100                      "pieceSize": 4096,
    101                      "name": "Ubuntu x86_64 DVD",
    102                      ...
    103                   }
    104                   {
    105                      "id": 10,
    106                      "totalSize": 2398480394,
    107                      "pieceCount": 83943,
    108                      "pieceSize": 12345,
    109                      "name": "Ubuntu i386 DVD",
    110                      ...
    111                   }
    112                ]
    113             }
    114          }
    115       }
    116 
    1171043.3.  Torrent Status Requests
    118105
    119    Request name is "torrent-status".
     106   Method name: "torrent-status"
     107
    120108   Request arguments: 3.1's optional "ids" argument.
    121109
     
    1291173.4.  Adding a Torrent
    130118
    131    Request name: "torrent-add"
     119   Method name: "torrent-add"
     120
    132121   Request arguments:
    133122
    134123   string             | value type & description
    135124   -------------------+-------------------------------------------------
    136    "autostart"        | boolean   true means to auto-start torrents
     125   "paused"           | boolean   if true, don't start the torrent
    137126   "destination"      | string    path to download the torrent to
    138127   "filename"         | string    location of the .torrent file
     
    148137   Common arguments:
    149138
    150    string             | value type & description
    151    -------------------+-------------------------------------------------
    152    "peer-limit"       | int            maximum number of peers
    153    "speed-limit-down" | int            maximum download speed (in KiB/s)
    154    "speed-limit-up"   | int            maximum upload speed (in KiB/s)
     139   string                     | value type & description
     140   ---------------------------+-------------------------------------------------
     141   "peer-limit"               | int       maximum number of peers
     142   "speed-limit-down"         | int       maximum download speed (in KiB/s)
     143   "speed-limit-down-enabled" | boolean   true if the download speed is limited
     144   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
     145   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
    155146
    1561473.5.1.  Mutators
    157148
    158    Request name: "torrent-set"
     149   Method name: "torrent-set"
    159150   Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
    160151   Response arguments: none
     
    1621533.5.2.  Accessors
    163154
    164    Request name: "torrent-get"
     155   Method name: "torrent-get"
    165156   Request arguments: none
    166157   Response arguments: A "torrents" list of objects containing all
     
    1821733.6.1.  Mutators
    183174
    184     Request name: "torrent-set-file"
     175    Method name: "torrent-set-file"
    185176    Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
    186177    Response arguments: none
     
    1881793.6.2.  Accessors
    189180
    190     Request name: "torrent-get-file"
     181    Method name: "torrent-get-file"
    191182    Request arguments: none
    192183   Response arguments: A "torrents" list of objects containing all
     
    2112024.2.  Mutators
    212203
    213    Request name: "session-set"
     204   Method name: "session-set"
    214205   Request arguments: one or more of 4.1's arguments
    215206   Response arguments: none
     
    2172084.2.  Accessors
    218209
    219    Request name: "session-get"
     210   Method name: "session-get"
    220211   Request arguments: none
    221212   Response arguments: all of 4.1's arguments
  • trunk/libtransmission/Makefile.am

    r5813 r5827  
    1717    handshake.c \
    1818    inout.c \
    19     ipc.c \
    2019    ipcparse.c \
    2120    json.c \
     
    3433    ratecontrol.c \
    3534    resume.c \
     35    rpc.c \
    3636    session.c \
    3737    stats.c \
     
    5858    handshake.h \
    5959    inout.h \
    60     ipc.h \
    6160    ipcparse.h \
    6261    list.h \
     
    7574    ratecontrol.h \
    7675    resume.h \
     76    rpc.h \
    7777    session.h \
    7878    stats.h \
  • trunk/libtransmission/rpc.c

    r5819 r5827  
    1616#include "transmission.h"
    1717#include "bencode.h"
    18 #include "ipc.h"
     18#include "rpc.h"
    1919#include "torrent.h"
    2020#include "utils.h"
     
    246246    {
    247247        tr_torrent * tor = torrents[i];
    248         tr_benc * d = tr_bencListAddDict( list, 4 );
     248        tr_benc * d = tr_bencListAddDict( list, 6 );
    249249        tr_bencDictAddInt( d, "id", tor->uniqueId );
    250250        tr_bencDictAddInt( d, "peer-limit",
     
    252252        tr_bencDictAddInt( d, "speed-limit-down",
    253253                           tr_torrentGetSpeedLimit( tor, TR_DOWN ) );
     254        tr_bencDictAddInt( d, "speed-limit-down-enabled",
     255                           tr_torrentGetSpeedMode( tor, TR_DOWN )
     256                               == TR_SPEEDLIMIT_SINGLE );
    254257        tr_bencDictAddInt( d, "speed-limit-up",
    255258                           tr_torrentGetSpeedLimit( tor, TR_UP ) );
     259        tr_bencDictAddInt( d, "speed-limit-up-enabled",
     260                           tr_torrentGetSpeedMode( tor, TR_UP )
     261                               == TR_SPEEDLIMIT_SINGLE );
    256262    }
    257263
     
    274280        if( tr_bencDictFindInt( args_in, "speed-limit-down", &tmp ) )
    275281            tr_torrentSetSpeedLimit( tor, TR_DOWN, tmp );
     282        if( tr_bencDictFindInt( args_in, "speed-limit-down-enabled", &tmp ) )
     283            tr_torrentSetSpeedMode( tor, TR_DOWN, tmp ? TR_SPEEDLIMIT_SINGLE
     284                                                      : TR_SPEEDLIMIT_GLOBAL );
    276285        if( tr_bencDictFindInt( args_in, "speed-limit-up", &tmp ) )
    277286            tr_torrentSetSpeedLimit( tor, TR_UP, tmp );
     287        if( tr_bencDictFindInt( args_in, "speed-limit-up-enabled", &tmp ) )
     288            tr_torrentSetSpeedMode( tor, TR_UP, tmp ? TR_SPEEDLIMIT_SINGLE
     289                                                    : TR_SPEEDLIMIT_GLOBAL );
    278290    }
    279291
     
    439451        ctor = tr_ctorNew( h );
    440452        tr_ctorSetMetainfoFromFile( ctor, filename );
    441         if( tr_bencDictFindInt( args_in, "autostart", &i ) )
    442             tr_ctorSetPaused( ctor, TR_FORCE, !i );
     453        if( tr_bencDictFindInt( args_in, "paused", &i ) )
     454            tr_ctorSetPaused( ctor, TR_FORCE, i );
    443455        if( tr_bencDictFindInt( args_in, "peer-limit", &i ) )
    444456            tr_ctorSetPeerLimit( ctor, TR_FORCE, i );
     
    539551struct request_handler
    540552{
    541     const char * name;
     553    const char * method;
    542554    handler * func;
    543555} request_handlers[] = {
     
    566578    char * out;
    567579    tr_benc response;
    568     tr_benc * headers_in = NULL;
    569     tr_benc * body_in = NULL;
    570     tr_benc * args_in = NULL;
    571     tr_benc * headers_out = NULL;
    572     tr_benc * body_out = NULL;
     580    tr_benc * args_in = tr_bencDictFind( request, "args" );
    573581    tr_benc * args_out = NULL;
    574582    const char * result = NULL;
    575583
    576     headers_in = tr_bencDictFind( request, "headers" );
    577     body_in = tr_bencDictFind( request, "body" );
    578     args_in = tr_bencDictFind( body_in, "args" );
    579 
    580584    /* build the response skeleton */
    581     tr_bencInitDict( &response, 2 );
    582     headers_out = tr_bencDictAddDict( &response, "headers", 2 );
    583     tr_bencDictAddStr( headers_out, "type", "response" );
    584     if( tr_bencDictFindInt( headers_in, "tag", &i ) )
    585         tr_bencDictAddInt( headers_out, "tag", i );
    586     body_out = tr_bencDictAddDict( &response, "body", 2 );
    587     args_out = tr_bencDictAddDict( body_out, "args", 0 );
     585    tr_bencInitDict( &response, 3 );
     586    if( tr_bencDictFindInt( request, "tag", &i ) )
     587        tr_bencDictAddInt( request, "tag", i );
     588    args_out = tr_bencDictAddDict( &response, "args", 0 );
    588589
    589590    /* parse the request */
    590     if( !tr_bencDictFindStr( body_in, "name", &str ) )
    591         result = "no request name given";
     591    if( !tr_bencDictFindStr( request, "method", &str ) )
     592        result = "no method name";
    592593    else {
    593594        const int n = TR_N_ELEMENTS( request_handlers );
    594595        for( i=0; i<n; ++i )
    595             if( !strcmp( str, request_handlers[i].name ) )
     596            if( !strcmp( str, request_handlers[i].method ) )
    596597                break;
    597598        result = i==n
    598             ? "request name not recognized"
     599            ? "method name not recognized"
    599600            : (*request_handlers[i].func)( handle, args_in, args_out );
    600601    }
     
    602603    /* serialize & return the response */
    603604    if( !result )
    604         result = "success";
    605     tr_bencDictAddStr( body_out, "result", result );
    606     out = tr_bencSave( &response, response_len ); /* TODO: json, not benc */
     605         result = "success";
     606    tr_bencDictAddStr( &response, "result", result );
     607    out = tr_bencSaveAsJSON( &response, response_len );
    607608    tr_bencFree( &response );
    608609    return out;
     
    610611
    611612char*
    612 tr_ipc_request_exec( struct tr_handle  * handle,
     613tr_rpc_request_exec( struct tr_handle  * handle,
    613614                     const void        * request_json,
    614615                     int                 request_len,
  • trunk/libtransmission/rpc.h

    r5817 r5827  
    1111 */
    1212
    13 #ifndef TR_IPC_H
    14 #define TR_IPC_H
     13#ifndef TR_RPC_H
     14#define TR_RPC_H
    1515
    1616struct tr_handle;
    1717
    1818char*
    19 tr_ipc_request_exec( struct tr_handle  * handle,
     19tr_rpc_request_exec( struct tr_handle  * handle,
    2020                     const void        * request_json,
    2121                     int                 request_len,
Note: See TracChangeset for help on using the changeset viewer.