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

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

readability. better explain the response arguments a bit.

File size: 5.5 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   The entire protocol is 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   Response bodies support two members:
41   (1) An optional "arguments" object of name/value pairs.
42   (2) An optional "error" string which may be omitted on success.
43
443.  Torrent Requests
45
463.1.  Common Arguments
47
48   Most torrent requests support an "ids" argument, which is a list
49   containing unique torrent ids, or torrent sha1 hash strings, or both.
50   These are the torrents that the request will be applied to.
51   If "ids" is omitted, the request is applied to all torrents.
52
533.2.  Torrent Action Requests
54
55   Request names: "torrent-start", "torrent-stop",
56                  "torrent-remove", "torrent-verify"
57   Request arguments: 3.1's optional "ids" argument.
58   Response arguments: none.
59
603.3.  Torrent Info Requests
61
62   Request name: "torrent-info".
63   Request arguments: 3.1's optional "ids" argument.
64
65   Response arguments: "info", an array of objects based on libtransmission's
66   tr_info struct but differ in the following ways:
67
68   (1) tr_info's "hash" field is omitted.
69   (2) tr_info's "pieces" field is omitted.
70   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
71
72   Example Request:
73
74      {
75         "headers": {
76            "type": "request",
77            "tag": 666
78         },
79         "body": {
80            "arguments": {
81               "name": "torrent-info",
82               "ids": [ 7, 10 ]
83            }
84         }
85      }
86
87   Example Response:
88
89      {
90         "headers": {
91            "type": "response",
92            "tag": 666
93         }
94         "body": {
95            "arguments": {
96               "info": [
97                  {
98                     "id": 7,
99                     "totalSize": 9803930483,
100                     "pieceCount": 1209233,
101                     "pieceSize": 4096,
102                     "name": "Ubuntu x86_64 DVD",
103                     ...
104                  }
105                  {
106                     "id": 10,
107                     "totalSize": 2398480394,
108                     "pieceCount": 83943,
109                     "pieceSize": 12345,
110                     "name": "Ubuntu i386 DVD",
111                     ...
112                  }
113               }
114            }
115         }
116      }
117
1183.4.  Torrent Status Requests
119
120   Request name is "torrent-status".
121   Request arguments: 3.1's optional "ids" argument.
122
123   Response arguments: "status", an array of objects based on
124   libtransmission's tr_stat struct but which differ the following ways:
125
126   (1) tr_stat's "tracker" field is omitted
127   (2) a new string, "announce-url", is added
128   (3) a new string, "scrape-url", is added
129
1303.5.  Adding a Torrent
131
132   Request name: "torrent-add"
133   Request arguments:
134
135   string             | value type & description
136   -------------------+-------------------------------------------------
137   "autostart"        | boolean   true means to auto-start torrents
138   "directory"        | string    path to download the torrent to
139   "filename"         | string    location of the .torrent file
140   "max-peers"        | int       maximum number of peers
141   "speed-limit-down" | int       maximum download speed (in KiB/s)
142   "speed-limit-up"   | int       maximum upload speed (in KiB/s)
143
144   The "filename" argument is required; all others are optional.
145
146   Response arguments: 3.1's "error" if the request failed.
147
1484.   Session Status Requests
149
1504.1.  Session Arguments
151
152   string             | value type & description
153   -------------------+-------------------------------------------------
154   "autostart"        | boolean   true means to auto-start torrents
155   "directory"        | string    path to download torrents to
156   "encryption"       | string    "required", "preferred", or "plaintext"
157   "max-peers"        | int       maximum global number of peers
158   "port"             | int       port number
159   "port-forwarding"  | boolean   true means enabled.
160   "pex-allowed"      | boolean   true means allow pex for public torrents
161   "speed-limit-down" | int       maximum global download speed (in KiB/s)
162   "speed-limit-up"   | int       maximum global upload speed (in KiB/s)
163
1644.2.  Mutators
165
166   Request name: "session-set"
167   Request arguments: one or more of 4.1's session arguments
168   Response arguments: none
169
1704.2.  Accessors
171
172   Request name: "session-get"
173   Request arguments: none
174   Response arguments: all of 4.1's session arguments
175
Note: See TracBrowser for help on using the repository browser.