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

Last change on this file since 6377 was 6377, checked in by charles, 14 years ago

#1101 (rpc): add individual file progress to torrent-get's "files" message

File size: 15.1 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
222.1.  Requests
23
24   Requests support three keys:
25
26   (1) A required "method" string telling the name of the method to invoke
27   (2) An optional "arguments" object of key/value pairs
28   (3) An optional "tag" number used by clients to track responses.
29       If provided by a request, the response MUST include the same tag.
30
312.2.  Responses
32
33   Reponses support three keys:
34
35   (1) A required "result" string whose value must be "success" on success,
36       or an error string on failure.
37   (2) An optional "arguments" object of key/value pairs
38   (3) An optional "tag" number as described in 2.1.
39
402.3.  Transport Mechanism
41
42   HTTP POSTing a JSON-encoded request is the preferred way of communicating
43   with a Transmission RPC server; however, a simple notation also exists
44   for sending requests in the query portion of a URL.
45
46   The URL notation works as follows:
47   (1) Any key not "tag" or "method" is treated as an argument.
48   (2) The "arguments" key isn't needed, since data isn't nested.
49   (3) If the value in a key/value pair can be parsed as a number, then it is.
50       Otherwise if it can be parsed as an array of numbers, then it is.
51       Otherwise, it's parsed as a string.
52
53   Examples:
54   ?method=torrent-start&ids=1,2
55   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
56
573.  Torrent Requests
58
593.1.  Torrent Action Requests
60
61   Method name         | libtransmission function
62   --------------------+-------------------------------------------------
63   "torrent-remove"    | tr_torrentRemove
64   "torrent-start"     | tr_torrentStart
65   "torrent-stop"      | tr_torrentStop
66   "torrent-verify"    | tr_torrentVerify
67
68   Request arguments: "ids", a list of torrent id numbers, sha1 hash strings,
69                      or both.  These are the torrents that the request will
70                      be applied to.  If "ids" is ommitted, the request is
71                      applied to all torrents.
72
73   Response arguments: none
74
753.2.  Torrent Mutator
76
77   Method name: "torrent-set"
78
79   Request arguments:
80
81   string                     | value type & description
82   ---------------------------+-------------------------------------------------
83   "files-wanted"             | array      indices of file(s) to download
84   "files-unwanted"           | array      indices of file(s) to not download
85   "ids"                      | array      torrent list, as described in 3.1
86   "peer-limit"               | number     maximum number of peers
87   "priority-high"            | array      indices of high-priority file(s)
88   "priority-low"             | array      indices of low-priority file(s)
89   "priority-normal"          | array      indices of normal-priority file(s)
90   "speed-limit-down"         | number     maximum download speed (in K/s)
91   "speed-limit-down-enabled" | 'boolean'  true if the download speed is limited
92   "speed-limit-up"           | number     maximum upload speed (in K/s)
93   "speed-limit-up-enabled"   | 'boolean'  true if the upload speed is limited
94
95   Response arguments: none
96
973.3.  Torrent Accessors
98
99   Method name: "torrent-get".
100
101   Request arguments:
102
103   string       | required? | default | value type & description
104   -------------+-----------+---------+---------------------------------------
105   "ids"        | no        | all     | array     described in 3.1
106   "fields"     | yes       | n/a     | number    bitwise-or'ed field
107                |           |         |           values from the table below
108
109   Response arguments:
110
111   (1) A "fields" number identical to the request's
112   (2) A "torrents" array of objects, each of which contains the
113       key/value fields that match the "fields" argument.
114       See the table below for a complete list.
115
116   "fields" value     | response | response               | source
117                      | value    | key                    |
118   -------------------+----------+------------------------+-------------
119   activity, 1        | number   | desiredAvailable       | tr_stat
120                      | number   | eta                    | tr_stat
121                      | number   | peersConnected         | tr_stat
122                      | number   | peersGettingFromUs     | tr_stat
123                      | number   | peersSendingToUs       | tr_stat
124                      | number   | rateDownload           | tr_stat
125                      | number   | rateUpload             | tr_stat
126                      | number   | recheckProgress        | tr_stat
127                      | number   | status                 | tr_stat
128                      | number   | swarmSpeed (K/s)       | tr_stat
129                      | 'double' | uploadRatio            | tr_stat
130                      | number   | webseedsSendingToUs    | tr_stat
131   -------------------+----------+------------------------+-------------
132   announce, 2        | string   | announceResponse       | tr_stat
133                      | string   | announceURL            | tr_stat
134                      | number   | lastAnnounceTime       | tr_stat
135                      | number   | manualAnnounceTime     | tr_stat
136                      | number   | nextAnnounceTime       | tr_stat
137   -------------------+----------+------------------------+-------------
138   error, 4           | number   | error                  | tr_stat
139                      | number   | errorString            | tr_stat
140   -------------------+----------+------------------------+-------------
141   files, 8           | array    | files
142                      +----------+--------------------------------------
143                      | files is an array of objects that contain:
144                      +----------+------------------------+-------------
145                      | number   | bytesCompleted         | tr_torrent
146                      | number   | length                 | tr_info
147                      | string   | name                   | tr_info
148   -------------------+----------+------------------------+-------------
149   history, 16        | number   | activityDate           | tr_stat
150                      | number   | addedDate              | tr_stat
151                      | number   | corruptEver            | tr_stat
152                      | number   | doneDate               | tr_stat
153                      | number   | downloadedEver         | tr_stat
154                      | number   | startDate              | tr_stat
155                      | number   | uploadedEver           | tr_stat
156   -------------------+----------+------------------------+-------------
157   id, 32             | number   | uniqueId               | tr_torrent
158                      | string   | hashString             | tr_info
159                      | string   | name                   | tr_info
160   -------------------+----------+------------------------+-------------
161   info, 64           | string   | comment                | tr_info
162                      | string   | creator                | tr_info
163                      | number   | dateCreated            | tr_info
164                      | number   | pieceCount             | tr_info
165                      | number   | pieceSize              | tr_info
166                      | 'boolean'| isPrivate              | tr_torrent
167   -------------------+----------+------------------------+-------------
168   limits, 128        | number   | downloadLimit          | tr_torrent
169                      | number   | downloadLimitMode      | tr_torrent
170                      | number   | maxConnectedPeers      | tr_torrent
171                      | number   | uploadLimit            | tr_torrent
172                      | number   | uploadLimitMode        | tr_torrent
173   -------------------+----------+------------------------+-------------
174   peers, 256         | not defined yet
175   -------------------+----------+------------------------+-------------
176   peer stats, 512    | number   | fromCache              | tr_stat
177                      | number   | fromIncoming           | tr_stat
178                      | number   | fromPex                | tr_stat
179                      | number   | fromTracker            | tr_stat
180   -------------------+----------+------------------------+-------------
181   priorities, 1024   | array    | priorities             | tr_info
182                      | array    | wanted                 | tr_info
183                      +----------+--------------------------------------
184                      | priorities is an array of tr_info.fileCount
185                      | numbers.  Each is the tr_priority_t mode for
186                      | the corresponding file.
187                      +-------------------------------------------------
188                      | wanted is an array of tr_info.fileCount
189                      | 'booleans' true if the corresponding file
190                      | is to be downloaded.
191   -------------------+----------+------------------------+-------------
192   scrape, 2048       | number   | lastScrapeTime         | tr_stat
193                      | number   | nextScrapeTime         | tr_stat
194                      | string   | scrapeResponse         | tr_stat
195                      | string   | scrapeURL              | tr_stat
196   -------------------+----------+------------------------+-------------
197   size, 4096         | number   | haveUnchecked          | tr_stat
198                      | number   | haveValid              | tr_stat
199                      | number   | leftUntilDone          | tr_stat
200                      | number   | sizeWhenDone           | tr_stat
201                      | number   | totalSize              | tr_info
202   -------------------+----------+------------------------+-------------
203   tracker stats,     | number   | leechers               | tr_stat
204   8192               | number   | peersKnown             | tr_stat
205                      | number   | seeders                | tr_stat
206                      | number   | timesCompleted         | tr_stat
207   -------------------+----------+--------------------------------------
208   trackers, 16384    | array    | trackers
209                      +----------+--------------------------------------
210                      | trackers is an array of objects that contain:
211                      +----------+------------------------+-------------
212                      | string   | announce               | tr_info
213                      | string   | scrape                 | tr_info
214                      | number   | tier                   | tr_info
215   -------------------+----------+------------------------+-------------
216   webseeds, 32768    | array    | webseeds
217                      +----------+--------------------------------------
218                      | webseeds is an array of strings:
219                      +----------+------------------------+-------------
220                      | string   | webseed URL            | tr_info
221   -------------------+----------+------------------------+-------------
222
223   Example:
224
225   Say we want to get the name and total size of torrents #7 and #10.
226   name is in the "id" section (32) and total size is in "size" (2048),
227   so the "fields" argument will be 32 + 2048 == 2080.
228
229   Request:
230
231      {
232         "arguments": {
233             "fields": 2080,
234             "ids": [ 7, 10 ],
235             "sort-method": "name"
236         }
237         "method": "torrent-get",
238         "tag": 39693
239      }
240
241
242   Response:
243
244      {
245         "arguments": {
246            "fields": 2080,
247            "torrents": [
248               {
249                   "hashString": "sijioejisoefjiosejfioi",
250                   "haveUnchecked", 23023,
251                   "haveValid", 27986795145,
252                   "leftUntilDone", 0,
253                   "name": "Fedora x86_64 DVD",
254                   "sizeWhenDone", 34983493932,
255                   "totalSize", 34983493932,
256                   "uniqueId": 10,
257               }
258               {
259                   "hashString": "asdasiofjosejfoasjfiosj",
260                   "haveUnchecked", 0,
261                   "haveValid", 9923890123,
262                   "leftUntilDone", 0,
263                   "name": "Ubuntu x86_64 DVD",
264                   "sizeWhenDone", 9923890123,
265                   "totalSize", 9923890123,
266                   "uniqueId": 7,
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
3134.1.1.  Mutators
314
315   Method name: "session-set"
316   Request arguments: one or more of 4.1's arguments
317   Response arguments: none
318
3194.1.2.  Accessors
320
321   Method name: "session-get"
322   Request arguments: none
323   Response arguments: all of 4.1's arguments
324
3254.2.  Session Statistics
326
327   Method name: "session-stats"
328
329   Request arguments: none
330
331   Response arguments:
332
333   string                     | value type
334   ---------------------------+-------------------------------------------------
335   "activeTorrentCount"       | number
336   "downloadSpeed"            | number
337   "pausedTorrentCount"       | number
338   "torrentCount"             | number
339   "uploadSpeed"              | number
340   
341
Note: See TracBrowser for help on using the repository browser.