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

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

(very) rough draft of the new ipc protocol

File size: 5.8 KB
Line 
11.  Introduction
2
3   This document describes a protocol for interacting with Transmission
4   sessions remotely.
5
6   The JSON terminology in RFC 4627 is used. "array" is equivalent
7   to a benc list; "object" is equivalent to a benc dictionary;
8   an object's "strings" are the dictionary's keys,
9   and an object's "members" are its string/value pairs.
10
112.  Message Format
12
13   The entire protocol is formatted in a subset of JSON that understands
14   arrays, maps, strings, and whole numbers with no exponentials --
15   in short, the subset of JSON easily represented in benc.
16   floating-point numbers are represented as strings.
17   booleans are represented as integers where 0 is false and 1 is true.
18
19   There are only two message types, request and response.  Both have
20   the same format: an object with two members whose strings are
21   "headers" and "body", and whose values are both objects.
22
232.1.  Headers
24
25   Message headers support two members:
26   (1) A required "type" string whose value must be "request" or "response".
27   (2) An optional "tag" integer that may be supplied by request.
28       Responses MUST return an identical tag member.
29
302.2.  Request Body
31
32   Request bodies support two members:
33   (1) A required "name" string telling the name of the request.
34   (2) An optional "arguments" object of argument name/value pairs.
35
362.3.  Response Body
37
38   Response bodies support three members:
39   (1) A required "name" string which matches the request's name.
40   (2) An optional "error" string which may be omitted on success.
41   (3) An optional "arguments" object of argument name/value pairs.
42
433.  Torrent Requests
44
453.1.  Common Arguments
46
47   Most torrent requests support an "ids" argument, which is a list
48   containing unique torrent information ids, or torrent sha1 hash strings,
49   or both.  These are the torrents that the request will be applied to.
50   If the ids are omitted, the request is applied to all torrents.
51
523.2.  Torrent Action Requests
53
54   Request names: "torrent-start", "torrent-stop", "torrent-remove",
55"torrent-verify".
56   The only supported argument is 3.1's "ids" argument.
57   The response has no arguments.
58
593.3.  Torrent Info Requests
60
61   Request name is "torrent-info".
62   The only supported argument is 3.1's "ids" argument.
63
64   The response's arguments object contains a member whose string
65   is "info" and whose value is an array of tr_info objects.
66   tr_info objects are (nearly) 1-to-1 mappings of libtransmission's
67   tr_info struct, where the members' string in the tr_info field name,
68   and the members' value is the field's value.
69
70   The tr_info object differs from libtransmission's tr_info struct
71   in the following ways:
72   (1) tr_info's "hash" field is omitted.
73   (2) tr_info's "pieces" field is omitted.
74   (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
75
76   Example Request:
77
78      {
79         "headers": {
80            "type": "request"
81         },
82         "body": {
83            "arguments": {
84               "name": "torrent-info",
85               "ids": [1, 2]
86            }
87         }
88      }
89
90   Example Response:
91
92      {
93         "headers": {
94            "type": "response"
95         }
96         "body": {
97            "arguments": {
98               "info": [
99                  {
100                     "id": 1,
101                     "totalSize": 9803930483,
102                     "pieceCount": 1209233,
103                     "pieceSize": 4096,
104                     "name": "Ubuntu x86_64 DVD",
105                     ...
106                  }
107                  {
108                     "id": 2,
109                     "totalSize": 2398480394,
110                     "pieceCount": 83943,
111                     "pieceSize": 12345,
112                     "name": "Ubuntu i386 DVD",
113                     ...
114                  }
115               }
116            }
117         }
118      }
119
1203.4.  Torrent Status Requests
121
122   Request name is "torrent-status".
123   The only supported argument is 3.1's "ids" argument.
124
125   The response's arguments contains a member whose string is "status"
126   and whose value is an array of tr_stat objects.  tr_stat objects
127   are (nearly) 1-to-1 mappings of libtransmission's tr_stat struct,
128   where the members' string in the tr_stat field name, and the
129   members' value is the field's value.
130
131   The tr_stat object differs from libtransmission's tr_stat struct
132   in the following ways:
133
134   (1) tr_stat's "tracker" field is omitted and replaced
135       with two fields: "announce-url" and "scrape-url"
136
1373.5.  Adding a Torrent
138
139   Request name is "torrent-add".
140   All arguments are optional except "filename".
141   Supported arguments are:
142
143   string             | value type & description
144   -------------------+-------------------------------------------------
145   "autostart"        | boolean.  true means to auto-start torrents.
146   "directory"        | string.   path to download the torrent to.
147   "filename"         | string.   location of the .torrent file.
148   "speed-limit-up"   | int.      speed in KiB/s
149   "speed-limit-down" | int.      speed in KiB/s
150
151
1524.   Session Status Requests
153
1544.1.  Mutators
155
156   The request name to change the session's state is "session-set".
157   Supported arguments are:
158
159   string             | value type & description
160   -------------------+-------------------------------------------------
161   "autostart"        | boolean.  true means to auto-start torrents.
162   "directory"        | string.   path to download torrents to.
163   "encryption"       | string.   "required", "preferred", or "plaintext"
164   "port"             | int.      port number
165   "port-forwarding"  | boolean.  true means enabled.
166   "pex-allowed"      | boolean.  true means allow pex for public torrents.
167   "speed-limit-up"   | int.      speed in KiB/s
168   "speed-limit-down" | int.      speed in KiB/s
169
1704.2.  Accessors
171
172   Request name: "session-get"
173   Request arguments: none
174   Response arguments: all the arguments described in 4.1.
175
Note: See TracBrowser for help on using the repository browser.