source: trunk/doc/rpc-spec.txt @ 6346

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

(rpc) allocate a bit in torrent-set/torrent-get for detailed peer information

File size: 15.0 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   and an object's "keys" are the dictionary's string keys.
11
122.  Message Format
13
14   Messages are formatted in a subset of JSON easily represented
15   as bencoded data -- arrays, objects, strings, and whole numbers.
16   Booleans are represented as numbers where 0 is false and 1 is true.
17   Floating-point numbers are represented as strings.
18
19   Messages are formatted as objects.  There are two types:
20   requests (described in 2.1) and responses (described in 2.2).
21
222.1.  Requests
23
24   Requests support three keys:
25
26   (1) A required "method" string telling the name of the method to invoke
27   (2) An optional "arguments" object of key/value pairs
28   (3) An optional "tag" number used by clients to track responses.
29       If provided by a request, the response MUST include the same tag.
30
312.2.  Responses
32
33   Reponses support three keys:
34
35   (1) A required "result" string whose value must be "success" on success,
36       or an error string on failure.
37   (2) An optional "arguments" object of key/value pairs
38   (3) An optional "tag" number as described in 2.1.
39
402.3.  Transport Mechanism
41
42   HTTP POSTing a JSON-encoded request is the preferred way of communicating
43   with a Transmission RPC server; however, a simple notation also exists
44   for sending requests in the query portion of a URL.
45
46   The URL notation works as follows:
47   (1) Any key not "tag" or "method" is treated as an argument.
48   (2) The "arguments" key isn't needed, since data isn't nested.
49   (3) If the value in a key/value pair can be parsed as a number, then it is.
50       Otherwise if it can be parsed as an array of numbers, then it is.
51       Otherwise, it's parsed as a string.
52
53   Examples:
54   ?method=torrent-start&ids=1,2
55   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
56
573.  Torrent Requests
58
593.1.  Torrent Action Requests
60
61   Method name         | libtransmission function
62   --------------------+-------------------------------------------------
63   "torrent-remove"    | tr_torrentRemove
64   "torrent-start"     | tr_torrentStart
65   "torrent-stop"      | tr_torrentStop
66   "torrent-verify"    | tr_torrentVerify
67
68   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
69                      or both.  These are the torrents that the request will
70                      be applied to.  If "ids" is ommitted, the request is
71                      applied to all torrents.
72
73   Response arguments: none
74
753.2.  Torrent Mutator
76
77   Method name: "torrent-set"
78
79   Request arguments:
80
81   string                     | value type & description
82   ---------------------------+-------------------------------------------------
83   "files-wanted"             | array      indices of file(s) to download
84   "files-unwanted"           | array      indices of file(s) to not download
85   "ids"                      | array      torrent list, as described in 3.1
86   "peer-limit"               | number     maximum number of peers
87   "priority-high"            | array      indices of high-priority file(s)
88   "priority-low"             | array      indices of low-priority file(s)
89   "priority-normal"          | array      indices of normal-priority file(s)
90   "speed-limit-down"         | number     maximum download speed (in K/s)
91   "speed-limit-down-enabled" | 'boolean'  true if the download speed is limited
92   "speed-limit-up"           | number     maximum upload speed (in K/s)
93   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
94
95   Response arguments: none
96
973.3.  Torrent Accessors
98
99   Method name: "torrent-get".
100
101   Request arguments:
102
103   string       | required? | default | value type & description
104   -------------+-----------+---------+---------------------------------------
105   "ids"        | no        | all     | array     described in 3.1
106   "fields"     | yes       | n/a     | number    bitwise-or'ed field
107                |           |         |           values from the table below
108
109   Response arguments:
110
111   (1) A "fields" number identical to the request's
112   (2) A "torrents" array of objects, each of which contains the
113       key/value fields that match the "fields" argument.
114       See the table below for a complete list.
115
116   "fields" value     | response | response               | source
117                      | value    | key                    |
118   -------------------+----------+------------------------+-------------
119   activity, 1        | number   | desiredAvailable       | tr_stat
120                      | number   | eta                    | tr_stat
121                      | number   | peersConnected         | tr_stat
122                      | number   | peersGettingFromUs     | tr_stat
123                      | number   | peersSendingToUs       | tr_stat
124                      | number   | rateDownload           | tr_stat
125                      | number   | rateUpload             | tr_stat
126                      | number   | recheckProgress        | tr_stat
127                      | number   | status                 | tr_stat
128                      | number   | swarmSpeed (K/s)       | tr_stat
129                      | 'double' | uploadRatio            | tr_stat
130                      | number   | webseedsSendingToUs    | tr_stat
131   -------------------+----------+------------------------+-------------
132   announce, 2        | string   | announceResponse       | tr_stat
133                      | string   | announceURL            | tr_stat
134                      | number   | lastAnnounceTime       | tr_stat
135                      | number   | manualAnnounceTime     | tr_stat
136                      | number   | nextAnnounceTime       | tr_stat
137   -------------------+----------+------------------------+-------------
138   error, 4           | number   | error                  | tr_stat
139                      | number   | errorString            | tr_stat
140   -------------------+----------+------------------------+-------------
141   files, 8           | array    | files
142                      +----------+--------------------------------------
143                      | files is an array of objects that contain:
144                      +----------+------------------------+-------------
145                      | number   | length                 | tr_info
146                      | string   | name                   | tr_info
147   -------------------+----------+------------------------+-------------
148   history, 16        | number   | activityDate           | tr_stat
149                      | number   | addedDate              | tr_stat
150                      | number   | corruptEver            | tr_stat
151                      | number   | doneDate               | tr_stat
152                      | number   | downloadedEver         | tr_stat
153                      | number   | startDate              | tr_stat
154                      | number   | uploadedEver           | tr_stat
155   -------------------+----------+------------------------+-------------
156   id, 32             | number   | uniqueId               | tr_torrent
157                      | string   | hashString             | tr_info
158                      | string   | name                   | tr_info
159   -------------------+----------+------------------------+-------------
160   info, 64           | string   | comment                | tr_info
161                      | string   | creator                | tr_info
162                      | number   | dateCreated            | tr_info
163                      | number   | pieceCount             | tr_info
164                      | number   | pieceSize              | tr_info
165                      | 'boolean'| isPrivate              | tr_torrent
166   -------------------+----------+------------------------+-------------
167   limits, 128        | number   | downloadLimit          | tr_torrent
168                      | number   | downloadLimitMode      | tr_torrent
169                      | number   | maxConnectedPeers      | tr_torrent
170                      | number   | uploadLimit            | tr_torrent
171                      | number   | uploadLimitMode        | tr_torrent
172   -------------------+----------+------------------------+-------------
173   peers, 256         | not defined yet
174   -------------------+----------+------------------------+-------------
175   peer stats, 512    | number   | fromCache              | tr_stat
176                      | number   | fromIncoming           | tr_stat
177                      | number   | fromPex                | tr_stat
178                      | number   | fromTracker            | tr_stat
179   -------------------+----------+------------------------+-------------
180   priorities, 1024   | array    | priorities             | tr_info
181                      | array    | wanted                 | tr_info
182                      +----------+--------------------------------------
183                      | priorities is an array of tr_info.fileCount
184                      | numbers.  Each is the tr_priority_t mode for
185                      | the corresponding file.
186                      +-------------------------------------------------
187                      | wanted is an array of tr_info.fileCount
188                      | 'booleans' true if the corresponding file
189                      | is to be downloaded.
190   -------------------+----------+------------------------+-------------
191   scrape, 2048       | number   | lastScrapeTime         | tr_stat
192                      | number   | nextScrapeTime         | tr_stat
193                      | string   | scrapeResponse         | tr_stat
194                      | string   | scrapeURL              | tr_stat
195   -------------------+----------+------------------------+-------------
196   size, 4096         | number   | haveUnchecked          | tr_stat
197                      | number   | haveValid              | tr_stat
198                      | number   | leftUntilDone          | tr_stat
199                      | number   | sizeWhenDone           | tr_stat
200                      | number   | totalSize              | tr_info
201   -------------------+----------+------------------------+-------------
202   tracker stats,     | number   | leechers               | tr_stat
203   8192               | number   | peersKnown             | tr_stat
204                      | number   | seeders                | tr_stat
205                      | number   | timesCompleted         | tr_stat
206   -------------------+----------+--------------------------------------
207   trackers, 16384    | array    | trackers
208                      +----------+--------------------------------------
209                      | trackers is an array of objects that contain:
210                      +----------+------------------------+-------------
211                      | string   | announce               | tr_info
212                      | string   | scrape                 | tr_info
213                      | number   | tier                   | tr_info
214   -------------------+----------+------------------------+-------------
215   webseeds, 32768    | array    | webseeds
216                      +----------+--------------------------------------
217                      | webseeds is an array of strings:
218                      +----------+------------------------+-------------
219                      | string   | webseed URL            | tr_info
220   -------------------+----------+------------------------+-------------
221
222   Example:
223
224   Say we want to get the name and total size of torrents #7 and #10.
225   name is in the "id" section (32) and total size is in "size" (2048),
226   so the "fields" argument will be 32 + 2048 == 2080.
227
228   Request:
229
230      {
231         "arguments": {
232             "fields": 2080,
233             "ids": [ 7, 10 ],
234             "sort-method": "name"
235         }
236         "method": "torrent-get",
237         "tag": 39693
238      }
239
240
241   Response:
242
243      {
244         "arguments": {
245            "fields": 2080,
246            "torrents": [
247               {
248                   "hashString": "sijioejisoefjiosejfioi",
249                   "haveUnchecked", 23023,
250                   "haveValid", 27986795145,
251                   "leftUntilDone", 0,
252                   "name": "Fedora x86_64 DVD",
253                   "sizeWhenDone", 34983493932,
254                   "totalSize", 34983493932,
255                   "uniqueId": 10,
256               }
257               {
258                   "hashString": "asdasiofjosejfoasjfiosj",
259                   "haveUnchecked", 0,
260                   "haveValid", 9923890123,
261                   "leftUntilDone", 0,
262                   "name": "Ubuntu x86_64 DVD",
263                   "sizeWhenDone", 9923890123,
264                   "totalSize", 9923890123,
265                   "uniqueId": 7,
266               },
267            ]
268         },
269         "result": "success",
270         "tag": 39693
271      }
272
2733.4.  Adding a Torrent
274
275   Method name: "torrent-add"
276
277   Request arguments:
278
279   key                | value type & description
280   -------------------+-------------------------------------------------
281   "download-dir"     | string      path to download the torrent to
282   "filename"         | string      location of the .torrent file
283   "metainfo"         | string      base64-encoded .torrent content
284   "paused"           | 'boolean'   if true, don't start the torrent
285   "peer-limit"       | number      maximum number of peers
286
287   Either "filename" OR "metainfo" must be included.
288   All other arguments are optional.
289
290   Response arguments: on success, a "torrent-added" object in the
291                       form of one of 3.3's tr_info objects with the
292                       fields for id, name, and hashString.
293
294
2954.   Session Requests
296
2974.1.  Session Arguments
298
299   string                     | value type & description
300   ---------------------------+-------------------------------------------------
301   "encryption"               | string     "required", "preferred", "tolerated"
302   "download-dir"             | string     default path to download torrents
303   "peer-limit"               | number     maximum global number of peers
304   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
305   "port"                     | number     port number
306   "port-forwarding-enabled"  | 'boolean'  true means enabled
307   "speed-limit-down"         | number     max global download speed (in K/s)
308   "speed-limit-down-enabled" | 'boolean'  true means enabled
309   "speed-limit-up"           | number     max global upload speed (in K/s)
310   "speed-limit-up-enabled"   | 'boolean'  true means enabled
311
3124.1.1.  Mutators
313
314   Method name: "session-set"
315   Request arguments: one or more of 4.1's arguments
316   Response arguments: none
317
3184.1.2.  Accessors
319
320   Method name: "session-get"
321   Request arguments: none
322   Response arguments: all of 4.1's arguments
323
3244.2.  Session Statistics
325
326   Method name: "session-stats"
327
328   Request arguments: none
329
330   Response arguments:
331
332   string                     | value type
333   ---------------------------+-------------------------------------------------
334   "activeTorrentCount"       | number
335   "downloadSpeed"            | number
336   "pausedTorrentCount"       | number
337   "torrentCount"             | number
338   "uploadSpeed"              | number
339   
340
Note: See TracBrowser for help on using the repository browser.