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

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

json ipc: implement torrent-add, torrent-set-file, torrent-get-file

File size: 7.2 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   Messages are 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 pairs.
37
382.3.  Response Body
39
40   All response bodies support two members:
41   (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.
45
463.  Torrent Requests
47
483.1.  Torrent Action Requests
49
50   Request names: "torrent-start", "torrent-stop",
51                  "torrent-remove", "torrent-verify"
52   Request arguments: "ids", a list of unique torrent ids, sha1 hash strings,
53                      or both.  These are the torrents that the request will
54                      be applied to.  If "ids" is ommitted, the request is
55                      applied to all torrents.
56   Response arguments: none.
57
583.2.  Torrent Info Requests
59
60   Request name: "torrent-info".
61   Request arguments: 3.1's optional "ids" argument.
62
63   Response arguments: "info", an array of objects based on libtransmission's
64   tr_info struct but differ in the following ways:
65
66   (1) tr_info's "hash" field is omitted.
67   (2) tr_info's "pieces" field is omitted.
68   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
69
70   Example Request:
71
72      {
73         "headers": {
74            "type": "request",
75            "tag": 666
76         },
77         "body": {
78            "name": "torrent-info",
79            "arguments": {
80               "ids": [ 7, 10 ]
81            }
82         }
83      }
84
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
1173.3.  Torrent Status Requests
118
119   Request name is "torrent-status".
120   Request arguments: 3.1's optional "ids" argument.
121
122   Response arguments: "status", an array of objects based on
123   libtransmission's tr_stat struct but which differ the following ways:
124
125   (1) tr_stat's "tracker" field is omitted
126   (2) a new string, "announce-url", is added
127   (3) a new string, "scrape-url", is added
128
1293.4.  Adding a Torrent
130
131   Request name: "torrent-add"
132   Request arguments:
133
134   string             | value type & description
135   -------------------+-------------------------------------------------
136   "autostart"        | boolean   true means to auto-start torrents
137   "destination"      | string    path to download the torrent to
138   "filename"         | string    location of the .torrent file
139   "max-peers"        | int       maximum number of peers
140
141   The "filename" argument is required; all others are optional.
142
143   Response arguments: on success, a "torrent-added" object in the
144                       form of one of 3.1's tr_info objects.
145
1463.5.  Other torrent settings
147
148   Common arguments:
149
150   string             | value type & description
151   -------------------+-------------------------------------------------
152   "max-peers"        | 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)
155
1563.5.1.  Mutators
157
158   Request name: "torrent-set"
159   Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
160   Response arguments: none
161
1623.5.2.  Accessors
163
164   Request name: "torrent-get"
165   Request arguments: none
166   Response arguments: A "torrents" list of objects containing all
167                       of 3.5's arguments plus the torrent's "id" int.
168                     
169
1703.6  File Priorities
171
172   Common arguments:
173
174   string             | value type & description
175   -------------------+-------------------------------------------------
176   "priority-high"    | array     indices of one or more high-priority files
177   "priority-low"     | array     indices of one or more low-priority files
178   "priority-normal"  | array     indices of one or more normal-priority files
179   "download"         | array     indices of one or more file to download
180   "no-download"      | array     indices of one or more file to not download
181
1823.6.1.  Mutators
183
184    Request name: "torrent-set-file"
185    Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
186    Response arguments: none
187
1883.6.2.  Accessors
189
190    Request name: "torrent-get-file"
191    Request arguments: none
192   Response arguments: A "torrents" list of objects containing all
193                       of 3.6's arguments plus the torrent's "id" int.
194   
1954.   Session Status Requests
196
1974.1.  Session Arguments
198
199   string             | value type & description
200   -------------------+-------------------------------------------------
201   "autostart"        | boolean   true means to auto-start torrents
202   "destination"      | string    path to download torrents to
203   "encryption"       | string    "required", "preferred", or "plaintext"
204   "max-peers"        | int       maximum global number of peers
205   "port"             | int       port number
206   "port-forwarding"  | boolean   true means enabled.
207   "pex-allowed"      | boolean   true means allow pex for public torrents
208   "speed-limit-down" | int       maximum global download speed (in KiB/s)
209   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)
210
2114.2.  Mutators
212
213   Request name: "session-set"
214   Request arguments: one or more of 4.1's arguments
215   Response arguments: none
216
2174.2.  Accessors
218
219   Request name: "session-get"
220   Request arguments: none
221   Response arguments: all of 4.1's arguments
222
Note: See TracBrowser for help on using the repository browser.