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

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

(daemon) #1510: kysucix's patch to give an option to delete local data via RPC when removing a torrent.

File size: 16.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   downloadedEver         | number                               | tr_stat
135   downloaders            | 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
2953.5.  Removing a Torrent
296
297   Method name: "torrent-remove"
298
299   Request arguments:
300
301   string                     | value type & description
302   ---------------------------+-------------------------------------------------
303   "ids"                      | array      torrent list, as described in 3.1
304   "delete-local-data"        | 'boolean'  delete local data. (default: false)
305
306   Response arguments: none
307
308
3094.   Session Requests
310
3114.1.  Session Arguments
312
313   string                     | value type & description
314   ---------------------------+-------------------------------------------------
315   "encryption"               | string     "required", "preferred", "tolerated"
316   "download-dir"             | string     default path to download torrents
317   "peer-limit"               | number     maximum global number of peers
318   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
319   "port"                     | number     port number
320   "port-forwarding-enabled"  | 'boolean'  true means enabled
321   "speed-limit-down"         | number     max global download speed (in K/s)
322   "speed-limit-down-enabled" | 'boolean'  true means enabled
323   "speed-limit-up"           | number     max global upload speed (in K/s)
324   "speed-limit-up-enabled"   | 'boolean'  true means enabled
325
3264.1.1.  Mutators
327
328   Method name: "session-set"
329   Request arguments: one or more of 4.1's arguments
330   Response arguments: none
331
3324.1.2.  Accessors
333
334   Method name: "session-get"
335   Request arguments: none
336   Response arguments: all of 4.1's arguments
337
3384.2.  Session Statistics
339
340   Method name: "session-stats"
341
342   Request arguments: none
343
344   Response arguments:
345
346   string                     | value type
347   ---------------------------+-------------------------------------------------
348   "activeTorrentCount"       | number
349   "downloadSpeed"            | number
350   "pausedTorrentCount"       | number
351   "torrentCount"             | number
352   "uploadSpeed"              | number
353   
354
Note: See TracBrowser for help on using the repository browser.