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

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

(#954) rpc: add "torrent-remove" method. rename tr_torrentDelete() as tr_torrentRemove() for consistency with various parts of the code.

File size: 8.8 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 name         | libtransmission function
67   --------------------+-------------------------------------------------
68   "torrent-close"     | tr_torrentClose
69   "torrent-remove"    | tr_torrentRemove
70   "torrent-start"     | tr_torrentStart
71   "torrent-stop"      | tr_torrentStop
72   "torrent-verify"    | tr_torrentVerify
73
74   Request arguments: "ids", a list of torrent id integers, sha1 hash strings,
75                      or both.  These are the torrents that the request will
76                      be applied to.  If "ids" is ommitted, the request is
77                      applied to all torrents.
78
79   Response arguments: none
80
813.2.  Torrent List
82
83   Method name: "torrent-list".
84
85   Request arguments: none.
86
87   Response arguments: "list", an array of objects that contain two keys:
88   a torrent's name string, and its unique torrent id.
89
903.3.  Torrent Info Requests
91
92   Method name: "torrent-info".
93
94   Request arguments: 3.1's optional "ids" argument.
95
96   Response arguments: "torrent-info", an array of objects based on
97   libtransmission's tr_info struct but different in the following ways:
98   (1) the torrent's "id" field is added.
99   (2) tr_info's "hash" field is omitted.
100   (3) tr_info's "pieces" field is omitted.
101   (4) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
102
103   Note that this is a fairly high-bandwidth request and that its results
104   don't change.  You should try to cache its results instead of re-calling it.
105
106   Example Request:
107
108      {
109         "arguments": { "ids": [ 7, 10 ] }
110         "method": "torrent-info",
111         "tag": 39693
112      }
113
114   Example Response:
115
116      {
117         "tag": 39693
118         "result": "success",
119         "arguments": {
120            "torrent-info": [
121               {
122                  "id": 7,
123                  "name": "Ubuntu x86_64 DVD",
124                  "pieceCount": 1209233,
125                  "pieceSize": 4096,
126                  "totalSize": 9803930483,
127                  ...
128               },
129               {
130                  "id": 10,
131                  "name": "Ubuntu i386 DVD",
132                  "pieceCount": 83943,
133                  "pieceSize": 12345,
134                  "totalSize": 2398480394,
135                  ...
136               }
137            ]
138         }
139      }
140
1413.4.  Torrent Status Requests
142
143   Method name: "torrent-status"
144
145   Request arguments: 3.1's optional "ids" argument.
146
147   Response arguments: "torrent-status", an array of objects based
148   on libtransmission's tr_stat struct but differerent in the
149   following ways:
150
151   (1) the torrent's "id" field is added.
152   (2) tr_info's "name" field is added.
153   (3) tr_stat's "tracker" field is omitted, and is instead
154       replaced with two strings: "announce-url" and scrape-url"
155
1563.5.  Adding a Torrent
157
158   Method name: "torrent-add"
159
160   Request arguments:
161
162   string             | value type & description
163   -------------------+-------------------------------------------------
164   "download-dir"     | string    path to download the torrent to
165   "filename"         | string    location of the .torrent file
166   "metainfo"         | string    base64-encoded .torrent content
167   "paused"           | boolean   if true, don't start the torrent
168   "peer-limit"       | int       maximum number of peers
169
170   Either "filename" OR "metainfo" must be included.
171   All other arguments are optional.
172
173   Response arguments: on success, a "torrent-added" object in the
174                       form of one of 3.3's tr_info objects.
175
1763.6.  Other torrent settings
177
178   Common arguments:
179
180   string                     | value type & description
181   ---------------------------+-------------------------------------------------
182   "peer-limit"               | int       maximum number of peers
183   "speed-limit-down"         | int       maximum download speed (in KiB/s)
184   "speed-limit-down-enabled" | boolean   true if the download speed is limited
185   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
186   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
187
1883.6.1.  Mutators
189
190   Method name: "torrent-set"
191   Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
192   Response arguments: none
193
1943.6.2.  Accessors
195
196   Method name: "torrent-get"
197   Request arguments: none
198   Response arguments: A "torrents" list of objects containing all
199                       of 3.6's arguments plus the torrent's "id" int.
200                     
201
2023.7  File Priorities
203
204   Common arguments:
205
206   string             | value type & description
207   -------------------+-------------------------------------------------
208   "files-wanted"     | array     indices of one or more file to download
209   "files-unwanted"   | array     indices of one or more file to not download
210   "priority-high"    | array     indices of one or more high-priority files
211   "priority-low"     | array     indices of one or more low-priority files
212   "priority-normal"  | array     indices of one or more normal-priority files
213
2143.7.1.  Mutators
215
216    Method name: "torrent-set-priorities"
217    Request arguments: 3.1's "ids", plus one or more of 3.7's arguments
218    Response arguments: none
219
2203.7.2.  Accessors
221
222    Method name: "torrent-get-priorities"
223    Request arguments: none
224    Response arguments: A "torrents" list of objects containing all
225                        of 3.7's arguments plus the torrent's "id" int.
226   
2274.   Session Status Requests
228
2294.1.  Session Arguments
230
231   string                     | value type & description
232   ---------------------------+-------------------------------------------------
233   "encryption"               | string   "required", "preferred", "tolerated"
234   "download-dir"             | string   default path to download torrents
235   "peer-limit"               | int      maximum global number of peers
236   "pex-allowed"              | boolean  true means allow pex in public torrents
237   "port"                     | int      port number
238   "port-forwarding-enabled"  | boolean  true means enabled.
239   "speed-limit-down"         | int      max global download speed (in KiB/s)
240   "speed-limit-down-enabled" | int      max global download speed (in KiB/s)
241   "speed-limit-up"           | int      max global upload speed (in KiB/s)
242   "speed-limit-up-enabled"   | int      max global upload speed (in KiB/s)
243
2444.2.  Mutators
245
246   Method name: "session-set"
247   Request arguments: one or more of 4.1's arguments
248   Response arguments: none
249
2504.2.  Accessors
251
252   Method name: "session-get"
253   Request arguments: none
254   Response arguments: all of 4.1's arguments
255
Note: See TracBrowser for help on using the repository browser.