source: branches/1.5x/doc/rpc-spec.txt

Last change on this file was 7868, checked in by charles, 9 years ago

(1.5x doc) tweak the RPC spec as suggested by chorlya

File size: 19.9 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-up"           | number     maximum upload speed (in K/s)
107   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
108
109   Just as an empty "ids" value is shorthand for "all ids", using an empty array
110   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
111   "priority-normal" is shorthand for saying "all files".
112
113   Response arguments: none
114
1153.3.  Torrent Accessors
116
117   Method name: "torrent-get".
118
119   Request arguments:
120
121   (1) An opional "ids" array as described in 3.1.
122   (2) A required "fields" array of keys. (see list below)
123
124   Response arguments:
125
126   (1) A "torrents" array of objects, each of which contains
127       the key/value pairs matching the request's "fields" argument.
128
129   key                    | type                                 | source
130   -----------------------+--------------------------------------+---------
131   activityDate           | number                               | tr_stat
132   addedDate              | number                               | tr_stat
133   announceResponse       | string                               | tr_stat
134   announceURL            | string                               | tr_stat
135   comment                | string                               | tr_info
136   corruptEver            | number                               | tr_stat
137   creator                | string                               | tr_info
138   dateCreated            | number                               | tr_info
139   desiredAvailable       | number                               | tr_stat
140   doneDate               | number                               | tr_stat
141   downloadDir            | string                               | tr_torrent
142   downloadedEver         | number                               | tr_stat
143   downloaders            | number                               | tr_stat
144   downloadLimitMode      | number                               | tr_torrent
145   downloadLimit          | number                               | tr_torrent
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   pieceCount             | tnumber                              | tr_info
171   pieceSize              | tnumber                              | tr_info
172   priorities             | array (see below)                    | n/a
173   rateDownload (B/s)     | number                               | tr_stat
174   rateUpload (B/s)       | number                               | tr_stat
175   recheckProgress        | 'double'                             | tr_stat
176   scrapeResponse         | string                               | tr_stat
177   scrapeURL              | string                               | tr_stat
178   seeders                | number                               | tr_stat
179   sizeWhenDone           | number                               | tr_stat
180   startDate              | number                               | tr_stat
181   status                 | number                               | tr_stat
182   swarmSpeed (K/s)       | number                               | tr_stat
183   timesCompleted         | number                               | tr_stat
184   trackers               | array (see below)                    | n/a
185   totalSize              | number                               | tr_info
186   uploadedEver           | number                               | tr_stat
187   uploadLimitMode        | number                               | tr_torrent
188   uploadLimit            | number                               | tr_torrent
189   uploadRatio            | 'double'                             | tr_stat
190   wanted                 | array (see below)                    | n/a
191   webseeds               | array (see below)                    | n/a
192   webseedsSendingToUs    | number                               | tr_stat
193                          |                                      |
194                          |                                      |
195   -----------------------+--------------------------------------+
196   files                  | array of objects, each containing:   |
197                          +-------------------------+------------+
198                          | key                     | type       |
199                          | bytesCompleted          | number     | tr_torrent
200                          | length                  | number     | tr_info
201                          | name                    | string     | tr_info
202   -----------------------+--------------------------------------+
203   peers                  | array of objects, each containing:   |
204                          +-------------------------+------------+
205                          | address                 | string     | tr_peer_stat
206                          | clientName              | string     | tr_peer_stat
207                          | clientIsChoked          | 'boolean'  | tr_peer_stat
208                          | clientIsInterested      | 'boolean'  | tr_peer_stat
209                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
210                          | isEncrypted             | 'boolean'  | tr_peer_stat
211                          | isIncoming              | 'boolean'  | tr_peer_stat
212                          | isUploadingTo           | 'boolean'  | tr_peer_stat
213                          | peerIsChoked            | 'boolean'  | tr_peer_stat
214                          | peerIsInterested        | 'boolean'  | tr_peer_stat
215                          | port                    | number     | tr_peer_stat
216                          | progress                | 'double'   | tr_peer_stat
217                          | rateToClient (B/s)      | number     | tr_peer_stat
218                          | rateToPeer (B/s)        | number     | tr_peer_stat
219   -----------------------+--------------------------------------+
220   peersFrom              | an object containing:                |
221                          +-------------------------+------------+
222                          | fromCache               | number     | tr_stat
223                          | fromIncoming            | number     | tr_stat
224                          | fromPex                 | number     | tr_stat
225                          | fromTracker             | number     | tr_stat
226   -----------------------+--------------------------------------+
227   priorities             | an array of tr_info.filecount        | tr_info
228                          | numbers. each is the tr_priority_t   |
229                          | mode for the corresponding file.     |
230   -----------------------+--------------------------------------+
231   trackers               | array of objects, each containing:   |
232                          +-------------------------+------------+
233                          | announce                | string     | tr_info
234                          | scrape                  | string     | tr_info
235                          | tier                    | number     | tr_info
236   -----------------------+--------------------------------------+
237   wanted                 | an array of tr_info.fileCount        | tr_info
238                          | 'booleans' true if the corresponding |
239                          | file is to be downloaded.            |
240   -----------------------+--------------------------------------+
241   webseeds               | an array of strings:                 |
242                          +-------------------------+------------+
243                          | webseed                 | string     | tr_info
244                          +-------------------------+------------+
245
246   Example:
247
248   Say we want to get the name and total size of torrents #7 and #10.
249
250   Request:
251
252      {
253         "arguments": {
254             "fields": [ "id", "name", "totalSize" ],
255             "ids": [ 7, 10 ]
256         },
257         "method": "torrent-get",
258         "tag": 39693
259      }
260
261
262   Response:
263
264      {
265         "arguments": {
266            "torrents": [
267               {
268                   "id": 10,
269                   "name": "Fedora x86_64 DVD",
270                   "totalSize", 34983493932,
271               },
272               {
273                   "id": 7,
274                   "name": "Ubuntu x86_64 DVD",
275                   "totalSize", 9923890123,
276               }
277            ]
278         },
279         "result": "success",
280         "tag": 39693
281      }
282
2833.4.  Adding a Torrent
284
285   Method name: "torrent-add"
286
287   Request arguments:
288
289   key                | value type & description
290   -------------------+-------------------------------------------------
291   "download-dir"     | string      path to download the torrent to
292   "filename"         | string      filename or URL of the .torrent file
293   "metainfo"         | string      base64-encoded .torrent content
294   "paused"           | 'boolean'   if true, don't start the torrent
295   "peer-limit"       | number      maximum number of peers
296
297   Either "filename" OR "metainfo" MUST be included.
298   All other arguments are optional.
299
300   Response arguments: on success, a "torrent-added" object in the
301                       form of one of 3.3's tr_info objects with the
302                       fields for id, name, and hashString.
303
3043.5.  Removing a Torrent
305
306   Method name: "torrent-remove"
307
308   Request arguments:
309
310   string                     | value type & description
311   ---------------------------+-------------------------------------------------
312   "ids"                      | array      torrent list, as described in 3.1
313   "delete-local-data"        | 'boolean'  delete local data. (default: false)
314
315   Response arguments: none
316
317
3184.   Session Requests
319
3204.1.  Session Arguments
321
322   string                     | value type & description
323   ---------------------------+-------------------------------------------------
324   "encryption"               | string     "required", "preferred", "tolerated"
325   "download-dir"             | string     default path to download torrents
326   "peer-limit"               | number     maximum global number of peers
327   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
328   "port"                     | number     port number
329   "port-forwarding-enabled"  | 'boolean'  true means enabled
330   "speed-limit-down"         | number     max global download speed (in K/s)
331   "speed-limit-down-enabled" | 'boolean'  true means enabled
332   "speed-limit-up"           | number     max global upload speed (in K/s)
333   "speed-limit-up-enabled"   | 'boolean'  true means enabled
334   "version"                  | string     long version string "$version ($revision)"
335   "rpc-version"              | number     the current RPC API version
336   "rpc-version-minimum"      | number     the minimum RPC API version supported
337
338   "rpc-version" indicates the RPC interface version supported by the RPC server.
339   It is incremented when a new version of Transmission changes the RPC interface.
340
341   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
342   It is changes when a new version of Transmission changes the RPC interface
343   in a way that is not backwards compatible.  There are no plans for this
344   to be common behavior.
345
3464.1.1.  Mutators
347
348   Method name: "session-set"
349   Request arguments: one or more of 4.1's arguments, except "version"
350   Response arguments: none
351
3524.1.2.  Accessors
353
354   Method name: "session-get"
355   Request arguments: none
356   Response arguments: all of 4.1's arguments
357
3584.2.  Session Statistics
359
360   Method name: "session-stats"
361
362   Request arguments: none
363
364   Response arguments:
365
366   string                     | value type
367   ---------------------------+-------------------------------------------------
368   "activeTorrentCount"       | number
369   "downloadSpeed"            | number
370   "pausedTorrentCount"       | number
371   "torrentCount"             | number
372   "uploadSpeed"              | number
373   ---------------------------+-------------------------------+
374   "cumulative-stats"         | object, containing:           |
375                              +------------------+------------+
376                              | uploadedBytes    | number     | tr_session_stats
377                              | downloadedBytes  | number     | tr_session_stats
378                              | filesAdded       | number     | tr_session_stats
379                              | sessionCount     | number     | tr_session_stats
380                              | secondsActive    | number     | tr_session_stats
381   ---------------------------+-------------------------------+
382   "current-stats"            | object, containing:           |
383                              +------------------+------------+
384                              | uploadedBytes    | number     | tr_session_stats
385                              | downloadedBytes  | number     | tr_session_stats
386                              | filesAdded       | number     | tr_session_stats
387                              | sessionCount     | number     | tr_session_stats
388                              | secondsActive    | number     | tr_session_stats
389   
390
3915.0.  Protocol Versions
392
393  The following changes have been made to the RPC interface:
394
395   RPC   | Release | Backwards |                |
396   Vers. | Version | Compat?   | Method         | Description
397   ------+---------+-----------+----------------+-------------------------------
398   1     | 1.30    | n/a       | n/a            | Initial version
399   ------+---------+-----------+----------------+-------------------------------
400   2     | 1.34    | yes       | torrent-get    | new arg "peers"
401   ------+---------+-----------+----------------+-------------------------------
402   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
403         |         |           | torrent-get    | new arg "downloaders"
404         |         |           | session-get    | new arg "version"
405         |         |           | torrent-remove | new method
406   ------+---------+-----------+----------------+-------------------------------
407   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
408         |         |           | session-get    | new arg "rpc-version-minimum"
409         |         |           | session-stats  | added "cumulative-stats"
410         |         |           | session-stats  | added "current-stats"
411         |         |           | torrent-get    | new arg "downloadDir"
412   ------+---------+-----------+----------------+-------------------------------
413
Note: See TracBrowser for help on using the repository browser.