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

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

(rpc) fix the spec: recheckProgress is a 'double', not a whole number

File size: 15.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 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   peers                  | array (see below)                    | n/a
151   peersConnected         | number                               | tr_stat
152   peersFrom              | object (see below)                   | n/a
153   peersGettingFromUs     | number                               | tr_stat
154   peersKnown             | number                               | tr_stat
155   peersSendingToUs       | number                               | tr_stat
156   pieceCount             | tnumber                              | tr_info
157   pieceSize              | tnumber                              | tr_info
158   priorities             | array (see below)                    | n/a
159   rateDownload (B/s)     | number                               | tr_stat
160   rateUpload (B/s)       | number                               | tr_stat
161   recheckProgress        | 'double'                             | tr_stat
162   scrapeResponse         | string                               | tr_stat
163   scrapeURL              | string                               | tr_stat
164   seeders                | number                               | tr_stat
165   sizeWhenDone           | number                               | tr_stat
166   startDate              | number                               | tr_stat
167   status                 | number                               | tr_stat
168   swarmSpeed (K/s)       | number                               | tr_stat
169   timesCompleted         | number                               | tr_stat
170   trackers               | array (see below)                    | n/a
171   totalSize              | number                               | tr_info
172   uploadedEver           | number                               | tr_stat
173   uploadLimitMode        | number                               | tr_torrent
174   uploadLimit            | number                               | tr_torrent
175   uploadRatio            | 'double'                             | tr_stat
176   wanted                 | array (see below)                    | n/a
177   webseeds               | array (see below)                    | n/a
178   webseedsSendingToUs    | number                               | tr_stat
179                          |                                      |
180                          |                                      |
181   -----------------------+--------------------------------------+
182   files                  | array of objects, each containing:   |
183                          +-------------------------+------------+
184                          | key                     | type       |
185                          | bytesCompleted          | number     | tr_torrent
186                          | length                  | number     | tr_info
187                          | name                    | string     | tr_info
188   -----------------------+--------------------------------------+
189   peers                  | array of objects, each containing:   |
190                          +-------------------------+------------+
191                          | address                 | string     | tr_peer_stat
192                          | clientName              | string     | tr_peer_stat
193                          | clientIsChoked          | 'boolean'  | tr_peer_stat
194                          | clientIsInterested      | 'boolean'  | tr_peer_stat
195                          | isDownloadingFrom       | 'boolean'  | tr_peer_stat
196                          | isEncrypted             | 'boolean'  | tr_peer_stat
197                          | isIncoming              | 'boolean'  | tr_peer_stat
198                          | isUploadingTo           | 'boolean'  | tr_peer_stat
199                          | peerIsChoked            | 'boolean'  | tr_peer_stat
200                          | peerIsInterested        | 'boolean'  | tr_peer_stat
201                          | progress                | 'double'   | tr_peer_stat
202                          | rateToClient (B/s)      | number     | tr_peer_stat
203                          | rateToPeer (B/s)        | number     | tr_peer_stat
204   -----------------------+--------------------------------------+
205   peersFrom              | an object containing:                |
206                          +-------------------------+------------+
207                          | fromCache               | number     | tr_stat
208                          | fromIncoming            | number     | tr_stat
209                          | fromPex                 | number     | tr_stat
210                          | fromTracker             | number     | tr_stat
211   -----------------------+--------------------------------------+
212   priorities             | an array of tr_info.filecount        | tr_info
213                          | numbers. each is the tr_priority_t   |
214                          | mode for the corresponding file.     |
215   -----------------------+--------------------------------------+
216   trackers               | array of objects, each containing:   |
217                          +-------------------------+------------+
218                          | announce                | string     | tr_info
219                          | scrape                  | string     | tr_info
220                          | tier                    | number     | tr_info
221   -----------------------+--------------------------------------+
222   wanted                 | an array of tr_info.fileCount        | tr_info
223                          | 'booleans' true if the corresponding |
224                          | file is to be downloaded.            |
225   -----------------------+--------------------------------------+
226   webseeds               | an array of strings:                 |
227                          +-------------------------+------------+
228                          | webseed                 | string     | tr_info
229                          +-------------------------+------------+
230
231   Example:
232
233   Say we want to get the name and total size of torrents #7 and #10.
234
235   Request:
236
237      {
238         "arguments": {
239             "fields": [ "id", "name", "totalSize" ]
240         },
241         "method": "torrent-get",
242         "tag": 39693
243      }
244
245
246   Response:
247
248      {
249         "arguments": {
250            "torrents": [
251               {
252                   "id": 10,
253                   "name": "Fedora x86_64 DVD",
254                   "totalSize", 34983493932,
255               },
256               {
257                   "id": 7,
258                   "name": "Ubuntu x86_64 DVD",
259                   "totalSize", 9923890123,
260               }
261            ]
262         },
263         "result": "success",
264         "tag": 39693
265      }
266
2673.4.  Adding a Torrent
268
269   Method name: "torrent-add"
270
271   Request arguments:
272
273   key                | value type & description
274   -------------------+-------------------------------------------------
275   "download-dir"     | string      path to download the torrent to
276   "filename"         | string      location of the .torrent file
277   "metainfo"         | string      base64-encoded .torrent content
278   "paused"           | 'boolean'   if true, don't start the torrent
279   "peer-limit"       | number      maximum number of peers
280
281   Either "filename" OR "metainfo" MUST be included.
282   All other arguments are optional.
283
284   Response arguments: on success, a "torrent-added" object in the
285                       form of one of 3.3's tr_info objects with the
286                       fields for id, name, and hashString.
287
288
2894.   Session Requests
290
2914.1.  Session Arguments
292
293   string                     | value type & description
294   ---------------------------+-------------------------------------------------
295   "encryption"               | string     "required", "preferred", "tolerated"
296   "download-dir"             | string     default path to download torrents
297   "peer-limit"               | number     maximum global number of peers
298   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
299   "port"                     | number     port number
300   "port-forwarding-enabled"  | 'boolean'  true means enabled
301   "speed-limit-down"         | number     max global download speed (in K/s)
302   "speed-limit-down-enabled" | 'boolean'  true means enabled
303   "speed-limit-up"           | number     max global upload speed (in K/s)
304   "speed-limit-up-enabled"   | 'boolean'  true means enabled
305
3064.1.1.  Mutators
307
308   Method name: "session-set"
309   Request arguments: one or more of 4.1's arguments
310   Response arguments: none
311
3124.1.2.  Accessors
313
314   Method name: "session-get"
315   Request arguments: none
316   Response arguments: all of 4.1's arguments
317
3184.2.  Session Statistics
319
320   Method name: "session-stats"
321
322   Request arguments: none
323
324   Response arguments:
325
326   string                     | value type
327   ---------------------------+-------------------------------------------------
328   "activeTorrentCount"       | number
329   "downloadSpeed"            | number
330   "pausedTorrentCount"       | number
331   "torrentCount"             | number
332   "uploadSpeed"              | number
333   
334
Note: See TracBrowser for help on using the repository browser.