source: trunk/doc/ipc-json-spec.txt @ 5801

Last change on this file since 5801 was 5801, checked in by charles, 14 years ago

readability

File size: 5.6 KB
Line 
11.  Introduction
2
3   This document describes a protocol for interacting with Transmission
4   sessions remotely.
5
61.1  Terminology
7
8   The JSON terminology in RFC 4627 is used. "array" is equivalent
9   to a benc list; "object" is equivalent to a benc dictionary;
10   an object's "strings" are the dictionary's keys,
11   and an object's "members" are its string/value pairs.
12
132.  Message Format
14
15   The entire protocol is formatted in a subset of JSON that understands
16   arrays, maps, strings, and whole numbers with no exponentials --
17   in short, the subset of JSON easily represented in benc.
18   floating-point numbers are represented as strings.
19   booleans are represented as integers where 0 is false and 1 is true.
20
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
252.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
322.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 argument pairs.
37
382.3.  Response Body
39
40   Response bodies support two members:
41   (1) An optional "arguments" object of argument name/value pairs.
42   (2) An optional "error" string which may be omitted on success.
43
443.  Torrent Requests
45
463.1.  Common Arguments
47
48   Most torrent requests support an "ids" argument, which is a list
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.
52
533.2.  Torrent Action Requests
54
55   Request names: "torrent-start", "torrent-stop",
56                  "torrent-remove", "torrent-verify"
57   The only supported argument is 3.1's "ids" argument.
58   The response has no arguments.
59
603.3.  Torrent Info Requests
61
62   Request name: "torrent-info".
63   The only supported argument is 3.1's "ids" argument.
64
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:
68
69   (1) tr_info's "hash" field is omitted.
70   (2) tr_info's "pieces" field is omitted.
71   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
72
73   Example Request:
74
75      {
76         "headers": {
77            "type": "request",
78            "tag": 666
79         },
80         "body": {
81            "arguments": {
82               "name": "torrent-info",
83               "ids": [1, 2]
84            }
85         }
86      }
87
88   Example Response:
89
90      {
91         "headers": {
92            "type": "response",
93            "tag": 666
94         }
95         "body": {
96            "arguments": {
97               "info": [
98                  {
99                     "id": 1,
100                     "totalSize": 9803930483,
101                     "pieceCount": 1209233,
102                     "pieceSize": 4096,
103                     "name": "Ubuntu x86_64 DVD",
104                     ...
105                  }
106                  {
107                     "id": 2,
108                     "totalSize": 2398480394,
109                     "pieceCount": 83943,
110                     "pieceSize": 12345,
111                     "name": "Ubuntu i386 DVD",
112                     ...
113                  }
114               }
115            }
116         }
117      }
118
1193.4.  Torrent Status Requests
120
121   Request name is "torrent-status".
122   The only supported argument is 3.1's "ids" argument.
123
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:
127
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
131
1323.5.  Adding a Torrent
133
134   Request name is "torrent-add".
135   All arguments are optional except "filename".
136   Supported arguments are:
137
138   string             | value type & description
139   -------------------+-------------------------------------------------
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)
146
147
1484.   Session Status Requests
149
1504.1.  Mutators
151
152   The request name to change the session's state is "session-set".
153   Supported arguments are:
154
155   string             | value type & description
156   -------------------+-------------------------------------------------
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)
166
1674.2.  Accessors
168
169   Request name: "session-get"
170   Request arguments: none
171   Response arguments: all the arguments described in 4.1.
172
Note: See TracBrowser for help on using the repository browser.