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

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

(RPC) add utility arguments for torrent-info: sort by (activity|age|id|name|progress|ratio|state|tracker), filter by (active|all|downloading|paused|seeding)

File size: 15.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 that understands
15   arrays, maps, strings, and whole numbers with no exponentials --
16   in short, the subset of JSON easily represented as bencoded data.
17   Floating-point numbers are represented as strings.
18   Booleans are represented as integers where 0 is false and 1 is true.
19
20   Messages are represented as JSON objects.  There are two types:
21   requests (described in 2.1) and responses (described in 2.2).
22
232.1.  Requests
24
25   Requests supports three keys:
26
27   (1) A required "method" string telling the name of the method to invoke
28   (2) An optional "arguments" object of key/value pairs
29   (3) An optional "tag" integer used by clients to track responses.
30       If provided by a request, the response MUST include the same tag.
31
322.2.  Responses
33
34   Reponses support three keys:
35
36   (1) A required "result" string whose value must be "success" on success,
37       or an error string on failure.
38   (2) An optional "arguments" object of key/value pairs
39   (3) An optional "tag" integer as described in 2.1.
40
412.3.  Transport Mechanism
42
43   POSTing a JSON-encoded request is the preferred way of communicating
44   with the Transmission server; however, a simple notation also exists
45   for sending requests in the query portion of a URL.
46
47   The URL notation works as follows:
48   (1) Any key not "tag" or "method" is assumed to be in "arguments".
49   (2) The "arguments" key isn't needed, since data isn't nested.
50   (3) If the entire value in a key/value pair can be parsed as an integer,
51       it's parsed into a JSON number.
52       Otherwise, if the value can be parsed as comma-delimited integers,
53       it's parsed into a JSON array of integers.
54       Otherwise, the value is treated as a string.
55
56   Examples:
57   ?method=torrent-start&ids=1,2
58   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
59
603.  Torrent Requests
61
623.1.  Torrent Action Requests
63
64   Method name         | libtransmission function
65   --------------------+-------------------------------------------------
66   "torrent-remove"    | tr_torrentRemove
67   "torrent-start"     | tr_torrentStart
68   "torrent-stop"      | tr_torrentStop
69   "torrent-verify"    | tr_torrentVerify
70
71   Request arguments: "ids", a list of torrent id integers, sha1 hash strings,
72                      or both.  These are the torrents that the request will
73                      be applied to.  If "ids" is ommitted, the request is
74                      applied to all torrents.
75
76   Response arguments: none
77
783.2.  Torrent Information Requests
79
80   Method name: "torrent-info".
81
82   The request supports four arguments:
83
84   (1) "ids", as described in section 3.1.
85   (2) A required "fields" number as described in the table below
86   (3) An optional "sort" string whose value should be one of:
87       "activity", "age", "id", "name", "progress", "ratio", "state", "tracker".
88   (4) An optional "sort-ascending" 'boolean'.
89       This is only used if "sort-method" is supplied.
90       Its default value is 'true'.
91   (5) An optional "filter" string whose value may be one of:
92       "active", "all", "downloading", "paused", "seeding"
93
94   The respons supports two arguments:
95
96   (1) A required "fields" number identical to the request's
97   (2) A "torrent-info" list of objects, each of which contains the
98       response names described in the table below.
99
100   field and          | response | response               | source
101   numeric value      | type     | name                   |
102   -------------------+----------+------------------------+-------------
103   activity, 1        | number   | desiredAvailable       | tr_stat
104                      | number   | eta                    | tr_stat
105                      | number   | peersConnected         | tr_stat
106                      | number   | peersGettingFromUs     | tr_stat
107                      | number   | peersSendingToUs       | tr_stat
108                      | number   | rateDownload           | tr_stat
109                      | number   | rateUpload             | tr_stat
110                      | number   | recheckProgress        | tr_stat
111                      | number   | status                 | tr_stat
112                      | number   | swarmSpeed             | tr_stat
113                      | number   | webseedsSendingToUs    | tr_stat
114   -------------------+----------+------------------------+-------------
115   announce, 2        | string   | announceResponse       | tr_stat
116                      | string   | announceURL            | tr_stat
117                      | string   | lastAnnounceTime       | tr_stat
118                      | string   | manualAnnounceTime     | tr_stat
119                      | string   | nextAnnounceTime       | tr_stat
120   -------------------+----------+------------------------+-------------
121   error, 4           | number   | error                  | tr_stat
122                      | number   | errorString            | tr_Stat
123   -------------------+----------+------------------------+-------------
124   files, 8           | array    | files
125                      +----------+--------------------------------------
126                      | files is an array of objects that contain:
127                      +----------+------------------------+-------------
128                      | number   | length                 | tr_info
129                      | string   | name                   | tr_info
130   -------------------+----------+------------------------+-------------
131   history, 16        | number   | activityDate           | tr_stat
132                      | number   | addedDate              | tr_stat
133                      | number   | corruptEver            | tr_stat
134                      | number   | doneDate               | tr_stat
135                      | number   | downloadedEver         | tr_stat
136                      | number   | startDate              | tr_stat
137                      | number   | uploadedEver           | tr_stat
138   -------------------+----------+------------------------+-------------
139   id, 32             | number   | uniqueId               | tr_torrent
140                      | string   | hashString             | tr_info
141                      | string   | name                   | tr_info
142   -------------------+----------+------------------------+-------------
143   info, 64           | string   | comment                | tr_info
144                      | string   | creator                | tr_info
145                      | number   | dateCreated            | tr_info
146                      | number   | pieceCount             | tr_info
147                      | number   | pieceSize              | tr_info
148   -------------------+----------+------------------------+-------------
149   limits, 128        | number   | downloadLimit          | tr_torrent
150                      | number   | downloadLimitMode      | tr_torrent
151                      | number   | maxConnectedPeers      | tr_torrent
152                      | number   | uploadLimit            | tr_torrent
153                      | number   | uploadLimitMode        | tr_torrent
154   -------------------+----------+------------------------+-------------
155   peers, 256         | object   | peersFrom              | tr_stat
156                      +----------+------------------------+-------------
157                      | peersFrom contains:
158                      +----------+------------------------+-------------
159                      | number   | cache                  | tr_stat
160                      | number   | incoming               | tr_stat
161                      | number   | pex                    | tr_stat
162                      | number   | tracker                | tr_stat
163   -------------------+----------+------------------------+-------------
164   scrape, 512        | number   | lastScrapeTime         | tr_stat
165                      | number   | nextScrapeTime         | tr_stat
166                      | string   | scrapeResponse         | tr_stat
167                      | string   | scrapeURL              | tr_stat
168   -------------------+----------+------------------------+-------------
169   size, 1024         | number   | haveUnchecked          | tr_stat
170                      | number   | haveValid              | tr_stat
171                      | number   | leftUntilDone          | tr_stat
172                      | 'double' | percentComplete        | tr_stat
173                      | 'double' | percentDone            | tr_stat
174                      | 'double' | ratio                  | tr_stat
175                      | number   | sizeWhenDone           | tr_stat
176                      | number   | totalSize              | tr_stat
177   -------------------+----------+------------------------+-------------
178   tracker stats,     | number   | leechers               | tr_stat
179   2048               | number   | peersKnown             | tr_stat
180                      | number   | seeders                | tr_stat
181                      | number   | timesCompleted         | tr_stat
182   -------------------+----------+--------------------------------------
183   trackers, 4096     | array    | trackers
184                      +----------+--------------------------------------
185                      | trackers is an array of objects that contain:
186                      +----------+------------------------+-------------
187                      | string   | announce               | tr_info
188                      | string   | scrape                 | tr_info
189                      | number   | tier                   | tr_info
190   -------------------+----------+------------------------+-------------
191   webseeds, 8192     | object   | webseeds
192                      +----------+--------------------------------------
193                      | webseeds contains:
194                      | an array of weseed url strings
195   -------------------+----------+------------------------+-------------
196
197
198   Example:
199
200   Say we want to get the ratio and name of torrents 7 and 10.
201   name is in the "id" section (32) and ratio is in "size" (1024),
202   so the "fields" argument will be 32 + 1024 == 1056.
203
204   Request:
205
206      {
207         "arguments": {
208             "fields": 1056,
209             "ids": [ 7, 10 ],
210             "sort-method": "name"
211         }
212         "method": "torrent-info",
213         "tag": 39693
214      }
215
216
217   Response:
218
219      {
220         "arguments": {
221            "fields": 1056,
222            "torrent-info": [
223               {
224                   "hashString": "sijioejisoefjiosejfioi",
225                   "haveUnchecked", 23023,
226                   "haveValid", 27986795145,
227                   "leftUntilDone", 0,
228                   "name": "Fedora x86_64 DVD",
229                   "percentComplete", "0.8010",
230                   "percentDone", "0.8010",
231                   "ratio", "0.604034",
232                   "sizeWhenDone", 34983493932,
233                   "totalSize", 34983493932,
234                   "uniqueId": 10,
235               }
236               {
237                   "hashString": "asdasiofjosejfoasjfiosj",
238                   "haveUnchecked", 0,
239                   "haveValid", 9923890123,
240                   "leftUntilDone", 0,
241                   "name": "Ubuntu x86_64 DVD",
242                   "percentComplete", "1.0000",
243                   "percentDone", "1.0000",
244                   "ratio", "2.23222",
245                   "sizeWhenDone", 9923890123,
246                   "totalSize", 9923890123,
247                   "uniqueId": 7,
248               },
249            ]
250         },
251         "result": "success",
252         "tag": 39693
253      }
254
2553.3.  Adding a Torrent
256
257   Method name: "torrent-add"
258
259   Request arguments:
260
261   key                | value type & description
262   -------------------+-------------------------------------------------
263   "download-dir"     | string    path to download the torrent to
264   "filename"         | string    location of the .torrent file
265   "metainfo"         | string    base64-encoded .torrent content
266   "paused"           | boolean   if true, don't start the torrent
267   "peer-limit"       | int       maximum number of peers
268
269   Either "filename" OR "metainfo" must be included.
270   All other arguments are optional.
271
272   Response arguments: on success, a "torrent-added" object in the
273                       form of one of 3.3's tr_info objects with the
274                       fields for id, name, and hashString.
275
2763.4.  Other Torrent Settings
277
278   Common arguments:
279
280   string                     | value type & description
281   ---------------------------+-------------------------------------------------
282   "peer-limit"               | int       maximum number of peers
283   "speed-limit-down"         | int       maximum download speed (in KiB/s)
284   "speed-limit-down-enabled" | boolean   true if the download speed is limited
285   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
286   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
287
2883.4.1.  Mutators
289
290   Method name: "torrent-set"
291   Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
292   Response arguments: none
293                     
294
2953.5  File Priorities
296
297   Common arguments:
298
299   string             | value type & description
300   -------------------+-------------------------------------------------
301   "files-wanted"     | array     indices of one or more file to download
302   "files-unwanted"   | array     indices of one or more file to not download
303   "priority-high"    | array     indices of one or more high-priority files
304   "priority-low"     | array     indices of one or more low-priority files
305   "priority-normal"  | array     indices of one or more normal-priority files
306
3073.5.1.  Mutators
308
309    Method name: "torrent-set-priorities"
310    Request arguments: 3.1's "ids", plus one or more of 3.7's arguments
311    Response arguments: none
312
3133.5.2.  Accessors
314
315    Method name: "torrent-get-priorities"
316    Request arguments: none
317    Response arguments: A "torrents" list of objects containing all
318                        of 3.7's arguments plus the torrent's "id" int.
319   
3204.   Session Status Requests
321
3224.1.  Session Arguments
323
324   string                     | value type & description
325   ---------------------------+-------------------------------------------------
326   "encryption"               | string   "required", "preferred", "tolerated"
327   "download-dir"             | string   default path to download torrents
328   "peer-limit"               | int      maximum global number of peers
329   "pex-allowed"              | boolean  true means allow pex in public torrents
330   "port"                     | int      port number
331   "port-forwarding-enabled"  | boolean  true means enabled
332   "speed-limit-down"         | int      max global download speed (in KiB/s)
333   "speed-limit-down-enabled" | boolean  true means enabled
334   "speed-limit-up"           | int      max global upload speed (in KiB/s)
335   "speed-limit-up-enabled"   | boolean  true means enabled
336
3374.2.  Mutators
338
339   Method name: "session-set"
340   Request arguments: one or more of 4.1's arguments
341   Response arguments: none
342
3434.2.  Accessors
344
345   Method name: "session-get"
346   Request arguments: none
347   Response arguments: all of 4.1's arguments
348
Note: See TracBrowser for help on using the repository browser.