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

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

(RPC) make all the speed units consistent.

File size: 14.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. "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   | length                 | tr_info
146                      | string   | name                   | tr_info
147   -------------------+----------+------------------------+-------------
148   history, 16        | number   | activityDate           | tr_stat
149                      | number   | addedDate              | tr_stat
150                      | number   | corruptEver            | tr_stat
151                      | number   | doneDate               | tr_stat
152                      | number   | downloadedEver         | tr_stat
153                      | number   | startDate              | tr_stat
154                      | number   | uploadedEver           | tr_stat
155   -------------------+----------+------------------------+-------------
156   id, 32             | number   | uniqueId               | tr_torrent
157                      | string   | hashString             | tr_info
158                      | string   | name                   | tr_info
159   -------------------+----------+------------------------+-------------
160   info, 64           | string   | comment                | tr_info
161                      | string   | creator                | tr_info
162                      | number   | dateCreated            | tr_info
163                      | number   | pieceCount             | tr_info
164                      | number   | pieceSize              | tr_info
165                      | 'boolean'| isPrivate              | tr_torrent
166   -------------------+----------+------------------------+-------------
167   limits, 128        | number   | downloadLimit          | tr_torrent
168                      | number   | downloadLimitMode      | tr_torrent
169                      | number   | maxConnectedPeers      | tr_torrent
170                      | number   | uploadLimit            | tr_torrent
171                      | number   | uploadLimitMode        | tr_torrent
172   -------------------+----------+------------------------+-------------
173   peers, 256         | number   | fromCache              | tr_stat
174                      | number   | fromIncoming           | tr_stat
175                      | number   | fromPex                | tr_stat
176                      | number   | fromTracker            | tr_stat
177   -------------------+----------+------------------------+-------------
178   priorities, 512    | array    | priorities             | tr_info
179                      | array    | wanted                 | tr_info
180                      +----------+--------------------------------------
181                      | priorities is an array of tr_info.fileCount
182                      | numbers.  Each is the tr_priority_t mode for
183                      | the corresponding file.
184                      +-------------------------------------------------
185                      | wanted is an array of tr_info.fileCount
186                      | 'booleans' true if the corresponding file
187                      | is to be downloaded.
188   -------------------+----------+------------------------+-------------
189   scrape, 1024       | number   | lastScrapeTime         | tr_stat
190                      | number   | nextScrapeTime         | tr_stat
191                      | string   | scrapeResponse         | tr_stat
192                      | string   | scrapeURL              | tr_stat
193   -------------------+----------+------------------------+-------------
194   size, 2048         | number   | haveUnchecked          | tr_stat
195                      | number   | haveValid              | tr_stat
196                      | number   | leftUntilDone          | tr_stat
197                      | number   | sizeWhenDone           | tr_stat
198                      | number   | totalSize              | tr_info
199   -------------------+----------+------------------------+-------------
200   tracker stats,     | number   | leechers               | tr_stat
201   4096               | number   | peersKnown             | tr_stat
202                      | number   | seeders                | tr_stat
203                      | number   | timesCompleted         | tr_stat
204   -------------------+----------+--------------------------------------
205   trackers, 8192     | array    | trackers
206                      +----------+--------------------------------------
207                      | trackers is an array of objects that contain:
208                      +----------+------------------------+-------------
209                      | string   | announce               | tr_info
210                      | string   | scrape                 | tr_info
211                      | number   | tier                   | tr_info
212   -------------------+----------+------------------------+-------------
213   webseeds, 16384    | array    | webseeds
214                      +----------+--------------------------------------
215                      | webseeds is an array of strings:
216                      +----------+------------------------+-------------
217                      | string   | webseed URL            | tr_info
218   -------------------+----------+------------------------+-------------
219
220   Example:
221
222   Say we want to get the name and total size of torrents #7 and #10.
223   name is in the "id" section (32) and total size is in "size" (2048),
224   so the "fields" argument will be 32 + 2048 == 2080.
225
226   Request:
227
228      {
229         "arguments": {
230             "fields": 2080,
231             "ids": [ 7, 10 ],
232             "sort-method": "name"
233         }
234         "method": "torrent-get",
235         "tag": 39693
236      }
237
238
239   Response:
240
241      {
242         "arguments": {
243            "fields": 2080,
244            "torrents": [
245               {
246                   "hashString": "sijioejisoefjiosejfioi",
247                   "haveUnchecked", 23023,
248                   "haveValid", 27986795145,
249                   "leftUntilDone", 0,
250                   "name": "Fedora x86_64 DVD",
251                   "sizeWhenDone", 34983493932,
252                   "totalSize", 34983493932,
253                   "uniqueId": 10,
254               }
255               {
256                   "hashString": "asdasiofjosejfoasjfiosj",
257                   "haveUnchecked", 0,
258                   "haveValid", 9923890123,
259                   "leftUntilDone", 0,
260                   "name": "Ubuntu x86_64 DVD",
261                   "sizeWhenDone", 9923890123,
262                   "totalSize", 9923890123,
263                   "uniqueId": 7,
264               },
265            ]
266         },
267         "result": "success",
268         "tag": 39693
269      }
270
2713.4.  Adding a Torrent
272
273   Method name: "torrent-add"
274
275   Request arguments:
276
277   key                | value type & description
278   -------------------+-------------------------------------------------
279   "download-dir"     | string      path to download the torrent to
280   "filename"         | string      location of the .torrent file
281   "metainfo"         | string      base64-encoded .torrent content
282   "paused"           | 'boolean'   if true, don't start the torrent
283   "peer-limit"       | number      maximum number of peers
284
285   Either "filename" OR "metainfo" must be included.
286   All other arguments are optional.
287
288   Response arguments: on success, a "torrent-added" object in the
289                       form of one of 3.3's tr_info objects with the
290                       fields for id, name, and hashString.
291
292
2934.   Session Requests
294
2954.1.  Session Arguments
296
297   string                     | value type & description
298   ---------------------------+-------------------------------------------------
299   "encryption"               | string     "required", "preferred", "tolerated"
300   "download-dir"             | string     default path to download torrents
301   "peer-limit"               | number     maximum global number of peers
302   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
303   "port"                     | number     port number
304   "port-forwarding-enabled"  | 'boolean'  true means enabled
305   "speed-limit-down"         | number     max global download speed (in K/s)
306   "speed-limit-down-enabled" | 'boolean'  true means enabled
307   "speed-limit-up"           | number     max global upload speed (in K/s)
308   "speed-limit-up-enabled"   | 'boolean'  true means enabled
309
3104.1.1.  Mutators
311
312   Method name: "session-set"
313   Request arguments: one or more of 4.1's arguments
314   Response arguments: none
315
3164.1.2.  Accessors
317
318   Method name: "session-get"
319   Request arguments: none
320   Response arguments: all of 4.1's arguments
321
3224.2.  Session Statistics
323
324   Method name: "session-stats"
325
326   Request arguments: none
327
328   Response arguments:
329
330   string                     | value type
331   ---------------------------+-------------------------------------------------
332   "activeTorrentCount"       | number
333   "downloadSpeed"            | number
334   "pausedTorrentCount"       | number
335   "torrentCount"             | number
336   "uploadSpeed"              | number
337   
338
Note: See TracBrowser for help on using the repository browser.