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

Last change on this file since 7264 was 7264, checked in by charles, 12 years ago

add "downloaders" to the spec; it's already in trunk

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   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
296
2974.   Session Requests
298
2994.1.  Session Arguments
300
301   string                     | value type & description
302   ---------------------------+-------------------------------------------------
303   "encryption"               | string     "required", "preferred", "tolerated"
304   "download-dir"             | string     default path to download torrents
305   "peer-limit"               | number     maximum global number of peers
306   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
307   "port"                     | number     port number
308   "port-forwarding-enabled"  | 'boolean'  true means enabled
309   "speed-limit-down"         | number     max global download speed (in K/s)
310   "speed-limit-down-enabled" | 'boolean'  true means enabled
311   "speed-limit-up"           | number     max global upload speed (in K/s)
312   "speed-limit-up-enabled"   | 'boolean'  true means enabled
313
3144.1.1.  Mutators
315
316   Method name: "session-set"
317   Request arguments: one or more of 4.1's arguments
318   Response arguments: none
319
3204.1.2.  Accessors
321
322   Method name: "session-get"
323   Request arguments: none
324   Response arguments: all of 4.1's arguments
325
3264.2.  Session Statistics
327
328   Method name: "session-stats"
329
330   Request arguments: none
331
332   Response arguments:
333
334   string                     | value type
335   ---------------------------+-------------------------------------------------
336   "activeTorrentCount"       | number
337   "downloadSpeed"            | number
338   "pausedTorrentCount"       | number
339   "torrentCount"             | number
340   "uploadSpeed"              | number
341   
342
Note: See TracBrowser for help on using the repository browser.