source: trunk/doc/rpc-json-spec.txt @ 5827

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

make the request/response messages a little terser. add per-torrent speed limit toggles. rename ipc -> rpc.

File size: 7.0 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 "strings" are the dictionary's keys,
11   and an object's "members" are its string/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 in benc.
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 a 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
423.  Torrent Requests
43
443.1.  Torrent Action Requests
45
46   Method names: "torrent-start", "torrent-stop",
47                 "torrent-remove", "torrent-verify"
48
49   Request arguments: "ids", a list of unique torrent ids, sha1 hash strings,
50                      or both.  These are the torrents that the request will
51                      be applied to.  If "ids" is ommitted, the request is
52                      applied to all torrents.
53
54   Response arguments: none.
55
563.2.  Torrent Info Requests
57
58   Method name: "torrent-info".
59
60   Request arguments: 3.1's optional "ids" argument.
61
62   Response arguments: "info", an array of objects based on libtransmission's
63   tr_info struct but differ in the following ways:
64
65   (1) tr_info's "hash" field is omitted.
66   (2) tr_info's "pieces" field is omitted.
67   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
68
69   Example Request:
70
71      {
72         "arguments": { "ids": [ 7, 10 ] }
73         "method": "torrent-info",
74         "tag": 666
75      }
76
77   Example Response:
78
79      {
80         "tag": 666
81         "result": "success",
82         "arguments": {
83            "info": [
84               {
85                  "id": 7,
86                  "totalSize": 9803930483,
87                  "pieceCount": 1209233,
88                  "pieceSize": 4096,
89                  "name": "Ubuntu x86_64 DVD",
90                  ...
91               },
92               {
93                  "id": 10,
94                  "totalSize": 2398480394,
95                  "pieceCount": 83943,
96                  "pieceSize": 12345,
97                  "name": "Ubuntu i386 DVD",
98                  ...
99               }
100            ]
101         }
102      }
103
1043.3.  Torrent Status Requests
105
106   Method name: "torrent-status"
107
108   Request arguments: 3.1's optional "ids" argument.
109
110   Response arguments: "status", an array of objects based on
111   libtransmission's tr_stat struct but which differ the following ways:
112
113   (1) tr_stat's "tracker" field is omitted
114   (2) a new string, "announce-url", is added
115   (3) a new string, "scrape-url", is added
116
1173.4.  Adding a Torrent
118
119   Method name: "torrent-add"
120
121   Request arguments:
122
123   string             | value type & description
124   -------------------+-------------------------------------------------
125   "paused"           | boolean   if true, don't start the torrent
126   "destination"      | string    path to download the torrent to
127   "filename"         | string    location of the .torrent file
128   "peer-limit"       | int       maximum number of peers
129
130   The "filename" argument is required; all others are optional.
131
132   Response arguments: on success, a "torrent-added" object in the
133                       form of one of 3.1's tr_info objects.
134
1353.5.  Other torrent settings
136
137   Common arguments:
138
139   string                     | value type & description
140   ---------------------------+-------------------------------------------------
141   "peer-limit"               | int       maximum number of peers
142   "speed-limit-down"         | int       maximum download speed (in KiB/s)
143   "speed-limit-down-enabled" | boolean   true if the download speed is limited
144   "speed-limit-up"           | int       maximum upload speed (in KiB/s)
145   "speed-limit-up-enabled"   | boolean   true if the upload speed is limited
146
1473.5.1.  Mutators
148
149   Method name: "torrent-set"
150   Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
151   Response arguments: none
152
1533.5.2.  Accessors
154
155   Method name: "torrent-get"
156   Request arguments: none
157   Response arguments: A "torrents" list of objects containing all
158                       of 3.5's arguments plus the torrent's "id" int.
159                     
160
1613.6  File Priorities
162
163   Common arguments:
164
165   string             | value type & description
166   -------------------+-------------------------------------------------
167   "priority-high"    | array     indices of one or more high-priority files
168   "priority-low"     | array     indices of one or more low-priority files
169   "priority-normal"  | array     indices of one or more normal-priority files
170   "download"         | array     indices of one or more file to download
171   "no-download"      | array     indices of one or more file to not download
172
1733.6.1.  Mutators
174
175    Method name: "torrent-set-file"
176    Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
177    Response arguments: none
178
1793.6.2.  Accessors
180
181    Method name: "torrent-get-file"
182    Request arguments: none
183   Response arguments: A "torrents" list of objects containing all
184                       of 3.6's arguments plus the torrent's "id" int.
185   
1864.   Session Status Requests
187
1884.1.  Session Arguments
189
190   string                     | value type & description
191   ---------------------------+-------------------------------------------------
192   "encryption"               | string   "required", "preferred", "tolerated"
193   "peer-limit"               | int      maximum global number of peers
194   "port"                     | int      port number
195   "port-forwarding-enabled"  | boolean  true means enabled.
196   "pex-allowed"              | boolean  true means allow pex in public torrents
197   "speed-limit-down"         | int      max global download speed (in KiB/s)
198   "speed-limit-down-enabled" | int      max global download speed (in KiB/s)
199   "speed-limit-up"           | int      max global upload speed (in KiB/s)
200   "speed-limit-up-enabled"   | int      max global upload speed (in KiB/s)
201
2024.2.  Mutators
203
204   Method name: "session-set"
205   Request arguments: one or more of 4.1's arguments
206   Response arguments: none
207
2084.2.  Accessors
209
210   Method name: "session-get"
211   Request arguments: none
212   Response arguments: all of 4.1's arguments
213
Note: See TracBrowser for help on using the repository browser.