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

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

(1) RPC "add-torrent" now lets clients embed base64-encoded metainfo directly into the request
(2) remove the RISON code; it didn't make the final cut
(3) add base64 encode/decode utilities and unit tests

File size: 8.6 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   an object's "keys" are the dictionary's string keys,
11   and an object's "members" are its key/value pairs.
12
132.  Message Format
14
15   Messages are formatted in a subset of JSON that understands
16   arrays, maps, strings, and whole numbers with no exponentials --
17   in short, the subset of JSON easily represented as bencoded data.
18   Floating-point numbers are represented as strings.
19   Booleans are represented as integers where 0 is false and 1 is true.
20
21   Messages are represented as JSON objects.  There are two types:
22   requests (described in 2.1) and responses (described in 2.2).
23
242.1.  Requests
25
26   Requests supports three keys:
27
28   (1) A required "method" string telling the name of the method to invoke
29   (2) An optional "arguments" object of name/value pairs
30   (3) An optional "tag" integer used for 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 name/value pairs
40   (3) An optional "tag" integer as described in 2.1.
41
422.3.  Request IPC Notation
43
44   As a convenience, a casual URI notation is supported for requests via the
45   query portion of a URI.  The advantage of this is that all current requests
46   can be invoked via a very simple http GET request.  The possible future
47   disadvantage is that it limits nesting and listing structured requests.
48
49   The URI notation works as follows:
50   (1) Any key not "tag" or "method" is assumed to be in "arguments".
51   (2) The "arguments" key isn't needed, since data isn't nested.
52   (3) If the entire value in a key/value pair can be parsed as an integer,
53       it's parsed into a JSON number.
54       Otherwise, if the value can be parsed as comma-delimited integers,
55       it's parsed into a JSON array of integers.
56       Otherwise, the value is treated as a string.
57
58   Examples:
59   ?method=torrent-start&ids=1,2
60   ?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
61
623.  Torrent Requests
63
643.1.  Torrent Action Requests
65
66   Method names: "torrent-start", "torrent-stop",
67                 "torrent-remove", "torrent-verify"
68
69   Request arguments: "ids", a list of torrent id integers, sha1 hash strings,
70                      or both.  These are the torrents that the request will
71                      be applied to.  If "ids" is ommitted, the request is
72                      applied to all torrents.
73
74   Response arguments: none
75
763.2.  Torrent List
77
78   Method name: "torrent-list".
79
80   Request arguments: none.
81
82   Response arguments: "list", an array of objects that contain two keys:
83   a torrent's name string, and its unique torrent id.
84
853.3.  Torrent Info Requests
86
87   Method name: "torrent-info".
88
89   Request arguments: 3.1's optional "ids" argument.
90
91   Response arguments: "torrent-info", an array of objects based on
92   libtransmission's tr_info struct but different in the following ways:
93   (1) the torrent's "id" field is added.
94   (2) tr_info's "hash" field is omitted.
95   (3) tr_info's "pieces" field is omitted.
96   (4) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
97
98   Note that this is a fairly high-bandwidth request and that its results
99   don't change.  You should try to cache its results instead of re-calling it.
100
101   Example Request:
102
103      {
104         "arguments": { "ids": [ 7, 10 ] }
105         "method": "torrent-info",
106         "tag": 39693
107      }
108
109   Example Response:
110
111      {
112         "tag": 39693
113         "result": "success",
114         "arguments": {
115            "torrent-info": [
116               {
117                  "id": 7,
118                  "name": "Ubuntu x86_64 DVD",
119                  "pieceCount": 1209233,
120                  "pieceSize": 4096,
121                  "totalSize": 9803930483,
122                  ...
123               },
124               {
125                  "id": 10,
126                  "name": "Ubuntu i386 DVD",
127                  "pieceCount": 83943,
128                  "pieceSize": 12345,
129                  "totalSize": 2398480394,
130                  ...
131               }
132            ]
133         }
134      }
135
1363.4.  Torrent Status Requests
137
138   Method name: "torrent-status"
139
140   Request arguments: 3.1's optional "ids" argument.
141
142   Response arguments: "torrent-status", an array of objects based
143   on libtransmission's tr_stat struct but differerent in the
144   following ways:
145
146   (1) the torrent's "id" field is added.
147   (2) tr_info's "name" field is added.
148   (3) tr_stat's "tracker" field is omitted, and is instead
149       replaced with two strings: "announce-url" and scrape-url"
150
1513.5.  Adding a Torrent
152
153   Method name: "torrent-add"
154
155   Request arguments:
156
157   string             | value type & description
158   -------------------+-------------------------------------------------
159   "download-dir"     | string    path to download the torrent to
160   "filename"         | string    location of the .torrent file
161   "metainfo"         | string    base64-encoded .torrent content
162   "paused"           | boolean   if true, don't start the torrent
163   "peer-limit"       | int       maximum number of peers
164
165   Either "filename" OR "metainfo" must be included.
166   All other arguments are optional.
167
168   Response arguments: on success, a "torrent-added" object in the
169                       form of one of 3.3's tr_info objects.
170
1713.6.  Other torrent settings
172
173   Common arguments:
174
175   string                     | value type & description
176   ---------------------------+-------------------------------------------------
177   "peer-limit"               | int       maximum number of peers
178   "speed-limit-down"         | int       maximum download speed (in KiB/s)
179   "speed-limit-down-enabled" | boolean   true if the download speed is limited
180   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
181   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
182
1833.6.1.  Mutators
184
185   Method name: "torrent-set"
186   Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
187   Response arguments: none
188
1893.6.2.  Accessors
190
191   Method name: "torrent-get"
192   Request arguments: none
193   Response arguments: A "torrents" list of objects containing all
194                       of 3.6's arguments plus the torrent's "id" int.
195                     
196
1973.7  File Priorities
198
199   Common arguments:
200
201   string             | value type & description
202   -------------------+-------------------------------------------------
203   "files-wanted"     | array     indices of one or more file to download
204   "files-unwanted"   | array     indices of one or more file to not download
205   "priority-high"    | array     indices of one or more high-priority files
206   "priority-low"     | array     indices of one or more low-priority files
207   "priority-normal"  | array     indices of one or more normal-priority files
208
2093.7.1.  Mutators
210
211    Method name: "torrent-set-priorities"
212    Request arguments: 3.1's "ids", plus one or more of 3.7's arguments
213    Response arguments: none
214
2153.7.2.  Accessors
216
217    Method name: "torrent-get-priorities"
218    Request arguments: none
219    Response arguments: A "torrents" list of objects containing all
220                        of 3.7's arguments plus the torrent's "id" int.
221   
2224.   Session Status Requests
223
2244.1.  Session Arguments
225
226   string                     | value type & description
227   ---------------------------+-------------------------------------------------
228   "encryption"               | string   "required", "preferred", "tolerated"
229   "download-dir"             | string   default path to download torrents
230   "peer-limit"               | int      maximum global number of peers
231   "pex-allowed"              | boolean  true means allow pex in public torrents
232   "port"                     | int      port number
233   "port-forwarding-enabled"  | boolean  true means enabled.
234   "speed-limit-down"         | int      max global download speed (in KiB/s)
235   "speed-limit-down-enabled" | int      max global download speed (in KiB/s)
236   "speed-limit-up"           | int      max global upload speed (in KiB/s)
237   "speed-limit-up-enabled"   | int      max global upload speed (in KiB/s)
238
2394.2.  Mutators
240
241   Method name: "session-set"
242   Request arguments: one or more of 4.1's arguments
243   Response arguments: none
244
2454.2.  Accessors
246
247   Method name: "session-get"
248   Request arguments: none
249   Response arguments: all of 4.1's arguments
250
Note: See TracBrowser for help on using the repository browser.