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

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

(rpc) tweaks to the rpc spec.

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