source: trunk/doc/ipc-json-spec.txt @ 5813

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

partial implementation of json-ipc backend: torrent start/stop/close/verify/stat/info, as are getting & setting per-torrent peer limits, upload speeds, and download speeds. this is a work in progress.

File size: 7.4 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   There are only two message types: request and response.  Both
22   are JSON objects with two members:  "headers" (described in 2.1)
23   and "body" (described in 2.2 - 2.3).
24
252.1.  Headers
26
27   Message headers support two members:
28   (1) A required "type" string whose value must be "request" or "response".
29   (2) An optional "tag" integer supplied by requests for their own use.
30       Responses MUST include the request tag's verbatim.
31
322.2.  Request Body
33
34   Request bodies support two members:
35   (1) A required "name" string telling the name of the request.
36   (2) An optional "arguments" object of name/value pairs.
37
382.3.  Response Body
39
40   All response bodies support two members:
41   (1) A required "result" string whose value must be "success" on success,
42       and may be "no-permission", "bad-format", or "error" on failure.
43   (2) An optional "arguments" object of name/value pairs.
44       The contents of these arguments depend on the request's name.
45
463.  Torrent Requests
47
483.1.  Torrent Action Requests
49
50   Request names: "torrent-start", "torrent-stop",
51                  "torrent-remove", "torrent-verify"
52   Request arguments: "ids", a list of unique torrent ids, sha1 hash strings,
53                      or both.  These are the torrents that the request will
54                      be applied to.  If "ids" is ommitted, the request is
55                      applied to all torrents.
56   Response arguments: none.
57
583.2.  Torrent Info Requests
59
60   Request name: "torrent-info".
61   Request arguments: 3.1's optional "ids" argument.
62
63   Response arguments: "info", an array of objects based on libtransmission's
64   tr_info struct but differ in the following ways:
65
66   (1) tr_info's "hash" field is omitted.
67   (2) tr_info's "pieces" field is omitted.
68   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
69
70   Example Request:
71
72      {
73         "headers": {
74            "type": "request",
75            "tag": 666
76         },
77         "body": {
78            "name": "torrent-info",
79            "arguments": {
80               "ids": [ 7, 10 ]
81            }
82         }
83      }
84
85   Example Response:
86
87      {
88         "headers": {
89            "type": "response",
90            "tag": 666
91         }
92         "body": {
93            "result": "success",
94            "arguments": {
95               "info": [
96                  {
97                     "id": 7,
98                     "totalSize": 9803930483,
99                     "pieceCount": 1209233,
100                     "pieceSize": 4096,
101                     "name": "Ubuntu x86_64 DVD",
102                     ...
103                  }
104                  {
105                     "id": 10,
106                     "totalSize": 2398480394,
107                     "pieceCount": 83943,
108                     "pieceSize": 12345,
109                     "name": "Ubuntu i386 DVD",
110                     ...
111                  }
112               ]
113            }
114         }
115      }
116
1173.3.  Torrent Status Requests
118
119   Request name is "torrent-status".
120   Request arguments: 3.1's optional "ids" argument.
121
122   Response arguments: "status", an array of objects based on
123   libtransmission's tr_stat struct but which differ the following ways:
124
125   (1) tr_stat's "tracker" field is omitted
126   (2) a new string, "announce-url", is added
127   (3) a new string, "scrape-url", is added
128
1293.4.  Adding a Torrent
130
131   Request name: "torrent-add"
132   Request arguments:
133
134   string             | value type & description
135   -------------------+-------------------------------------------------
136   "autostart"        | boolean   true means to auto-start torrents
137   "directory"        | string    path to download the torrent to
138   "filename"         | string    location of the .torrent file
139   "max-peers"        | int       maximum number of peers
140   "speed-limit-down" | int       maximum download speed (in KiB/s)
141   "speed-limit-up"   | int       maximum upload speed (in KiB/s)
142
143   The "filename" argument is required; all others are optional.
144
145   Response arguments: none.
146
1473.5.  Other torrent settings
148
149   Common arguments:
150
151   string             | value type & description
152   -------------------+-------------------------------------------------
153   "max-peers"        | int            maximum number of peers
154   "speed-limit-down" | int            maximum download speed (in KiB/s)
155   "speed-limit-up"   | int            maximum upload speed (in KiB/s)
156
1573.5.1.  Mutators
158
159   Request name: "torrent-set"
160   Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
161   Response arguments: none
162
1633.5.2.  Accessors
164
165   Request name: "torrent-get"
166   Request arguments: none
167   Response arguments: "torrents", a list of torrent objects containing
168                       all of 3.5's arguments plus the id passed in
169                       by "torrent-set".
170                     
171
1723.6  File Priorities
173
174   Common arguments:
175
176   string             | value type & description
177   -------------------+-------------------------------------------------
178   "priority-high"    | array          indices of one or more high-priority files
179   "priority-low"     | array          indices of one or more low-priority files
180   "priority-normal"  | array          indices of one or more normal-priority files
181   "download"         | array          indices of one or more file to download
182   "no-download"      | array          indices of one or more file to not download
183
1843.6.1.  Mutators
185
186    Request name: "torrent-set-file"
187    Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
188    Response arguments: none
189
1903.6.2.  Accessors
191
192    Request name: "torrent-get-file"
193    Request arguments: none
194   Response arguments: list of objects, one per torrent, containing
195                       all of 3.6's arguments plus the id passed in
196                       by "torrent-set".
197   
1984.   Session Status Requests
199
2004.1.  Session Arguments
201
202   string             | value type & description
203   -------------------+-------------------------------------------------
204   "autostart"        | boolean   true means to auto-start torrents
205   "directory"        | string    path to download torrents to
206   "encryption"       | string    "required", "preferred", or "plaintext"
207   "max-peers"        | int       maximum global number of peers
208   "port"             | int       port number
209   "port-forwarding"  | boolean   true means enabled.
210   "pex-allowed"      | boolean   true means allow pex for public torrents
211   "speed-limit-down" | int       maximum global download speed (in KiB/s)
212   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)
213
2144.2.  Mutators
215
216   Request name: "session-set"
217   Request arguments: one or more of 4.1's arguments
218   Response arguments: none
219
2204.2.  Accessors
221
222   Request name: "session-get"
223   Request arguments: none
224   Response arguments: all of 4.1's arguments
225
Note: See TracBrowser for help on using the repository browser.