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

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

(doc 1.3x) backport rpc spec clarifications from r6647

File size: 14.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. "array" is equivalent
9   to a benc list; "object" is equivalent to a benc dictionary;
10   and an object's "keys" are the dictionary's string keys.
11
122.  Message Format
13
14   Messages are formatted in a subset of JSON easily represented
15   as bencoded data -- arrays, objects, strings, and whole numbers.
16   Booleans are represented as numbers where 0 is false and 1 is true.
17   Floating-point numbers are represented as strings.
18
19   Messages are formatted as objects.  There are two types:
20   requests (described in 2.1) and responses (described in 2.2).
21
22   All text MUST be UTF-8 encoded.
23
242.1.  Requests
25
26   Requests support three keys:
27
28   (1) A required "method" string telling the name of the method to invoke
29   (2) An optional "arguments" object of key/value pairs
30   (3) An optional "tag" number used by clients to track responses.
31       If provided by a request, the response MUST include the same tag.
32
332.2.  Responses
34
35   Reponses support three keys:
36
37   (1) A required "result" string whose value MUST be "success" on success,
38       or an error string on failure.
39   (2) An optional "arguments" object of key/value pairs
40   (3) An optional "tag" number as described in 2.1.
41
422.3.  Transport Mechanism
43
44   HTTP POSTing a JSON-encoded request is the preferred way of communicating
45   with a Transmission RPC server; however, a simple notation also exists
46   for sending requests in the query portion of a URL.
47
48   The URL notation works as follows:
49   (1) Any key not "tag" or "method" is treated as an argument.
50   (2) The "arguments" key isn't needed, since data isn't nested.
51   (3) If the value in a key/value pair can be parsed as a number, then it is.
52       Otherwise if it can be parsed as an array of numbers, then it is.
53       Otherwise, it's parsed as a string.
54
55   Examples:
56   ?method=torrent-start&ids=1,2
57   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
58
593.  Torrent Requests
60
613.1.  Torrent Action Requests
62
63   Method name         | libtransmission function
64   --------------------+-------------------------------------------------
65   "torrent-remove"    | tr_torrentRemove
66   "torrent-start"     | tr_torrentStart
67   "torrent-stop"      | tr_torrentStop
68   "torrent-verify"    | tr_torrentVerify
69
70   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
71                      or both.  These are the torrents that the request will
72                      be applied to.  If "ids" is ommitted, the request is
73                      applied to all torrents.
74
75   Response arguments: none
76
773.2.  Torrent Mutators
78
79   Method name: "torrent-set"
80
81   Request arguments:
82
83   string                     | value type & description
84   ---------------------------+-------------------------------------------------
85   "files-wanted"             | array      indices of file(s) to download
86   "files-unwanted"           | array      indices of file(s) to not download
87   "ids"                      | array      torrent list, as described in 3.1
88   "peer-limit"               | number     maximum number of peers
89   "priority-high"            | array      indices of high-priority file(s)
90   "priority-low"             | array      indices of low-priority file(s)
91   "priority-normal"          | array      indices of normal-priority file(s)
92   "speed-limit-down"         | number     maximum download speed (in K/s)
93   "speed-limit-down-enabled" | 'boolean'  true if the download speed is limited
94   "speed-limit-up"           | number     maximum upload speed (in K/s)
95   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
96
97   Just as an empty "ids" value is shorthand for "all ids", using an empty array
98   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
99   "priority-normal" is shorthand for saying "all files".
100
101   Response arguments: none
102
1033.3.  Torrent Accessors
104
105   Method name: "torrent-get".
106
107   Request arguments:
108
109   (1) An opional "ids" array as described in 3.1.
110   (2) A required "fields" array of keys. (see list below)
111
112   Response arguments:
113
114   (1) A "torrents" array of objects, each of which contains
115       the key/value pairs matching the request's "fields" argument.
116
117   key                    | type                                 | source
118   -----------------------+--------------------------------------+---------
119   activityDate           | number                               | tr_stat
120   addedDate              | number                               | tr_stat
121   announceResponse       | string                               | tr_stat
122   announceURL            | string                               | tr_stat
123   comment                | string                               | tr_info
124   corruptEver            | number                               | tr_stat
125   creator                | string                               | tr_info
126   dateCreated            | number                               | tr_info
127   desiredAvailable       | number                               | tr_stat
128   doneDate               | number                               | tr_stat
129   downloadedEver         | number                               | tr_stat
130   downloadLimitMode      | number                               | tr_torrent
131   downloadLimit          | number                               | tr_torrent
132   error                  | number                               | tr_stat
133   errorString            | number                               | tr_stat
134   eta                    | number                               | tr_stat
135   files                  | array (see below)                    | n/a
136   hashString             | string                               | tr_info
137   haveUnchecked          | number                               | tr_stat
138   haveValid              | number                               | tr_stat
139   id                     | number                               | tr_torrent
140   isPrivate              | 'boolean                             | tr_torrent
141   lastAnnounceTime       | number                               | tr_stat
142   lastScrapeTime         | number                               | tr_stat
143   leechers               | number                               | tr_stat
144   leftUntilDone          | number                               | tr_stat
145   manualAnnounceTime     | number                               | tr_stat
146   maxConnectedPeers      | number                               | tr_torrent
147   name                   | string                               | tr_info
148   nextAnnounceTime       | number                               | tr_stat
149   nextScrapeTime         | number                               | tr_stat
150   peersConnected         | number                               | tr_stat
151   peersFrom              | object (see below)                   | n/a
152   peersGettingFromUs     | number                               | tr_stat
153   peersKnown             | number                               | tr_stat
154   peersSendingToUs       | number                               | tr_stat
155   pieceCount             | tnumber                              | tr_info
156   pieceSize              | tnumber                              | tr_info
157   priorities             | array (see below)                    | n/a
158   rateDownload (B/s)     | number                               | tr_stat
159   rateUpload (B/s)       | number                               | tr_stat
160   recheckProgress        | number                               | tr_stat
161   scrapeResponse         | string                               | tr_stat
162   scrapeURL              | string                               | tr_stat
163   seeders                | number                               | tr_stat
164   sizeWhenDone           | number                               | tr_stat
165   startDate              | number                               | tr_stat
166   status                 | number                               | tr_stat
167   swarmSpeed (K/s)       | number                               | tr_stat
168   timesCompleted         | number                               | tr_stat
169   trackers               | array (see below)                    | n/a
170   totalSize              | number                               | tr_info
171   uploadedEver           | number                               | tr_stat
172   uploadLimitMode        | number                               | tr_torrent
173   uploadLimit            | number                               | tr_torrent
174   uploadRatio            | 'double'                             | tr_stat
175   wanted                 | array (see below)                    | n/a
176   webseeds               | array (see below)                    | n/a
177   webseedsSendingToUs    | number                               | tr_stat
178                          |                                      |
179                          |                                      |
180   -----------------------+--------------------------------------+
181   files                  | array of objects, each containing:   |
182                          +-------------------------+------------+
183                          | key                     | type       |
184                          | bytesCompleted          | number     | tr_torrent
185                          | length                  | number     | tr_info
186                          | name                    | string     | tr_info
187   -----------------------+--------------------------------------+
188   peersFrom              | an object containing:                |
189                          +-------------------------+------------+
190                          | fromCache               | number     | tr_stat
191                          | fromIncoming            | number     | tr_stat
192                          | fromPex                 | number     | tr_stat
193                          | fromTracker             | number     | tr_stat
194   -----------------------+--------------------------------------+
195   priorities             | an array of tr_info.filecount        | tr_info
196                          | numbers. each is the tr_priority_t   |
197                          | mode for the corresponding file.     |
198   -----------------------+--------------------------------------+
199   trackers               | array of objects, each containing:   |
200                          +-------------------------+------------+
201                          | announce                | string     | tr_info
202                          | scrape                  | string     | tr_info
203                          | tier                    | number     | tr_info
204   -----------------------+--------------------------------------+
205   wanted                 | an array of tr_info.fileCount        | tr_info
206                          | 'booleans' true if the corresponding |
207                          | file is to be downloaded.            |
208   -----------------------+--------------------------------------+
209   webseeds               | an array of strings:                 |
210                          +-------------------------+------------+
211                          | webseed                 | string     | tr_info
212                          +-------------------------+------------+
213
214   Example:
215
216   Say we want to get the name and total size of torrents #7 and #10.
217
218   Request:
219
220      {
221         "arguments": {
222             "fields": [ "id", "name", "totalSize" ]
223         },
224         "method": "torrent-get",
225         "tag": 39693
226      }
227
228
229   Response:
230
231      {
232         "arguments": {
233            "torrents": [
234               {
235                   "id": 10,
236                   "name": "Fedora x86_64 DVD",
237                   "totalSize", 34983493932,
238               },
239               {
240                   "id": 7,
241                   "name": "Ubuntu x86_64 DVD",
242                   "totalSize", 9923890123,
243               }
244            ]
245         },
246         "result": "success",
247         "tag": 39693
248      }
249
2503.4.  Adding a Torrent
251
252   Method name: "torrent-add"
253
254   Request arguments:
255
256   key                | value type & description
257   -------------------+-------------------------------------------------
258   "download-dir"     | string      path to download the torrent to
259   "filename"         | string      location of the .torrent file
260   "metainfo"         | string      base64-encoded .torrent content
261   "paused"           | 'boolean'   if true, don't start the torrent
262   "peer-limit"       | number      maximum number of peers
263
264   Either "filename" OR "metainfo" MUST be included.
265   All other arguments are optional.
266
267   Response arguments: on success, a "torrent-added" object in the
268                       form of one of 3.3's tr_info objects with the
269                       fields for id, name, and hashString.
270
271
2724.   Session Requests
273
2744.1.  Session Arguments
275
276   string                     | value type & description
277   ---------------------------+-------------------------------------------------
278   "encryption"               | string     "required", "preferred", "tolerated"
279   "download-dir"             | string     default path to download torrents
280   "peer-limit"               | number     maximum global number of peers
281   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
282   "port"                     | number     port number
283   "port-forwarding-enabled"  | 'boolean'  true means enabled
284   "speed-limit-down"         | number     max global download speed (in K/s)
285   "speed-limit-down-enabled" | 'boolean'  true means enabled
286   "speed-limit-up"           | number     max global upload speed (in K/s)
287   "speed-limit-up-enabled"   | 'boolean'  true means enabled
288
2894.1.1.  Mutators
290
291   Method name: "session-set"
292   Request arguments: one or more of 4.1's arguments
293   Response arguments: none
294
2954.1.2.  Accessors
296
297   Method name: "session-get"
298   Request arguments: none
299   Response arguments: all of 4.1's arguments
300
3014.2.  Session Statistics
302
303   Method name: "session-stats"
304
305   Request arguments: none
306
307   Response arguments:
308
309   string                     | value type
310   ---------------------------+-------------------------------------------------
311   "activeTorrentCount"       | number
312   "downloadSpeed"            | number
313   "pausedTorrentCount"       | number
314   "torrentCount"             | number
315   "uploadSpeed"              | number
316   
317
Note: See TracBrowser for help on using the repository browser.