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

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

(trunk) libT and gtk+ parts for #1889: per-torrent vs. global speed limit confusion

File size: 22.1 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
82   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
83                      or both.  These are the torrents that the request will
84                      be applied to.  If "ids" is ommitted, the request is
85                      applied to all torrents.
86
87   Response arguments: none
88
893.2.  Torrent Mutators
90
91   Method name: "torrent-set"
92
93   Request arguments:
94
95   string                            | value type & description
96   ----------------------------------+-------------------------------------------------
97   "files-wanted"                    | array      indices of file(s) to download
98   "files-unwanted"                  | array      indices of file(s) to not download
99   "ids"                             | array      torrent list, as described in 3.1
100   "peer-limit"                      | number     maximum number of peers
101   "priority-high"                   | array      indices of high-priority file(s)
102   "priority-low"                    | array      indices of low-priority file(s)
103   "priority-normal"                 | array      indices of normal-priority file(s)
104   "speed-limit-down"                | number     maximum download speed (in K/s)
105   "speed-limit-down-enabled"        | 'boolean'  true if the download speed is limited
106   "speed-limit-down-global-enabled" | 'boolean'  true if the download speed is limited by session
107   "speed-limit-up"                  | number     maximum upload speed (in K/s)
108   "speed-limit-up-enabled"          | 'boolean'  true if the upload speed is limited
109   "speed-limit-up-global-enabled"   | 'boolean'  true if the upload speed is limited by session
110
111   Just as an empty "ids" value is shorthand for "all ids", using an empty array
112   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
113   "priority-normal" is shorthand for saying "all files".
114
115   Response arguments: none
116
1173.3.  Torrent Accessors
118
119   Method name: "torrent-get".
120
121   Request arguments:
122
123   (1) An opional "ids" array as described in 3.1.
124   (2) A required "fields" array of keys. (see list below)
125
126   Response arguments:
127
128   (1) A "torrents" array of objects, each of which contains
129       the key/value pairs matching the request's "fields" argument.
130
131   key                             | type                        | source
132   --------------------------------+-----------------------------+---------
133   activityDate                    | number                      | tr_stat
134   addedDate                       | number                      | tr_stat
135   announceResponse                | string                      | tr_stat
136   announceURL                     | string                      | tr_stat
137   comment                         | string                      | tr_info
138   corruptEver                     | number                      | tr_stat
139   creator                         | string                      | tr_info
140   dateCreated                     | number                      | tr_info
141   desiredAvailable                | number                      | tr_stat
142   doneDate                        | number                      | tr_stat
143   downloadDir                     | string                      | tr_torrent
144   downloadedEver                  | number                      | tr_stat
145   downloaders                     | number                      | tr_stat
146   error                           | number                      | tr_stat
147   errorString                     | number                      | tr_stat
148   eta                             | number                      | tr_stat
149   files                           | array (see below)           | n/a
150   hashString                      | string                      | tr_info
151   haveUnchecked                   | number                      | tr_stat
152   haveValid                       | number                      | tr_stat
153   id                              | number                      | tr_torrent
154   isPrivate                       | 'boolean'                   | tr_torrent
155   lastAnnounceTime                | number                      | tr_stat
156   lastScrapeTime                  | number                      | tr_stat
157   leechers                        | number                      | tr_stat
158   leftUntilDone                   | number                      | tr_stat
159   manualAnnounceTime              | number                      | tr_stat
160   maxConnectedPeers               | number                      | tr_torrent
161   name                            | string                      | tr_info
162   nextAnnounceTime                | number                      | tr_stat
163   nextScrapeTime                  | number                      | tr_stat
164   peers                           | array (see below)           | n/a
165   peersConnected                  | number                      | tr_stat
166   peersFrom                       | object (see below)          | n/a
167   peersGettingFromUs              | number                      | tr_stat
168   peersKnown                      | number                      | tr_stat
169   peersSendingToUs                | number                      | tr_stat
170   pieces                          | string (see below)          | tr_torrent
171   pieceCount                      | tnumber                     | tr_info
172   pieceSize                       | tnumber                     | tr_info
173   priorities                      | array (see below)           | n/a
174   rateDownload (B/s)              | number                      | tr_stat
175   rateUpload (B/s)                | number                      | tr_stat
176   recheckProgress                 | 'double'                    | tr_stat
177   scrapeResponse                  | string                      | tr_stat
178   scrapeURL                       | string                      | tr_stat
179   seeders                         | number                      | tr_stat
180   sizeWhenDone                    | number                      | tr_stat
181   speed-limit-down                | number                      | tr_torrent
182   speed-limit-down-enabled        | 'boolean'                   | tr_torrent
183   speed-limit-down-global-enabled | 'boolean'                   | tr_torrent
184   speed-limit-up                  | number                      | tr_torrent
185   speed-limit-up-enabled          | 'boolean'                   | tr_torrent
186   speed-limit-up-global-enabled   | 'boolean'                   | tr_torrent
187   startDate                       | number                      | tr_stat
188   status                          | number                      | tr_stat
189   swarmSpeed (K/s)                | number                      | tr_stat
190   timesCompleted                  | number                      | tr_stat
191   trackers                        | array (see below)           | n/a
192   totalSize                       | number                      | tr_info
193   uploadedEver                    | number                      | tr_stat
194   uploadLimitMode                 | number                      | tr_torrent
195   uploadLimit                     | number                      | tr_torrent
196   uploadRatio                     | 'double'                    | tr_stat
197   wanted                          | array (see below)           | n/a
198   webseeds                        | array (see below)           | n/a
199   webseedsSendingToUs             | number                      | tr_stat
200                                   |                             |
201                                   |                             |
202   -----------------------+--------+-----------------------------+
203   files                  | array of objects, each containing:   |
204                          +-------------------------+------------+
205                          | key                     | type       |
206                          | bytesCompleted          | number     | tr_torrent
207                          | length                  | number     | tr_info
208                          | name                    | string     | tr_info
209   -----------------------+--------------------------------------+
210   peers                  | array of objects, each containing:   |
211                          +-------------------------+------------+
212                          | address                 | string     | tr_peer_stat
213                          | clientName              | string     | tr_peer_stat
214                          | clientIsChoked          | 'boolean'  | tr_peer_stat
215                          | clientIsInterested      | 'boolean'  | tr_peer_stat
216                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
217                          | isEncrypted             | 'boolean'  | tr_peer_stat
218                          | isIncoming              | 'boolean'  | tr_peer_stat
219                          | isUploadingTo           | 'boolean'  | tr_peer_stat
220                          | peerIsChoked            | 'boolean'  | tr_peer_stat
221                          | peerIsInterested        | 'boolean'  | tr_peer_stat
222                          | port                    | number     | tr_peer_stat
223                          | progress                | 'double'   | tr_peer_stat
224                          | rateToClient (B/s)      | number     | tr_peer_stat
225                          | rateToPeer (B/s)        | number     | tr_peer_stat
226   -----------------------+--------------------------------------+
227   peersFrom              | an object containing:                |
228                          +-------------------------+------------+
229                          | fromCache               | number     | tr_stat
230                          | fromIncoming            | number     | tr_stat
231                          | fromPex                 | number     | tr_stat
232                          | fromTracker             | number     | tr_stat
233   -----------------------+--------------------------------------+
234   pieces                 | A bitfield holding pieceCount flags  | tr_torrent
235                          | which are set to 'true' if we have   |
236                          | the piece matching that position.    |
237                          | JSON doesn't allow raw binary data,  |
238                          | so this is a base64-encoded string.  |
239   -----------------------+--------------------------------------+
240   priorities             | an array of tr_info.filecount        | tr_info
241                          | numbers. each is the tr_priority_t   |
242                          | mode for the corresponding file.     |
243   -----------------------+--------------------------------------+
244   trackers               | array of objects, each containing:   |
245                          +-------------------------+------------+
246                          | announce                | string     | tr_info
247                          | scrape                  | string     | tr_info
248                          | tier                    | number     | tr_info
249   -----------------------+--------------------------------------+
250   wanted                 | an array of tr_info.fileCount        | tr_info
251                          | 'booleans' true if the corresponding |
252                          | file is to be downloaded.            |
253   -----------------------+--------------------------------------+
254   webseeds               | an array of strings:                 |
255                          +-------------------------+------------+
256                          | webseed                 | string     | tr_info
257                          +-------------------------+------------+
258
259   Example:
260
261   Say we want to get the name and total size of torrents #7 and #10.
262
263   Request:
264
265      {
266         "arguments": {
267             "fields": [ "id", "name", "totalSize" ],
268             "ids": [ 7, 10 ]
269         },
270         "method": "torrent-get",
271         "tag": 39693
272      }
273
274
275   Response:
276
277      {
278         "arguments": {
279            "torrents": [
280               {
281                   "id": 10,
282                   "name": "Fedora x86_64 DVD",
283                   "totalSize", 34983493932,
284               },
285               {
286                   "id": 7,
287                   "name": "Ubuntu x86_64 DVD",
288                   "totalSize", 9923890123,
289               }
290            ]
291         },
292         "result": "success",
293         "tag": 39693
294      }
295
2963.4.  Adding a Torrent
297
298   Method name: "torrent-add"
299
300   Request arguments:
301
302   key                | value type & description
303   -------------------+-------------------------------------------------
304   "download-dir"     | string      path to download the torrent to
305   "filename"         | string      filename or URL of the .torrent file
306   "metainfo"         | string      base64-encoded .torrent content
307   "paused"           | 'boolean'   if true, don't start the torrent
308   "peer-limit"       | number      maximum number of peers
309
310   Either "filename" OR "metainfo" MUST be included.
311   All other arguments are optional.
312
313   Response arguments: on success, a "torrent-added" object in the
314                       form of one of 3.3's tr_info objects with the
315                       fields for id, name, and hashString.
316
3173.5.  Removing a Torrent
318
319   Method name: "torrent-remove"
320
321   Request arguments:
322
323   string                     | value type & description
324   ---------------------------+-------------------------------------------------
325   "ids"                      | array      torrent list, as described in 3.1
326   "delete-local-data"        | 'boolean'  delete local data. (default: false)
327
328   Response arguments: none
329
330
3314.   Session Requests
332
3334.1.  Session Arguments
334
335   string                     | value type & description
336   ---------------------------+-------------------------------------------------
337   "encryption"               | string     "required", "preferred", "tolerated"
338   "download-dir"             | string     default path to download torrents
339   "peer-limit"               | number     maximum global number of peers
340   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
341   "port"                     | number     port number
342   "port-forwarding-enabled"  | 'boolean'  true means enabled
343   "speed-limit-down"         | number     max global download speed (in K/s)
344   "speed-limit-down-enabled" | 'boolean'  true means enabled
345   "speed-limit-up"           | number     max global upload speed (in K/s)
346   "speed-limit-up-enabled"   | 'boolean'  true means enabled
347   "version"                  | string     long version string "$version ($revision)"
348   "rpc-version"              | number     the current RPC API version
349   "rpc-version-minimum"      | number     the minimum RPC API version supported
350
351   "rpc-version" indicates the RPC interface version supported by the RPC server.
352   It is incremented when a new version of Transmission changes the RPC interface.
353
354   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
355   It is changes when a new version of Transmission changes the RPC interface
356   in a way that is not backwards compatible.  There are no plans for this
357   to be common behavior.
358
3594.1.1.  Mutators
360
361   Method name: "session-set"
362   Request arguments: one or more of 4.1's arguments, except "version"
363   Response arguments: none
364
3654.1.2.  Accessors
366
367   Method name: "session-get"
368   Request arguments: none
369   Response arguments: all of 4.1's arguments
370
3714.2.  Session Statistics
372
373   Method name: "session-stats"
374
375   Request arguments: none
376
377   Response arguments:
378
379   string                     | value type
380   ---------------------------+-------------------------------------------------
381   "activeTorrentCount"       | number
382   "downloadSpeed"            | number
383   "pausedTorrentCount"       | number
384   "torrentCount"             | number
385   "uploadSpeed"              | number
386   ---------------------------+-------------------------------+
387   "cumulative-stats"         | object, containing:           |
388                              +------------------+------------+
389                              | uploadedBytes    | number     | tr_session_stats
390                              | downloadedBytes  | number     | tr_session_stats
391                              | filesAdded       | number     | tr_session_stats
392                              | sessionCount     | number     | tr_session_stats
393                              | secondsActive    | number     | tr_session_stats
394   ---------------------------+-------------------------------+
395   "current-stats"            | object, containing:           |
396                              +------------------+------------+
397                              | uploadedBytes    | number     | tr_session_stats
398                              | downloadedBytes  | number     | tr_session_stats
399                              | filesAdded       | number     | tr_session_stats
400                              | sessionCount     | number     | tr_session_stats
401                              | secondsActive    | number     | tr_session_stats
402   
403
4045.0.  Protocol Versions
405
406  The following changes have been made to the RPC interface:
407
408   RPC   | Release | Backwards |                |
409   Vers. | Version | Compat?   | Method         | Description
410   ------+---------+-----------+----------------+-------------------------------
411   1     | 1.30    | n/a       | n/a            | Initial version
412   ------+---------+-----------+----------------+-------------------------------
413   2     | 1.34    | yes       | torrent-get    | new arg "peers"
414   ------+---------+-----------+----------------+-------------------------------
415   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
416         |         | yes       | torrent-get    | new arg "downloaders"
417         |         | yes       | session-get    | new arg "version"
418         |         | yes       | torrent-remove | new method
419   ------+---------+-----------+----------------+-------------------------------
420   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
421         |         | yes       | session-get    | new arg "rpc-version-minimum"
422         |         | yes       | session-stats  | added "cumulative-stats"
423         |         | yes       | session-stats  | added "current-stats"
424         |         | yes       | torrent-get    | new arg "downloadDir"
425   ------+---------+-----------+----------------+-------------------------------
426   6     | 1.60    | yes       | torrent-get    | new arg "pieces"
427         |         | yes       | torrent-set    | new arg "speed-limit-down-global-enabled"
428         |         | yes       | torrent-set    | new arg "speed-limit-up-global-enabled"
429         |         | yes       | torrent-get    | new arg "speed-limit-down"
430         |         | yes       | torrent-get    | new arg "speed-limit-down-enabled"
431         |         | yes       | torrent-get    | new arg "speed-limit-down-global-enabled"
432         |         | yes       | torrent-get    | new arg "speed-limit-up"
433         |         | yes       | torrent-get    | new arg "speed-limit-up-enabled"
434         |         | yes       | torrent-get    | new arg "speed-limit-up-global-enabled"
435         |         |        NO | torrent-get    | removed arg "downloadLimit"
436         |         |        NO | torrent-get    | removed arg "downloadLimitMode"
437         |         |        NO | torrent-get    | removed arg "uploadLimit"
438         |         |        NO | torrent-get    | removed arg "uploadLimitMode"
439   ------+---------+-----------+----------------+-------------------------------
440
441
Note: See TracBrowser for help on using the repository browser.