Changeset 5801


Ignore:
Timestamp:
May 10, 2008, 4:11:00 PM (14 years ago)
Author:
charles
Message:

readability

File:
1 edited

Legend:

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

    r5799 r5801  
    33   This document describes a protocol for interacting with Transmission
    44   sessions remotely.
     5
     61.1  Terminology
    57
    68   The JSON terminology in RFC 4627 is used. "array" is equivalent
     
    1719   booleans are represented as integers where 0 is false and 1 is true.
    1820
    19    There are only two message types, request and response.  Both have
    20    the same format: an object with two members whose strings are
    21    "headers" and "body", and whose values are both objects.
     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).
    2224
    23252.1.  Headers
     
    2527   Message headers support two members:
    2628   (1) A required "type" string whose value must be "request" or "response".
    27    (2) An optional "tag" integer that may be supplied by request.
    28        Responses MUST return an identical tag member.
     29   (2) An optional "tag" integer supplied by requests for their own use.
     30       Responses MUST include the request tag's verbatim.
    2931
    30322.2.  Request Body
     
    3234   Request bodies support two members:
    3335   (1) A required "name" string telling the name of the request.
    34    (2) An optional "arguments" object of argument name/value pairs.
     36   (2) An optional "arguments" object of name/value argument pairs.
    3537
    36382.3.  Response Body
    3739
    38    Response bodies support three members:
    39    (1) A required "name" string which matches the request's name.
     40   Response bodies support two members:
     41   (1) An optional "arguments" object of argument name/value pairs.
    4042   (2) An optional "error" string which may be omitted on success.
    41    (3) An optional "arguments" object of argument name/value pairs.
    4243
    43443.  Torrent Requests
     
    4647
    4748   Most torrent requests support an "ids" argument, which is a list
    48    containing unique torrent information ids, or torrent sha1 hash strings,
    49    or both.  These are the torrents that the request will be applied to.
    50    If the ids are omitted, the request is applied to all torrents.
     49   containing unique torrent ids, or torrent sha1 hash strings, or both.
     50   These are the torrents that the request will be applied to.
     51   If "ids" is omitted, the request is applied to all torrents.
    5152
    52533.2.  Torrent Action Requests
    5354
    54    Request names: "torrent-start", "torrent-stop", "torrent-remove",
    55 "torrent-verify".
     55   Request names: "torrent-start", "torrent-stop",
     56                  "torrent-remove", "torrent-verify"
    5657   The only supported argument is 3.1's "ids" argument.
    5758   The response has no arguments.
     
    59603.3.  Torrent Info Requests
    6061
    61    Request name is "torrent-info".
     62   Request name: "torrent-info".
    6263   The only supported argument is 3.1's "ids" argument.
    6364
    64    The response's arguments object contains a member whose string
    65    is "info" and whose value is an array of tr_info objects.
    66    tr_info objects are (nearly) 1-to-1 mappings of libtransmission's
    67    tr_info struct, where the members' string in the tr_info field name,
    68    and the members' value is the field's value.
     65   The response will contain an "info" argument holding an array of
     66   tr_info objects.  these are a (nearly) 1-to-1 mapping of
     67   libtransmission's tr_info struct, but differ in the following ways:
    6968
    70    The tr_info object differs from libtransmission's tr_info struct
    71    in the following ways:
    7269   (1) tr_info's "hash" field is omitted.
    7370   (2) tr_info's "pieces" field is omitted.
     
    7875      {
    7976         "headers": {
    80             "type": "request"
     77            "type": "request",
     78            "tag": 666
    8179         },
    8280         "body": {
     
    9290      {
    9391         "headers": {
    94             "type": "response"
     92            "type": "response",
     93            "tag": 666
    9594         }
    9695         "body": {
     
    123122   The only supported argument is 3.1's "ids" argument.
    124123
    125    The response's arguments contains a member whose string is "status"
    126    and whose value is an array of tr_stat objects.  tr_stat objects
    127    are (nearly) 1-to-1 mappings of libtransmission's tr_stat struct,
    128    where the members' string in the tr_stat field name, and the
    129    members' value is the field's value.
     124   The response will contain a "status" argument holding an array of
     125   tr_stat objects.  these are a (nearly) 1-to-1 mapping of
     126   libtransmission's tr_stat struct, but differ in the following ways:
    130127
    131    The tr_stat object differs from libtransmission's tr_stat struct
    132    in the following ways:
    133 
    134    (1) tr_stat's "tracker" field is omitted and replaced
    135        with two fields: "announce-url" and "scrape-url"
     128   (1) tr_stat's "tracker" field is omitted
     129   (2) a new string, "announce-url", is added
     130   (3) a new string, "scrape-url", is added
    136131
    1371323.5.  Adding a Torrent
     
    143138   string             | value type & description
    144139   -------------------+-------------------------------------------------
    145    "autostart"        | boolean.  true means to auto-start torrents.
    146    "directory"        | string.   path to download the torrent to.
    147    "filename"         | string.   location of the .torrent file.
    148    "speed-limit-up"   | int.      speed in KiB/s
    149    "speed-limit-down" | int.      speed in KiB/s
     140   "autostart"        | boolean   true means to auto-start torrents
     141   "directory"        | string    path to download the torrent to
     142   "filename"         | string    location of the .torrent file
     143   "max-peers"        | int       maximum number of peers
     144   "speed-limit-down" | int       maximum download speed (in KiB/s)
     145   "speed-limit-up"   | int       maximum upload speed (in KiB/s)
    150146
    151147
     
    159155   string             | value type & description
    160156   -------------------+-------------------------------------------------
    161    "autostart"        | boolean.  true means to auto-start torrents.
    162    "directory"        | string.   path to download torrents to.
    163    "encryption"       | string.   "required", "preferred", or "plaintext"
    164    "port"             | int.      port number
    165    "port-forwarding"  | boolean.  true means enabled.
    166    "pex-allowed"      | boolean.  true means allow pex for public torrents.
    167    "speed-limit-up"   | int.      speed in KiB/s
    168    "speed-limit-down" | int.      speed in KiB/s
     157   "autostart"        | boolean   true means to auto-start torrents
     158   "directory"        | string    path to download torrents to
     159   "encryption"       | string    "required", "preferred", or "plaintext"
     160   "max-peers"        | int       maximum global number of peers
     161   "port"             | int       port number
     162   "port-forwarding"  | boolean   true means enabled.
     163   "pex-allowed"      | boolean   true means allow pex for public torrents
     164   "speed-limit-down" | int       maximum global download speed (in KiB/s)
     165   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)
    169166
    1701674.2.  Accessors
Note: See TracChangeset for help on using the changeset viewer.