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

Last change on this file since 8148 was 8148, checked in by charles, 13 years ago

(trunk) fix another rpc seed-ratio problem reported by livings

File size: 26.5 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.
9
10   In benc terms, a JSON "array" is equivalent to a benc list,
11   a JSON "object" is equivalent to a benc dictionary,
12   and a JSON object's "keys" are the dictionary's string keys.
13
142.  Message Format
15
16   Messages are formatted in a subset of JSON easily represented
17   as bencoded data.  Arrays, objects, strings, and whole numbers
18   all have one-to-one mappings between JSON and benc.
19
20   Booleans and floating-point numbers are also used in the JSON messages.
21   Those two types aren't native to benc, so they're encoded this way:
22   Booleans are encoded as numbers where 0 is false and 1 is true.
23   Floating-point numbers are represented as strings.
24
25   Messages are formatted as objects.  There are two types:
26   requests (described in 2.1) and responses (described in 2.2).
27
28   All text MUST be UTF-8 encoded.
29
302.1.  Requests
31
32   Requests support three keys:
33
34   (1) A required "method" string telling the name of the method to invoke
35   (2) An optional "arguments" object of key/value pairs
36   (3) An optional "tag" number used by clients to track responses.
37       If provided by a request, the response MUST include the same tag.
38
392.2.  Responses
40
41   Reponses support three keys:
42
43   (1) A required "result" string whose value MUST be "success" on success,
44       or an error string on failure.
45   (2) An optional "arguments" object of key/value pairs
46   (3) An optional "tag" number as described in 2.1.
47
482.3.  Transport Mechanism
49
50   HTTP POSTing a JSON-encoded request is the preferred way of communicating
51   with a Transmission RPC server.  The current Transmission implementation
52   has the default URL as http://host:9091/transmission/rpc.  Clients
53   may use this as a default, but should allow the URL to be reconfigured,
54   since the port and path may be changed to allow mapping and/or multiple
55   daemons to run on a single server.
56
57   In addition to POSTing, there's also a simple notation for sending
58   requests in the query portion of a URL.  This is not as robust, but can
59   be useful for debugging and simple tasks.  The notation works as follows:
60
61   (1) Any key not "tag" or "method" is treated as an argument.
62   (2) The "arguments" key isn't needed, since data isn't nested.
63   (3) If the value in a key/value pair can be parsed as a number, then it is.
64       Otherwise if it can be parsed as an array of numbers, then it is.
65       Otherwise, it's parsed as a string.
66
67   Examples:
68   ?method=torrent-start&ids=1,2
69   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
70   
71
723.  Torrent Requests
73
743.1.  Torrent Action Requests
75
76   Method name          | libtransmission function
77   ---------------------+-------------------------------------------------
78   "torrent-start"      | tr_torrentStart
79   "torrent-stop"       | tr_torrentStop
80   "torrent-verify"     | tr_torrentVerify
81   "torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
82
83   Request arguments: "ids", which specifies which torrents to use.
84                      All torrents are used if the "ids" argument is omitted.
85                      "ids" should be one of the following:
86                      (1) an integer referring to a torrent id
87                      (2) a list of torrent id numbers, sha1 hash strings, or both
88                      (3) a string, "recently-active", for recently-active torrents
89
90   Response arguments: none
91
923.2.  Torrent Mutators
93
94   Method name: "torrent-set"
95
96   Request arguments:
97
98   string                            | value type & description
99   ----------------------------------+-------------------------------------------------
100   "downloadLimit"                   | number     maximum download speed (in K/s)
101   "downloadLimited"                 | 'boolean'  true if "downloadLimit" is honored
102   "files-wanted"                    | array      indices of file(s) to download
103   "files-unwanted"                  | array      indices of file(s) to not download
104   "honorsSessionLimits"             | 'boolean'  true if session upload limits are honored
105   "ids"                             | array      torrent list, as described in 3.1
106   "peer-limit"                      | number     maximum number of peers
107   "priority-high"                   | array      indices of high-priority file(s)
108   "priority-low"                    | array      indices of low-priority file(s)
109   "priority-normal"                 | array      indices of normal-priority file(s)
110   "seedRatioLimit"                  | 'double'   session seeding ratio
111   "seedRatioMode"                   | number     which ratio to use.  See tr_ratiolimit
112   "uploadLimit"                     | number     maximum upload speed (in K/s)
113   "uploadLimited"                   | 'boolean'  true if "uploadLimit" is honored
114
115   Just as an empty "ids" value is shorthand for "all ids", using an empty array
116   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
117   "priority-normal" is shorthand for saying "all files".
118
119   Response arguments: none
120
1213.3.  Torrent Accessors
122
123   Method name: "torrent-get".
124
125   Request arguments:
126
127   (1) An opional "ids" array as described in 3.1.
128   (2) A required "fields" array of keys. (see list below)
129
130   Response arguments:
131
132   (1) A "torrents" array of objects, each of which contains
133       the key/value pairs matching the request's "fields" argument.
134   (2) If the request's "ids" field was "recently-active",
135       a "removed" array of torrent-id numbers of recently-removed
136       torrents.
137
138   key                             | type                        | source
139   --------------------------------+-----------------------------+---------
140   activityDate                    | number                      | tr_stat
141   addedDate                       | number                      | tr_stat
142   announceResponse                | string                      | tr_stat
143   announceURL                     | string                      | tr_stat
144   comment                         | string                      | tr_info
145   corruptEver                     | number                      | tr_stat
146   creator                         | string                      | tr_info
147   dateCreated                     | number                      | tr_info
148   desiredAvailable                | number                      | tr_stat
149   doneDate                        | number                      | tr_stat
150   downloadDir                     | string                      | tr_torrent
151   downloadedEver                  | number                      | tr_stat
152   downloaders                     | number                      | tr_stat
153   downloadLimit                   | number                      | tr_torrent
154   downloadLimited                 | 'boolean'                   | tr_torrent
155   error                           | number                      | tr_stat
156   errorString                     | number                      | tr_stat
157   eta                             | number                      | tr_stat
158   files                           | array (see below)           | n/a
159   fileStats                       | array (see below)           | n/a
160   hashString                      | string                      | tr_info
161   haveUnchecked                   | number                      | tr_stat
162   haveValid                       | number                      | tr_stat
163   honorsSessionLimits             | 'boolean'                   | tr_torrent
164   id                              | number                      | tr_torrent
165   isPrivate                       | 'boolean'                   | tr_torrent
166   lastAnnounceTime                | number                      | tr_stat
167   lastScrapeTime                  | number                      | tr_stat
168   leechers                        | number                      | tr_stat
169   leftUntilDone                   | number                      | tr_stat
170   manualAnnounceTime              | number                      | tr_stat
171   maxConnectedPeers               | number                      | tr_torrent
172   name                            | string                      | tr_info
173   nextAnnounceTime                | number                      | tr_stat
174   nextScrapeTime                  | number                      | tr_stat
175   peer-limit                      | number                      | tr_torrent
176   peers                           | array (see below)           | n/a
177   peersConnected                  | number                      | tr_stat
178   peersFrom                       | object (see below)          | n/a
179   peersGettingFromUs              | number                      | tr_stat
180   peersKnown                      | number                      | tr_stat
181   peersSendingToUs                | number                      | tr_stat
182   percentDone                     | 'double'                    | tr_stat
183   pieces                          | string (see below)          | tr_torrent
184   pieceCount                      | tnumber                     | tr_info
185   pieceSize                       | tnumber                     | tr_info
186   priorities                      | array (see below)           | n/a
187   ratio                           | 'double'                    | tr_stat
188   rateDownload (B/s)              | number                      | tr_stat
189   rateUpload (B/s)                | number                      | tr_stat
190   recheckProgress                 | 'double'                    | tr_stat
191   scrapeResponse                  | string                      | tr_stat
192   scrapeURL                       | string                      | tr_stat
193   seeders                         | number                      | tr_stat
194   seedRatioLimit                  | 'double'                    | tr_torrent
195   seedRatioMode                   | number                      | tr_ratiolimit
196   sizeWhenDone                    | number                      | tr_stat
197   startDate                       | number                      | tr_stat
198   status                          | number                      | tr_stat
199   swarmSpeed (K/s)                | number                      | tr_stat
200   timesCompleted                  | number                      | tr_stat
201   trackers                        | array (see below)           | n/a
202   totalSize                       | number                      | tr_info
203   torrentFile                     | string                      | tr_info
204   uploadedEver                    | number                      | tr_stat
205   uploadLimit                     | number                      | tr_torrent
206   uploadLimited                   | 'boolean'                   | tr_torrent
207   uploadRatio                     | 'double'                    | tr_stat
208   wanted                          | array (see below)           | n/a
209   webseeds                        | array (see below)           | n/a
210   webseedsSendingToUs             | number                      | tr_stat
211                                   |                             |
212                                   |                             |
213   -----------------------+--------+-----------------------------+
214   files                  | array of objects, each containing:   |
215                          +-------------------------+------------+
216                          | key                     | type       |
217                          | bytesCompleted          | number     | tr_torrent
218                          | length                  | number     | tr_info
219                          | name                    | string     | tr_info
220   -----------------------+--------------------------------------+
221   fileStats              | a file's non-constant properties.    |
222                          | array of tr_info.filecount objects,  |
223                          | each containing:                     |
224                          +-------------------------+------------+
225                          | bytesCompleted          | number     | tr_torrent
226                          | wanted                  | 'boolean'  | tr_info
227                          | priority                | number     | tr_info
228   -----------------------+--------------------------------------+
229   peers                  | array of objects, each containing:   |
230                          +-------------------------+------------+
231                          | address                 | string     | tr_peer_stat
232                          | clientName              | string     | tr_peer_stat
233                          | clientIsChoked          | 'boolean'  | tr_peer_stat
234                          | clientIsInterested      | 'boolean'  | tr_peer_stat
235                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
236                          | isEncrypted             | 'boolean'  | tr_peer_stat
237                          | isIncoming              | 'boolean'  | tr_peer_stat
238                          | isUploadingTo           | 'boolean'  | tr_peer_stat
239                          | peerIsChoked            | 'boolean'  | tr_peer_stat
240                          | peerIsInterested        | 'boolean'  | tr_peer_stat
241                          | port                    | number     | tr_peer_stat
242                          | progress                | 'double'   | tr_peer_stat
243                          | rateToClient (B/s)      | number     | tr_peer_stat
244                          | rateToPeer (B/s)        | number     | tr_peer_stat
245   -----------------------+--------------------------------------+
246   peersFrom              | an object containing:                |
247                          +-------------------------+------------+
248                          | fromCache               | number     | tr_stat
249                          | fromIncoming            | number     | tr_stat
250                          | fromPex                 | number     | tr_stat
251                          | fromTracker             | number     | tr_stat
252   -----------------------+--------------------------------------+
253   pieces                 | A bitfield holding pieceCount flags  | tr_torrent
254                          | which are set to 'true' if we have   |
255                          | the piece matching that position.    |
256                          | JSON doesn't allow raw binary data,  |
257                          | so this is a base64-encoded string.  |
258   -----------------------+--------------------------------------+
259   priorities             | an array of tr_info.filecount        | tr_info
260                          | numbers. each is the tr_priority_t   |
261                          | mode for the corresponding file.     |
262   -----------------------+--------------------------------------+
263   trackers               | array of objects, each containing:   |
264                          +-------------------------+------------+
265                          | announce                | string     | tr_info
266                          | scrape                  | string     | tr_info
267                          | tier                    | number     | tr_info
268   -----------------------+--------------------------------------+
269   wanted                 | an array of tr_info.fileCount        | tr_info
270                          | 'booleans' true if the corresponding |
271                          | file is to be downloaded.            |
272   -----------------------+--------------------------------------+
273   webseeds               | an array of strings:                 |
274                          +-------------------------+------------+
275                          | webseed                 | string     | tr_info
276                          +-------------------------+------------+
277
278   Example:
279
280   Say we want to get the name and total size of torrents #7 and #10.
281
282   Request:
283
284      {
285         "arguments": {
286             "fields": [ "id", "name", "totalSize" ],
287             "ids": [ 7, 10 ]
288         },
289         "method": "torrent-get",
290         "tag": 39693
291      }
292
293
294   Response:
295
296      {
297         "arguments": {
298            "torrents": [
299               {
300                   "id": 10,
301                   "name": "Fedora x86_64 DVD",
302                   "totalSize", 34983493932,
303               },
304               {
305                   "id": 7,
306                   "name": "Ubuntu x86_64 DVD",
307                   "totalSize", 9923890123,
308               }
309            ]
310         },
311         "result": "success",
312         "tag": 39693
313      }
314
3153.4.  Adding a Torrent
316
317   Method name: "torrent-add"
318
319   Request arguments:
320
321   key                | value type & description
322   -------------------+-------------------------------------------------
323   "download-dir"     | string      path to download the torrent to
324   "filename"         | string      filename or URL of the .torrent file
325   "metainfo"         | string      base64-encoded .torrent content
326   "paused"           | 'boolean'   if true, don't start the torrent
327   "peer-limit"       | number      maximum number of peers
328   "files-wanted"     | array       indices of file(s) to download
329   "files-unwanted"   | array       indices of file(s) to not download
330   "priority-high"    | array       indices of high-priority file(s)
331   "priority-low"     | array       indices of low-priority file(s)
332   "priority-normal"  | array       indices of normal-priority file(s)
333
334   Either "filename" OR "metainfo" MUST be included.
335   All other arguments are optional.
336
337   Response arguments: on success, a "torrent-added" object in the
338                       form of one of 3.3's tr_info objects with the
339                       fields for id, name, and hashString.
340
3413.5.  Removing a Torrent
342
343   Method name: "torrent-remove"
344
345   Request arguments:
346
347   string                     | value type & description
348   ---------------------------+-------------------------------------------------
349   "ids"                      | array      torrent list, as described in 3.1
350   "delete-local-data"        | 'boolean'  delete local data. (default: false)
351
352   Response arguments: none
353
354
3554.   Session Requests
356
3574.1.  Session Arguments
358
359   string                     | value type & description
360   ---------------------------+-------------------------------------------------
361   "alt-speed-down"           | number     max global download speed (in K/s)
362   "alt-speed-enabled"        | 'boolean'  true means use the alt speeds
363   "alt-speed-time-begin"     | number     when to turn on alt speeds (units: minutes after midnight)
364   "alt-speed-time-enabled"   | 'boolean'  true means the scheduled on/off times are used
365   "alt-speed-time-end"       | number     when to turn off alt speeds (units: same)
366   "alt-speed-time-day"       | number     what day(s) to turn on alt speeds (look at tr_sched_day)
367   "alt-speed-up"             | number     max global upload speed (in K/s)
368   "blocklist-enabled"        | 'boolean'  true means enabled
369   "blocklist-size"           | number     number of rules in the blocklist
370   "encryption"               | string     "required", "preferred", "tolerated"
371   "download-dir"             | string     default path to download torrents
372   "peer-limit-global"        | number     maximum global number of peers
373   "peer-limit-per-torrent"   | number     maximum global number of peers
374   "pex-enabled"              | 'boolean'  true means allow pex in public torrents
375   "peer-port"                | number     port number
376   "peer-port-random-on-start"| 'boolean'  true means pick a random peer port on launch
377   "port-forwarding-enabled"  | 'boolean'  true means enabled
378   "rpc-version"              | number     the current RPC API version
379   "rpc-version-minimum"      | number     the minimum RPC API version supported
380   "seedRatioLimit"           | 'double'   the default seed ratio for torrents to use
381   "seedRatioLimited"         | 'boolean'  true if seedRatioLimit is honored by default
382   "speed-limit-down"         | number     max global download speed (in K/s)
383   "speed-limit-down-enabled" | 'boolean'  true means enabled
384   "speed-limit-up"           | number     max global upload speed (in K/s)
385   "speed-limit-up-enabled"   | 'boolean'  true means enabled
386   "version"                  | string     long version string "$version ($revision)"
387
388   "rpc-version" indicates the RPC interface version supported by the RPC server.
389   It is incremented when a new version of Transmission changes the RPC interface.
390
391   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
392   It is changes when a new version of Transmission changes the RPC interface
393   in a way that is not backwards compatible.  There are no plans for this
394   to be common behavior.
395
3964.1.1.  Mutators
397
398   Method name: "session-set"
399   Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
400                      "rpc-version", "rpc-version-minimum", and "version"
401   Response arguments: none
402
4034.1.2.  Accessors
404
405   Method name: "session-get"
406   Request arguments: none
407   Response arguments: all of 4.1's arguments
408
4094.2.  Session Statistics
410
411   Method name: "session-stats"
412
413   Request arguments: none
414
415   Response arguments:
416
417   string                     | value type
418   ---------------------------+-------------------------------------------------
419   "activeTorrentCount"       | number
420   "downloadSpeed"            | number
421   "pausedTorrentCount"       | number
422   "torrentCount"             | number
423   "uploadSpeed"              | number
424   ---------------------------+-------------------------------+
425   "cumulative-stats"         | object, containing:           |
426                              +------------------+------------+
427                              | uploadedBytes    | number     | tr_session_stats
428                              | downloadedBytes  | number     | tr_session_stats
429                              | filesAdded       | number     | tr_session_stats
430                              | sessionCount     | number     | tr_session_stats
431                              | secondsActive    | number     | tr_session_stats
432   ---------------------------+-------------------------------+
433   "current-stats"            | object, containing:           |
434                              +------------------+------------+
435                              | uploadedBytes    | number     | tr_session_stats
436                              | downloadedBytes  | number     | tr_session_stats
437                              | filesAdded       | number     | tr_session_stats
438                              | sessionCount     | number     | tr_session_stats
439                              | secondsActive    | number     | tr_session_stats
440
4414.3.  Blocklist
442
443   Method name: "blocklist-update"
444   Request arguments: none
445   Response arguments: "blocklist-size"
446   
447
4485.0.  Protocol Versions
449
450  The following changes have been made to the RPC interface:
451
452   RPC   | Release | Backwards |                |
453   Vers. | Version | Compat?   | Method         | Description
454   ------+---------+-----------+----------------+-------------------------------
455   1     | 1.30    | n/a       | n/a            | Initial version
456   ------+---------+-----------+----------------+-------------------------------
457   2     | 1.34    | yes       | torrent-get    | new arg "peers"
458   ------+---------+-----------+----------------+-------------------------------
459   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
460         |         | yes       | torrent-get    | new arg "downloaders"
461         |         | yes       | session-get    | new arg "version"
462         |         | yes       | torrent-remove | new method
463   ------+---------+-----------+----------------+-------------------------------
464   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
465         |         | yes       | session-get    | new arg "rpc-version-minimum"
466         |         | yes       | session-stats  | added "cumulative-stats"
467         |         | yes       | session-stats  | added "current-stats"
468         |         | yes       | torrent-get    | new arg "downloadDir"
469   ------+---------+-----------+----------------+-------------------------------
470   6     | 1.60    | yes       | torrent-get    | new arg "pieces"
471         |         | yes       | torrent-get    | new arg "fileStats"
472         |         | yes       | torrent-set    | new arg "ratio"
473         |         | yes       | torrent-set    | new arg "downloadLimited"
474         |         | yes       | torrent-set    | new arg "uploadLimited"
475         |         | yes       | torrent-set    | new arg "honorsSessionLimits"
476         |         | yes       | torrent-add    | new arg "files-wanted"
477         |         | yes       | torrent-add    | new arg "files-unwanted"
478         |         | yes       | torrent-add    | new arg "priority-high"
479         |         | yes       | torrent-add    | new arg "priority-low"
480         |         | yes       | torrent-add    | new arg "priority-normal"
481         |         | yes       | session-get    | new arg "seedRatioLimit"
482         |         | yes       | session-get    | new arg "seedRatioLimited"
483         |         | yes       | session-get    | new arg "alt-speed-enabled"
484         |         | yes       | session-get    | new arg "alt-speed-time-enabled"
485         |         | yes       | session-get    | new arg "alt-speed-up"
486         |         | yes       | session-get    | new arg "alt-speed-down"
487         |         | yes       | session-get    | new arg "alt-speed-begin"
488         |         | yes       | session-get    | new arg "alt-speed-end"
489         |         | yes       | session-get    | new arg "blocklist-enabled"
490         |         | yes       | session-get    | new arg "blocklist-size"
491         |         | yes       | session-get    | new arg "peer-limit-per-torrent"
492         |         | yes       | torrent-get    | new arg "seedRatioLimit"
493         |         | yes       | torrent-get    | new arg "seedRatioMode"
494         |         | yes       | torrent-get    | new arg "torrentFile"
495         |         | yes       | torrent-get    | new ids option "recently-active"
496         |         | yes       | torrent-get    | new ids option "percentDone"
497         |         | yes       |                | new method "torrent-reannounce"
498         |         | yes       |                | new method "blocklist-update"
499         |         |        NO | torrent-get    | removed arg "downloadLimitMode"
500         |         |        NO | torrent-get    | removed arg "uploadLimitMode"
501         |         |        NO | session-get    | renamed "pex-allowed" to "pex-enabled"
502         |         |        NO | session-get    | renamed "port" to "peer-port"
503         |         |        NO | session-get    | renamed "peer-limit" to "peer-limit-global"
504   ------+---------+-----------+----------------+-------------------------------
505
506
Note: See TracBrowser for help on using the repository browser.