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

Last change on this file since 6505 was 6505, checked in by charles, 13 years ago

fix a cut/paste error in the spec.

File size: 13.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 Mutators
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   (1) An opional "ids" array as described in 3.1.
104   (2) A required "fields" array of keys. (see list below)
105
106   Response arguments:
107
108   (1) A "torrents" array of objects, each of which contains
109       the key/value pairs matching the request's "fields" argument.
110
111   key                    | type                                 | source
112   -----------------------+--------------------------------------+---------
113   activityDate           | number                               | tr_stat
114   addedDate              | number                               | tr_stat
115   announceResponse       | string                               | tr_stat
116   announceURL            | string                               | tr_stat
117   comment                | string                               | tr_info
118   corruptEver            | number                               | tr_stat
119   creator                | string                               | tr_info
120   dateCreated            | number                               | tr_info
121   desiredAvailable       | number                               | tr_stat
122   doneDate               | number                               | tr_stat
123   downloadedEver         | number                               | tr_stat
124   downloadLimitMode      | number                               | tr_torrent
125   downloadLimit          | number                               | tr_torrent
126   error                  | number                               | tr_stat
127   errorString            | number                               | tr_stat
128   eta                    | number                               | tr_stat
129   files                  | array (see below)                    | n/a
130   hashString             | string                               | tr_info
131   haveUnchecked          | number                               | tr_stat
132   haveValid              | number                               | tr_stat
133   id                     | number                               | tr_torrent
134   isPrivate              | 'boolean                             | tr_torrent
135   lastAnnounceTime       | number                               | tr_stat
136   lastScrapeTime         | number                               | tr_stat
137   leechers               | number                               | tr_stat
138   leftUntilDone          | number                               | tr_stat
139   manualAnnounceTime     | number                               | tr_stat
140   maxConnectedPeers      | number                               | tr_torrent
141   name                   | string                               | tr_info
142   nextAnnounceTime       | number                               | tr_stat
143   nextScrapeTime         | number                               | tr_stat
144   peersConnected         | number                               | tr_stat
145   peersFrom              | object (see below)                   | n/a
146   peersGettingFromUs     | number                               | tr_stat
147   peersKnown             | number                               | tr_stat
148   peersSendingToUs       | number                               | tr_stat
149   pieceCount             | tnumber                              | tr_info
150   pieceSize              | tnumber                              | tr_info
151   priorities             | array (see below)                    | n/a
152   rateDownload           | number                               | tr_stat
153   rateUpload             | number                               | tr_stat
154   recheckProgress        | number                               | tr_stat
155   scrapeResponse         | string                               | tr_stat
156   scrapeURL              | string                               | tr_stat
157   seeders                | number                               | tr_stat
158   sizeWhenDone           | number                               | tr_stat
159   startDate              | number                               | tr_stat
160   status                 | number                               | tr_stat
161   swarmSpeed (K/s)       | number                               | tr_stat
162   timesCompleted         | number                               | tr_stat
163   trackers               | array (see below)                    | n/a
164   totalSize              | number                               | tr_info
165   uploadedEver           | number                               | tr_stat
166   uploadLimitMode        | number                               | tr_torrent
167   uploadLimit            | number                               | tr_torrent
168   uploadRatio            | 'double'                             | tr_stat
169   wanted                 | array (see below)                    | n/a
170   webseeds               | array (see below)                    | n/a
171   webseedsSendingToUs    | number                               | tr_stat
172                          |                                      |
173                          |                                      |
174   -----------------------+--------------------------------------+
175   files                  | array of objects, each containing:   |
176                          +------------------+-------------------+
177                          | key              | type              |
178                          | bytesCompleted   | number            | tr_torrent
179                          | length           | number            | tr_info
180                          | name             | string            | tr_info
181   -----------------------+--------------------------------------+
182   peersFrom              | an object containing:                |
183                          +------------------+-------------------+
184                          | fromCache        | number            | tr_stat
185                          | fromIncoming     | number            | tr_stat
186                          | fromPex          | number            | tr_stat
187                          | fromTracker      | number            | tr_stat
188   -----------------------+--------------------------------------+
189   priorities             | an array of tr_info.filecount        | tr_info
190                          | numbers. each is the tr_priority_t   |
191                          | mode for the corresponding file.     |
192   -----------------------+--------------------------------------+
193   trackers               | array of objects, each containing:   |
194                          +------------------+-------------------+
195                          | announce         | string            | tr_info
196                          | scrape           | string            | tr_info
197                          | tier             | number            | tr_info
198   -----------------------+--------------------------------------+
199   wanted                 | an array of tr_info.fileCount        | tr_info
200                          | 'booleans' true if the corresponding |
201                          | file is to be downloaded.            |
202   -----------------------+--------------------------------------+
203   webseeds               | an array of strings:                 |
204                          +------------------+-------------------+
205                          | webseed          | string            | tr_info
206                          +------------------+-------------------+
207
208   Example:
209
210   Say we want to get the name and total size of torrents #7 and #10.
211
212   Request:
213
214      {
215         "arguments": {
216             "fields": [ "id", "name", "totalSize" ]
217         }
218         "method": "torrent-get",
219         "tag": 39693
220      }
221
222
223   Response:
224
225      {
226         "arguments": {
227            "torrents": [
228               {
229                   "id": 10,
230                   "name": "Fedora x86_64 DVD",
231                   "totalSize", 34983493932,
232               }
233               {
234                   "id": 7,
235                   "name": "Ubuntu x86_64 DVD",
236                   "totalSize", 9923890123,
237               },
238            ]
239         },
240         "result": "success",
241         "tag": 39693
242      }
243
2443.4.  Adding a Torrent
245
246   Method name: "torrent-add"
247
248   Request arguments:
249
250   key                | value type & description
251   -------------------+-------------------------------------------------
252   "download-dir"     | string      path to download the torrent to
253   "filename"         | string      location of the .torrent file
254   "metainfo"         | string      base64-encoded .torrent content
255   "paused"           | 'boolean'   if true, don't start the torrent
256   "peer-limit"       | number      maximum number of peers
257
258   Either "filename" OR "metainfo" MUST be included.
259   All other arguments are optional.
260
261   Response arguments: on success, a "torrent-added" object in the
262                       form of one of 3.3's tr_info objects with the
263                       fields for id, name, and hashString.
264
265
2664.   Session Requests
267
2684.1.  Session Arguments
269
270   string                     | value type & description
271   ---------------------------+-------------------------------------------------
272   "encryption"               | string     "required", "preferred", "tolerated"
273   "download-dir"             | string     default path to download torrents
274   "peer-limit"               | number     maximum global number of peers
275   "pex-allowed"              | 'boolean'  true means allow pex in public torrents
276   "port"                     | number     port number
277   "port-forwarding-enabled"  | 'boolean'  true means enabled
278   "speed-limit-down"         | number     max global download speed (in K/s)
279   "speed-limit-down-enabled" | 'boolean'  true means enabled
280   "speed-limit-up"           | number     max global upload speed (in K/s)
281   "speed-limit-up-enabled"   | 'boolean'  true means enabled
282
2834.1.1.  Mutators
284
285   Method name: "session-set"
286   Request arguments: one or more of 4.1's arguments
287   Response arguments: none
288
2894.1.2.  Accessors
290
291   Method name: "session-get"
292   Request arguments: none
293   Response arguments: all of 4.1's arguments
294
2954.2.  Session Statistics
296
297   Method name: "session-stats"
298
299   Request arguments: none
300
301   Response arguments:
302
303   string                     | value type
304   ---------------------------+-------------------------------------------------
305   "activeTorrentCount"       | number
306   "downloadSpeed"            | number
307   "pausedTorrentCount"       | number
308   "torrentCount"             | number
309   "uploadSpeed"              | number
310   
311
Note: See TracBrowser for help on using the repository browser.