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

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

(1.4x rpc) #1584: include version in session-get response

File size: 15.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; 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-remove"    | tr_torrentRemove
72   "torrent-start"     | tr_torrentStart
73   "torrent-stop"      | tr_torrentStop
74   "torrent-verify"    | tr_torrentVerify
75
76   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
77                      or both.  These are the torrents that the request will
78                      be applied to.  If "ids" is ommitted, the request is
79                      applied to all torrents.
80
81   Response arguments: none
82
833.2.  Torrent Mutators
84
85   Method name: "torrent-set"
86
87   Request arguments:
88
89   string                     | value type & description
90   ---------------------------+-------------------------------------------------
91   "files-wanted"             | array      indices of file(s) to download
92   "files-unwanted"           | array      indices of file(s) to not download
93   "ids"                      | array      torrent list, as described in 3.1
94   "peer-limit"               | number     maximum number of peers
95   "priority-high"            | array      indices of high-priority file(s)
96   "priority-low"             | array      indices of low-priority file(s)
97   "priority-normal"          | array      indices of normal-priority file(s)
98   "speed-limit-down"         | number     maximum download speed (in K/s)
99   "speed-limit-down-enabled" | 'boolean'  true if the download speed is limited
100   "speed-limit-up"           | number     maximum upload speed (in K/s)
101   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
102
103   Just as an empty "ids" value is shorthand for "all ids", using an empty array
104   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
105   "priority-normal" is shorthand for saying "all files".
106
107   Response arguments: none
108
1093.3.  Torrent Accessors
110
111   Method name: "torrent-get".
112
113   Request arguments:
114
115   (1) An opional "ids" array as described in 3.1.
116   (2) A required "fields" array of keys. (see list below)
117
118   Response arguments:
119
120   (1) A "torrents" array of objects, each of which contains
121       the key/value pairs matching the request's "fields" argument.
122
123   key                    | type                                 | source
124   -----------------------+--------------------------------------+---------
125   activityDate           | number                               | tr_stat
126   addedDate              | number                               | tr_stat
127   announceResponse       | string                               | tr_stat
128   announceURL            | string                               | tr_stat
129   comment                | string                               | tr_info
130   corruptEver            | number                               | tr_stat
131   creator                | string                               | tr_info
132   dateCreated            | number                               | tr_info
133   desiredAvailable       | number                               | tr_stat
134   doneDate               | number                               | tr_stat
135   downloadedEver         | number                               | tr_stat
136   downloadLimitMode      | number                               | tr_torrent
137   downloadLimit          | number                               | tr_torrent
138   error                  | number                               | tr_stat
139   errorString            | number                               | tr_stat
140   eta                    | number                               | tr_stat
141   files                  | array (see below)                    | n/a
142   hashString             | string                               | tr_info
143   haveUnchecked          | number                               | tr_stat
144   haveValid              | number                               | tr_stat
145   id                     | number                               | tr_torrent
146   isPrivate              | 'boolean                             | tr_torrent
147   lastAnnounceTime       | number                               | tr_stat
148   lastScrapeTime         | number                               | tr_stat
149   leechers               | number                               | tr_stat
150   leftUntilDone          | number                               | tr_stat
151   manualAnnounceTime     | number                               | tr_stat
152   maxConnectedPeers      | number                               | tr_torrent
153   name                   | string                               | tr_info
154   nextAnnounceTime       | number                               | tr_stat
155   nextScrapeTime         | number                               | tr_stat
156   peers                  | array (see below)                    | n/a
157   peersConnected         | number                               | tr_stat
158   peersFrom              | object (see below)                   | n/a
159   peersGettingFromUs     | number                               | tr_stat
160   peersKnown             | number                               | tr_stat
161   peersSendingToUs       | number                               | tr_stat
162   pieceCount             | tnumber                              | tr_info
163   pieceSize              | tnumber                              | tr_info
164   priorities             | array (see below)                    | n/a
165   rateDownload (B/s)     | number                               | tr_stat
166   rateUpload (B/s)       | number                               | tr_stat
167   recheckProgress        | 'double'                             | tr_stat
168   scrapeResponse         | string                               | tr_stat
169   scrapeURL              | string                               | tr_stat
170   seeders                | number                               | tr_stat
171   sizeWhenDone           | number                               | tr_stat
172   startDate              | number                               | tr_stat
173   status                 | number                               | tr_stat
174   swarmSpeed (K/s)       | number                               | tr_stat
175   timesCompleted         | number                               | tr_stat
176   trackers               | array (see below)                    | n/a
177   totalSize              | number                               | tr_info
178   uploadedEver           | number                               | tr_stat
179   uploadLimitMode        | number                               | tr_torrent
180   uploadLimit            | number                               | tr_torrent
181   uploadRatio            | 'double'                             | tr_stat
182   wanted                 | array (see below)                    | n/a
183   webseeds               | array (see below)                    | n/a
184   webseedsSendingToUs    | number                               | tr_stat
185                          |                                      |
186                          |                                      |
187   -----------------------+--------------------------------------+
188   files                  | array of objects, each containing:   |
189                          +-------------------------+------------+
190                          | key                     | type       |
191                          | bytesCompleted          | number     | tr_torrent
192                          | length                  | number     | tr_info
193                          | name                    | string     | tr_info
194   -----------------------+--------------------------------------+
195   peers                  | array of objects, each containing:   |
196                          +-------------------------+------------+
197                          | address                 | string     | tr_peer_stat
198                          | clientName              | string     | tr_peer_stat
199                          | clientIsChoked          | 'boolean'  | tr_peer_stat
200                          | clientIsInterested      | 'boolean'  | tr_peer_stat
201                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
202                          | isEncrypted             | 'boolean'  | tr_peer_stat
203                          | isIncoming              | 'boolean'  | tr_peer_stat
204                          | isUploadingTo           | 'boolean'  | tr_peer_stat
205                          | peerIsChoked            | 'boolean'  | tr_peer_stat
206                          | peerIsInterested        | 'boolean'  | tr_peer_stat
207                          | port                    | number     | tr_peer_stat
208                          | progress                | 'double'   | tr_peer_stat
209                          | rateToClient (B/s)      | number     | tr_peer_stat
210                          | rateToPeer (B/s)        | number     | tr_peer_stat
211   -----------------------+--------------------------------------+
212   peersFrom              | an object containing:                |
213                          +-------------------------+------------+
214                          | fromCache               | number     | tr_stat
215                          | fromIncoming            | number     | tr_stat
216                          | fromPex                 | number     | tr_stat
217                          | fromTracker             | number     | tr_stat
218   -----------------------+--------------------------------------+
219   priorities             | an array of tr_info.filecount        | tr_info
220                          | numbers. each is the tr_priority_t   |
221                          | mode for the corresponding file.     |
222   -----------------------+--------------------------------------+
223   trackers               | array of objects, each containing:   |
224                          +-------------------------+------------+
225                          | announce                | string     | tr_info
226                          | scrape                  | string     | tr_info
227                          | tier                    | number     | tr_info
228   -----------------------+--------------------------------------+
229   wanted                 | an array of tr_info.fileCount        | tr_info
230                          | 'booleans' true if the corresponding |
231                          | file is to be downloaded.            |
232   -----------------------+--------------------------------------+
233   webseeds               | an array of strings:                 |
234                          +-------------------------+------------+
235                          | webseed                 | string     | tr_info
236                          +-------------------------+------------+
237
238   Example:
239
240   Say we want to get the name and total size of torrents #7 and #10.
241
242   Request:
243
244      {
245         "arguments": {
246             "fields": [ "id", "name", "totalSize" ]
247         },
248         "method": "torrent-get",
249         "tag": 39693
250      }
251
252
253   Response:
254
255      {
256         "arguments": {
257            "torrents": [
258               {
259                   "id": 10,
260                   "name": "Fedora x86_64 DVD",
261                   "totalSize", 34983493932,
262               },
263               {
264                   "id": 7,
265                   "name": "Ubuntu x86_64 DVD",
266                   "totalSize", 9923890123,
267               }
268            ]
269         },
270         "result": "success",
271         "tag": 39693
272      }
273
2743.4.  Adding a Torrent
275
276   Method name: "torrent-add"
277
278   Request arguments:
279
280   key                | value type & description
281   -------------------+-------------------------------------------------
282   "download-dir"     | string      path to download the torrent to
283   "filename"         | string      location of the .torrent file
284   "metainfo"         | string      base64-encoded .torrent content
285   "paused"           | 'boolean'   if true, don't start the torrent
286   "peer-limit"       | number      maximum number of peers
287
288   Either "filename" OR "metainfo" MUST be included.
289   All other arguments are optional.
290
291   Response arguments: on success, a "torrent-added" object in the
292                       form of one of 3.3's tr_info objects with the
293                       fields for id, name, and hashString.
294
295
2964.   Session Requests
297
2984.1.  Session Arguments
299
300   string                     | value type & description
301   ---------------------------+-------------------------------------------------
302   "encryption"               | string     "required", "preferred", "tolerated"
303   "download-dir"             | string     default path to download torrents
304   "peer-limit"               | number     maximum global number of peers
305   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
306   "port"                     | number     port number
307   "port-forwarding-enabled"  | 'boolean'  true means enabled
308   "speed-limit-down"         | number     max global download speed (in K/s)
309   "speed-limit-down-enabled" | 'boolean'  true means enabled
310   "speed-limit-up"           | number     max global upload speed (in K/s)
311   "speed-limit-up-enabled"   | 'boolean'  true means enabled
312   "version"                  | string     long version string "$version ($revision)"
313
314
3154.1.1.  Mutators
316
317   Method name: "session-set"
318   Request arguments: one or more of 4.1's arguments, except "version"
319   Response arguments: none
320
3214.1.2.  Accessors
322
323   Method name: "session-get"
324   Request arguments: none
325   Response arguments: all of 4.1's arguments
326
3274.2.  Session Statistics
328
329   Method name: "session-stats"
330
331   Request arguments: none
332
333   Response arguments:
334
335   string                     | value type
336   ---------------------------+-------------------------------------------------
337   "activeTorrentCount"       | number
338   "downloadSpeed"            | number
339   "pausedTorrentCount"       | number
340   "torrentCount"             | number
341   "uploadSpeed"              | number
342   
343
Note: See TracBrowser for help on using the repository browser.