Changeset 5801 for trunk/doc/ipc-json-spec.txt

Timestamp:

May 10, 2008, 4:11:00 PM (14 years ago)

Author:

charles

Message:

readability

File:

• trunk/doc/ipc-json-spec.txt (modified) (11 diffs)

trunk/doc/ipc-json-spec.txt

@@ -3 +3 @@
    This document describes a protocol for interacting with Transmission
    sessions remotely.
+
+1.1  Terminology
 
    The JSON terminology in RFC 4627 is used. "array" is equivalent
@@ -17 +19 @@
    booleans are represented as integers where 0 is false and 1 is true.
 
-   There are only two message types, request and response.  Both have
-   the same format: an object with two members whose strings are
-   "headers" and "body", and whose values are both objects.
+   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
@@ -25 +27 @@
    Message headers support two members:
    (1) A required "type" string whose value must be "request" or "response".
-   (2) An optional "tag" integer that may be supplied by request.
-       Responses MUST return an identical tag member.
+   (2) An optional "tag" integer supplied by requests for their own use.
+       Responses MUST include the request tag's verbatim.
 
 2.2.  Request Body
@@ -32 +34 @@
    Request bodies support two members:
    (1) A required "name" string telling the name of the request.
-   (2) An optional "arguments" object of argument name/value pairs.
+   (2) An optional "arguments" object of name/value argument pairs.
 
 2.3.  Response Body
 
-   Response bodies support three members:
-   (1) A required "name" string which matches the request's name.
+   Response bodies support two members:
+   (1) An optional "arguments" object of argument name/value pairs.
    (2) An optional "error" string which may be omitted on success.
-   (3) An optional "arguments" object of argument name/value pairs.
 
 3.  Torrent Requests
@@ -46 +47 @@
 
    Most torrent requests support an "ids" argument, which is a list
-   containing unique torrent information ids, or torrent sha1 hash strings,
-   or both.  These are the torrents that the request will be applied to.
-   If the ids are omitted, the request is applied to all torrents.
+   containing unique torrent ids, or torrent sha1 hash strings, or both.
+   These are the torrents that the request will be applied to.
+   If "ids" is omitted, the request is applied to all torrents.
 
 3.2.  Torrent Action Requests
 
-   Request names: "torrent-start", "torrent-stop", "torrent-remove",
-"torrent-verify".
+   Request names: "torrent-start", "torrent-stop",
+                  "torrent-remove", "torrent-verify"
    The only supported argument is 3.1's "ids" argument.
    The response has no arguments.
@@ -59 +60 @@
 3.3.  Torrent Info Requests
 
-   Request name is "torrent-info".
+   Request name: "torrent-info".
    The only supported argument is 3.1's "ids" argument.
 
-   The response's arguments object contains a member whose string
-   is "info" and whose value is an array of tr_info objects.
-   tr_info objects are (nearly) 1-to-1 mappings of libtransmission's
-   tr_info struct, where the members' string in the tr_info field name,
-   and the members' value is the field's value.
+   The response will contain an "info" argument holding an array of
+   tr_info objects.  these are a (nearly) 1-to-1 mapping of
+   libtransmission's tr_info struct, but differ in the following ways:
 
-   The tr_info object differs from libtransmission's tr_info struct
-   in the following ways:
    (1) tr_info's "hash" field is omitted.
    (2) tr_info's "pieces" field is omitted.
@@ -78 +75 @@
       {
          "headers": {
-            "type": "request"
+            "type": "request",
+            "tag": 666
          },
          "body": {
@@ -92 +90 @@
       {
          "headers": {
-            "type": "response"
+            "type": "response",
+            "tag": 666
          }
          "body": {
@@ -123 +122 @@
    The only supported argument is 3.1's "ids" argument.
 
-   The response's arguments contains a member whose string is "status"
-   and whose value is an array of tr_stat objects.  tr_stat objects
-   are (nearly) 1-to-1 mappings of libtransmission's tr_stat struct,
-   where the members' string in the tr_stat field name, and the
-   members' value is the field's value.
+   The response will contain a "status" argument holding an array of
+   tr_stat objects.  these are a (nearly) 1-to-1 mapping of
+   libtransmission's tr_stat struct, but differ in the following ways:
 
-   The tr_stat object differs from libtransmission's tr_stat struct
-   in the following ways:
-
-   (1) tr_stat's "tracker" field is omitted and replaced 
-       with two fields: "announce-url" and "scrape-url"
+   (1) tr_stat's "tracker" field is omitted
+   (2) a new string, "announce-url", is added
+   (3) a new string, "scrape-url", is added
 
 3.5.  Adding a Torrent
@@ -143 +138 @@
    string             | value type & description
    -------------------+-------------------------------------------------
-   "autostart"        | boolean.  true means to auto-start torrents.
-   "directory"        | string.   path to download the torrent to.
-   "filename"         | string.   location of the .torrent file.
-   "speed-limit-up"   | int.      speed in KiB/s
-   "speed-limit-down" | int.      speed in KiB/s
+   "autostart"        | boolean   true means to auto-start torrents
+   "directory"        | string    path to download the torrent to
+   "filename"         | string    location of the .torrent file
+   "max-peers"        | 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)
 
 
@@ -159 +155 @@
    string             | value type & description
    -------------------+-------------------------------------------------
-   "autostart"        | boolean.  true means to auto-start torrents.
-   "directory"        | string.   path to download torrents to.
-   "encryption"       | string.   "required", "preferred", or "plaintext"
-   "port"             | int.      port number
-   "port-forwarding"  | boolean.  true means enabled.
-   "pex-allowed"      | boolean.  true means allow pex for public torrents.
-   "speed-limit-up"   | int.      speed in KiB/s
-   "speed-limit-down" | int.      speed in KiB/s
+   "autostart"        | boolean   true means to auto-start torrents
+   "directory"        | string    path to download torrents to
+   "encryption"       | string    "required", "preferred", or "plaintext"
+   "max-peers"        | int       maximum global number of peers
+   "port"             | int       port number
+   "port-forwarding"  | boolean   true means enabled.
+   "pex-allowed"      | boolean   true means allow pex for public torrents
+   "speed-limit-down" | int       maximum global download speed (in KiB/s)
+   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)
 
 4.2.  Accessors