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

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

(1.5x daemon) #1704: --info and/or --files should show the download directory

File size: 18.2 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; however, a simple notation also exists
52   for sending requests in the query portion of a URL.
53
54   The URL notation works as follows:
55   (1) Any key not "tag" or "method" is treated as an argument.
56   (2) The "arguments" key isn't needed, since data isn't nested.
57   (3) If the value in a key/value pair can be parsed as a number, then it is.
58       Otherwise if it can be parsed as an array of numbers, then it is.
59       Otherwise, it's parsed as a string.
60
61   Examples:
62   ?method=torrent-start&ids=1,2
63   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
64
653.  Torrent Requests
66
673.1.  Torrent Action Requests
68
69   Method name         | libtransmission function
70   --------------------+-------------------------------------------------
71   "torrent-start"     | tr_torrentStart
72   "torrent-stop"      | tr_torrentStop
73   "torrent-verify"    | tr_torrentVerify
74
75   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
76                      or both.  These are the torrents that the request will
77                      be applied to.  If "ids" is ommitted, the request is
78                      applied to all torrents.
79
80   Response arguments: none
81
823.2.  Torrent Mutators
83
84   Method name: "torrent-set"
85
86   Request arguments:
87
88   string                     | value type & description
89   ---------------------------+-------------------------------------------------
90   "files-wanted"             | array      indices of file(s) to download
91   "files-unwanted"           | array      indices of file(s) to not download
92   "ids"                      | array      torrent list, as described in 3.1
93   "peer-limit"               | number     maximum number of peers
94   "priority-high"            | array      indices of high-priority file(s)
95   "priority-low"             | array      indices of low-priority file(s)
96   "priority-normal"          | array      indices of normal-priority file(s)
97   "speed-limit-down"         | number     maximum download speed (in K/s)
98   "speed-limit-down-enabled" | 'boolean'  true if the download speed is limited
99   "speed-limit-up"           | number     maximum upload speed (in K/s)
100   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
101
102   Just as an empty "ids" value is shorthand for "all ids", using an empty array
103   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
104   "priority-normal" is shorthand for saying "all files".
105
106   Response arguments: none
107
1083.3.  Torrent Accessors
109
110   Method name: "torrent-get".
111
112   Request arguments:
113
114   (1) An opional "ids" array as described in 3.1.
115   (2) A required "fields" array of keys. (see list below)
116
117   Response arguments:
118
119   (1) A "torrents" array of objects, each of which contains
120       the key/value pairs matching the request's "fields" argument.
121
122   key                    | type                                 | source
123   -----------------------+--------------------------------------+---------
124   activityDate           | number                               | tr_stat
125   addedDate              | number                               | tr_stat
126   announceResponse       | string                               | tr_stat
127   announceURL            | string                               | tr_stat
128   comment                | string                               | tr_info
129   corruptEver            | number                               | tr_stat
130   creator                | string                               | tr_info
131   dateCreated            | number                               | tr_info
132   desiredAvailable       | number                               | tr_stat
133   doneDate               | number                               | tr_stat
134   downloadDir            | string                               | tr_torrent
135   downloadedEver         | number                               | tr_stat
136   downloaders            | number                               | tr_stat
137   downloadLimitMode      | number                               | tr_torrent
138   downloadLimit          | number                               | tr_torrent
139   error                  | number                               | tr_stat
140   errorString            | number                               | tr_stat
141   eta                    | number                               | tr_stat
142   files                  | array (see below)                    | n/a
143   hashString             | string                               | tr_info
144   haveUnchecked          | number                               | tr_stat
145   haveValid              | number                               | tr_stat
146   id                     | number                               | tr_torrent
147   isPrivate              | 'boolean                             | tr_torrent
148   lastAnnounceTime       | number                               | tr_stat
149   lastScrapeTime         | number                               | tr_stat
150   leechers               | number                               | tr_stat
151   leftUntilDone          | number                               | tr_stat
152   manualAnnounceTime     | number                               | tr_stat
153   maxConnectedPeers      | number                               | tr_torrent
154   name                   | string                               | tr_info
155   nextAnnounceTime       | number                               | tr_stat
156   nextScrapeTime         | number                               | tr_stat
157   peers                  | array (see below)                    | n/a
158   peersConnected         | number                               | tr_stat
159   peersFrom              | object (see below)                   | n/a
160   peersGettingFromUs     | number                               | tr_stat
161   peersKnown             | number                               | tr_stat
162   peersSendingToUs       | number                               | tr_stat
163   pieceCount             | tnumber                              | tr_info
164   pieceSize              | tnumber                              | tr_info
165   priorities             | array (see below)                    | n/a
166   rateDownload (B/s)     | number                               | tr_stat
167   rateUpload (B/s)       | number                               | tr_stat
168   recheckProgress        | 'double'                             | tr_stat
169   scrapeResponse         | string                               | tr_stat
170   scrapeURL              | string                               | tr_stat
171   seeders                | number                               | tr_stat
172   sizeWhenDone           | number                               | tr_stat
173   startDate              | number                               | tr_stat
174   status                 | number                               | tr_stat
175   swarmSpeed (K/s)       | number                               | tr_stat
176   timesCompleted         | number                               | tr_stat
177   trackers               | array (see below)                    | n/a
178   totalSize              | number                               | tr_info
179   uploadedEver           | number                               | tr_stat
180   uploadLimitMode        | number                               | tr_torrent
181   uploadLimit            | number                               | tr_torrent
182   uploadRatio            | 'double'                             | tr_stat
183   wanted                 | array (see below)                    | n/a
184   webseeds               | array (see below)                    | n/a
185   webseedsSendingToUs    | number                               | tr_stat
186                          |                                      |
187                          |                                      |
188   -----------------------+--------------------------------------+
189   files                  | array of objects, each containing:   |
190                          +-------------------------+------------+
191                          | key                     | type       |
192                          | bytesCompleted          | number     | tr_torrent
193                          | length                  | number     | tr_info
194                          | name                    | string     | tr_info
195   -----------------------+--------------------------------------+
196   peers                  | array of objects, each containing:   |
197                          +-------------------------+------------+
198                          | address                 | string     | tr_peer_stat
199                          | clientName              | string     | tr_peer_stat
200                          | clientIsChoked          | 'boolean'  | tr_peer_stat
201                          | clientIsInterested      | 'boolean'  | tr_peer_stat
202                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
203                          | isEncrypted             | 'boolean'  | tr_peer_stat
204                          | isIncoming              | 'boolean'  | tr_peer_stat
205                          | isUploadingTo           | 'boolean'  | tr_peer_stat
206                          | peerIsChoked            | 'boolean'  | tr_peer_stat
207                          | peerIsInterested        | 'boolean'  | tr_peer_stat
208                          | port                    | number     | tr_peer_stat
209                          | progress                | 'double'   | tr_peer_stat
210                          | rateToClient (B/s)      | number     | tr_peer_stat
211                          | rateToPeer (B/s)        | number     | tr_peer_stat
212   -----------------------+--------------------------------------+
213   peersFrom              | an object containing:                |
214                          +-------------------------+------------+
215                          | fromCache               | number     | tr_stat
216                          | fromIncoming            | number     | tr_stat
217                          | fromPex                 | number     | tr_stat
218                          | fromTracker             | number     | tr_stat
219   -----------------------+--------------------------------------+
220   priorities             | an array of tr_info.filecount        | tr_info
221                          | numbers. each is the tr_priority_t   |
222                          | mode for the corresponding file.     |
223   -----------------------+--------------------------------------+
224   trackers               | array of objects, each containing:   |
225                          +-------------------------+------------+
226                          | announce                | string     | tr_info
227                          | scrape                  | string     | tr_info
228                          | tier                    | number     | tr_info
229   -----------------------+--------------------------------------+
230   wanted                 | an array of tr_info.fileCount        | tr_info
231                          | 'booleans' true if the corresponding |
232                          | file is to be downloaded.            |
233   -----------------------+--------------------------------------+
234   webseeds               | an array of strings:                 |
235                          +-------------------------+------------+
236                          | webseed                 | string     | tr_info
237                          +-------------------------+------------+
238
239   Example:
240
241   Say we want to get the name and total size of torrents #7 and #10.
242
243   Request:
244
245      {
246         "arguments": {
247             "fields": [ "id", "name", "totalSize" ]
248         },
249         "method": "torrent-get",
250         "tag": 39693
251      }
252
253
254   Response:
255
256      {
257         "arguments": {
258            "torrents": [
259               {
260                   "id": 10,
261                   "name": "Fedora x86_64 DVD",
262                   "totalSize", 34983493932,
263               },
264               {
265                   "id": 7,
266                   "name": "Ubuntu x86_64 DVD",
267                   "totalSize", 9923890123,
268               }
269            ]
270         },
271         "result": "success",
272         "tag": 39693
273      }
274
2753.4.  Adding a Torrent
276
277   Method name: "torrent-add"
278
279   Request arguments:
280
281   key                | value type & description
282   -------------------+-------------------------------------------------
283   "download-dir"     | string      path to download the torrent to
284   "filename"         | string      location of the .torrent file
285   "metainfo"         | string      base64-encoded .torrent content
286   "paused"           | 'boolean'   if true, don't start the torrent
287   "peer-limit"       | number      maximum number of peers
288
289   Either "filename" OR "metainfo" MUST be included.
290   All other arguments are optional.
291
292   Response arguments: on success, a "torrent-added" object in the
293                       form of one of 3.3's tr_info objects with the
294                       fields for id, name, and hashString.
295
2963.5.  Removing a Torrent
297
298   Method name: "torrent-remove"
299
300   Request arguments:
301
302   string                     | value type & description
303   ---------------------------+-------------------------------------------------
304   "ids"                      | array      torrent list, as described in 3.1
305   "delete-local-data"        | 'boolean'  delete local data. (default: false)
306
307   Response arguments: none
308
309
3104.   Session Requests
311
3124.1.  Session Arguments
313
314   string                     | value type & description
315   ---------------------------+-------------------------------------------------
316   "encryption"               | string     "required", "preferred", "tolerated"
317   "download-dir"             | string     default path to download torrents
318   "peer-limit"               | number     maximum global number of peers
319   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
320   "port"                     | number     port number
321   "port-forwarding-enabled"  | 'boolean'  true means enabled
322   "speed-limit-down"         | number     max global download speed (in K/s)
323   "speed-limit-down-enabled" | 'boolean'  true means enabled
324   "speed-limit-up"           | number     max global upload speed (in K/s)
325   "speed-limit-up-enabled"   | 'boolean'  true means enabled
326   "version"                  | string     long version string "$version ($revision)"
327   "rpc-version"              | number     the current RPC API version
328   "rpc-version-minimum"      | number     the minimum RPC API version supported
329
330   "rpc-version" indicates the RPC interface version supported by the RPC server.
331   It is incremented when a new version of Transmission changes the RPC interface.
332
333   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
334   It is changes when a new version of Transmission changes the RPC interface
335   in a way that is not backwards compatible.  There are no plans for this
336   to be common behavior.
337
3384.1.1.  Mutators
339
340   Method name: "session-set"
341   Request arguments: one or more of 4.1's arguments, except "version"
342   Response arguments: none
343
3444.1.2.  Accessors
345
346   Method name: "session-get"
347   Request arguments: none
348   Response arguments: all of 4.1's arguments
349
3504.2.  Session Statistics
351
352   Method name: "session-stats"
353
354   Request arguments: none
355
356   Response arguments:
357
358   string                     | value type
359   ---------------------------+-------------------------------------------------
360   "activeTorrentCount"       | number
361   "downloadSpeed"            | number
362   "pausedTorrentCount"       | number
363   "torrentCount"             | number
364   "uploadSpeed"              | number
365   
366
3675.0.  Protocol Versions
368
369  The following changes have been made to the RPC interface:
370
371   RPC   | Release | Backwards |                |
372   Vers. | Version | Compat?   | Method         | Description
373   ------+---------+-----------+----------------+-------------------------------
374   1     | 1.30    | n/a       | n/a            | Initial version
375   ------+---------+-----------+----------------+-------------------------------
376   2     | 1.34    | yes       | torrent-get    | new arg "peers"
377   ------+---------+-----------+----------------+-------------------------------
378   3     | 1.41    | yes       | torrent-get    | added "port" to "peers"
379         |         |           | torrent-get    | new arg "downloaders"
380         |         |           | session-get    | new arg "version"
381         |         |           | torrent-remove | new method
382   ------+---------+-----------+----------------+-------------------------------
383   4     | 1.50    | yes       | session-get    | new arg "rpc-version"
384         |         |           | session-get    | new arg "rpc-version-minimum"
385         |         |           | torrent-get    | new arg "downloadDir"
386   ------+---------+-----------+----------------+-------------------------------
387
Note: See TracBrowser for help on using the repository browser.