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

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

(trunk) #1608: Completed pieces bitfield in rpc

File size: 20.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
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   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   startDate              | number                               | tr_stat
182   status                 | number                               | tr_stat
183   swarmSpeed (K/s)       | number                               | tr_stat
184   timesCompleted         | number                               | tr_stat
185   trackers               | array (see below)                    | n/a
186   totalSize              | number                               | tr_info
187   uploadedEver           | number                               | tr_stat
188   uploadLimitMode        | number                               | tr_torrent
189   uploadLimit            | number                               | tr_torrent
190   uploadRatio            | 'double'                             | tr_stat
191   wanted                 | array (see below)                    | n/a
192   webseeds               | array (see below)                    | n/a
193   webseedsSendingToUs    | number                               | tr_stat
194                          |                                      |
195                          |                                      |
196   -----------------------+--------------------------------------+
197   files                  | array of objects, each containing:   |
198                          +-------------------------+------------+
199                          | key                     | type       |
200                          | bytesCompleted          | number     | tr_torrent
201                          | length                  | number     | tr_info
202                          | name                    | string     | tr_info
203   -----------------------+--------------------------------------+
204   peers                  | array of objects, each containing:   |
205                          +-------------------------+------------+
206                          | address                 | string     | tr_peer_stat
207                          | clientName              | string     | tr_peer_stat
208                          | clientIsChoked          | 'boolean'  | tr_peer_stat
209                          | clientIsInterested      | 'boolean'  | tr_peer_stat
210                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
211                          | isEncrypted             | 'boolean'  | tr_peer_stat
212                          | isIncoming              | 'boolean'  | tr_peer_stat
213                          | isUploadingTo           | 'boolean'  | tr_peer_stat
214                          | peerIsChoked            | 'boolean'  | tr_peer_stat
215                          | peerIsInterested        | 'boolean'  | tr_peer_stat
216                          | port                    | number     | tr_peer_stat
217                          | progress                | 'double'   | tr_peer_stat
218                          | rateToClient (B/s)      | number     | tr_peer_stat
219                          | rateToPeer (B/s)        | number     | tr_peer_stat
220   -----------------------+--------------------------------------+
221   peersFrom              | an object containing:                |
222                          +-------------------------+------------+
223                          | fromCache               | number     | tr_stat
224                          | fromIncoming            | number     | tr_stat
225                          | fromPex                 | number     | tr_stat
226                          | fromTracker             | number     | tr_stat
227   -----------------------+--------------------------------------+
228   pieces                 | A bitfield holding pieceCount flags  | tr_torrent
229                          | which are set to 'true' if we have   |
230                          | the piece matching that position.    |
231                          | JSON doesn't allow raw binary data,  |
232                          | so this is a base64-encoded string.  |
233   -----------------------+--------------------------------------+
234   priorities             | an array of tr_info.filecount        | tr_info
235                          | numbers. each is the tr_priority_t   |
236                          | mode for the corresponding file.     |
237   -----------------------+--------------------------------------+
238   trackers               | array of objects, each containing:   |
239                          +-------------------------+------------+
240                          | announce                | string     | tr_info
241                          | scrape                  | string     | tr_info
242                          | tier                    | number     | tr_info
243   -----------------------+--------------------------------------+
244   wanted                 | an array of tr_info.fileCount        | tr_info
245                          | 'booleans' true if the corresponding |
246                          | file is to be downloaded.            |
247   -----------------------+--------------------------------------+
248   webseeds               | an array of strings:                 |
249                          +-------------------------+------------+
250                          | webseed                 | string     | tr_info
251                          +-------------------------+------------+
252
253   Example:
254
255   Say we want to get the name and total size of torrents #7 and #10.
256
257   Request:
258
259      {
260         "arguments": {
261             "fields": [ "id", "name", "totalSize" ],
262             "ids": [ 7, 10 ]
263         },
264         "method": "torrent-get",
265         "tag": 39693
266      }
267
268
269   Response:
270
271      {
272         "arguments": {
273            "torrents": [
274               {
275                   "id": 10,
276                   "name": "Fedora x86_64 DVD",
277                   "totalSize", 34983493932,
278               },
279               {
280                   "id": 7,
281                   "name": "Ubuntu x86_64 DVD",
282                   "totalSize", 9923890123,
283               }
284            ]
285         },
286         "result": "success",
287         "tag": 39693
288      }
289
2903.4.  Adding a Torrent
291
292   Method name: "torrent-add"
293
294   Request arguments:
295
296   key                | value type & description
297   -------------------+-------------------------------------------------
298   "download-dir"     | string      path to download the torrent to
299   "filename"         | string      filename or URL of the .torrent file
300   "metainfo"         | string      base64-encoded .torrent content
301   "paused"           | 'boolean'   if true, don't start the torrent
302   "peer-limit"       | number      maximum number of peers
303
304   Either "filename" OR "metainfo" MUST be included.
305   All other arguments are optional.
306
307   Response arguments: on success, a "torrent-added" object in the
308                       form of one of 3.3's tr_info objects with the
309                       fields for id, name, and hashString.
310
3113.5.  Removing a Torrent
312
313   Method name: "torrent-remove"
314
315   Request arguments:
316
317   string                     | value type & description
318   ---------------------------+-------------------------------------------------
319   "ids"                      | array      torrent list, as described in 3.1
320   "delete-local-data"        | 'boolean'  delete local data. (default: false)
321
322   Response arguments: none
323
324
3254.   Session Requests
326
3274.1.  Session Arguments
328
329   string                     | value type & description
330   ---------------------------+-------------------------------------------------
331   "encryption"               | string     "required", "preferred", "tolerated"
332   "download-dir"             | string     default path to download torrents
333   "peer-limit"               | number     maximum global number of peers
334   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
335   "port"                     | number     port number
336   "port-forwarding-enabled"  | 'boolean'  true means enabled
337   "speed-limit-down"         | number     max global download speed (in K/s)
338   "speed-limit-down-enabled" | 'boolean'  true means enabled
339   "speed-limit-up"           | number     max global upload speed (in K/s)
340   "speed-limit-up-enabled"   | 'boolean'  true means enabled
341   "version"                  | string     long version string "$version ($revision)"
342   "rpc-version"              | number     the current RPC API version
343   "rpc-version-minimum"      | number     the minimum RPC API version supported
344
345   "rpc-version" indicates the RPC interface version supported by the RPC server.
346   It is incremented when a new version of Transmission changes the RPC interface.
347
348   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
349   It is changes when a new version of Transmission changes the RPC interface
350   in a way that is not backwards compatible.  There are no plans for this
351   to be common behavior.
352
3534.1.1.  Mutators
354
355   Method name: "session-set"
356   Request arguments: one or more of 4.1's arguments, except "version"
357   Response arguments: none
358
3594.1.2.  Accessors
360
361   Method name: "session-get"
362   Request arguments: none
363   Response arguments: all of 4.1's arguments
364
3654.2.  Session Statistics
366
367   Method name: "session-stats"
368
369   Request arguments: none
370
371   Response arguments:
372
373   string                     | value type
374   ---------------------------+-------------------------------------------------
375   "activeTorrentCount"       | number
376   "downloadSpeed"            | number
377   "pausedTorrentCount"       | number
378   "torrentCount"             | number
379   "uploadSpeed"              | number
380   ---------------------------+-------------------------------+
381   "cumulative-stats"         | object, containing:           |
382                              +------------------+------------+
383                              | uploadedBytes    | number     | tr_session_stats
384                              | downloadedBytes  | number     | tr_session_stats
385                              | filesAdded       | number     | tr_session_stats
386                              | sessionCount     | number     | tr_session_stats
387                              | secondsActive    | number     | tr_session_stats
388   ---------------------------+-------------------------------+
389   "current-stats"            | object, containing:           |
390                              +------------------+------------+
391                              | uploadedBytes    | number     | tr_session_stats
392                              | downloadedBytes  | number     | tr_session_stats
393                              | filesAdded       | number     | tr_session_stats
394                              | sessionCount     | number     | tr_session_stats
395                              | secondsActive    | number     | tr_session_stats
396   
397
3985.0.  Protocol Versions
399
400  The following changes have been made to the RPC interface:
401
402   RPC   | Release | Backwards |                |
403   Vers. | Version | Compat?   | Method         | Description
404   ------+---------+-----------+----------------+-------------------------------
405   1     | 1.30    | n/a       | n/a            | Initial version
406   ------+---------+-----------+----------------+-------------------------------
407   2     | 1.34    | yes       | torrent-get    | new arg "peers"
408   ------+---------+-----------+----------------+-------------------------------
409   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
410         |         |           | torrent-get    | new arg "downloaders"
411         |         |           | session-get    | new arg "version"
412         |         |           | torrent-remove | new method
413   ------+---------+-----------+----------------+-------------------------------
414   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
415         |         |           | session-get    | new arg "rpc-version-minimum"
416         |         |           | session-stats  | added "cumulative-stats"
417         |         |           | session-stats  | added "current-stats"
418         |         |           | torrent-get    | new arg "downloadDir"
419   ------+---------+-----------+----------------+-------------------------------
420   6     | 1.60    | yes       | torrent-get    | new arg "pieces"
421   ------+---------+-----------+----------------+-------------------------------
422
423
Note: See TracBrowser for help on using the repository browser.