source: branches/daemon/daemon/ipcproto.txt @ 1623

Last change on this file since 1623 was 1617, checked in by joshe, 15 years ago

Add a daemon frontend.

File size: 14.6 KB
1It is assumed the reader is familiar with bencoding, as described in
2the BitTorrent protocol specification at
5Dictionary keys used below will be enclosed in quotation marks, these
6are used for clarity and are not part of the actual key.
8The IPC protocol is used to allow processes to control or retrieve
9information from a Transmission frontend, such as transmission-daemon
10or transmission-gtk. This communication is done over a unix-domain
11socket file, such as ~/.transmission/daemon/socket. In this document
12the Transmission frontend will be referred to as the server and the
13process connecting to it as the client.
15Once a client connects to the server's socket, messages may be
16exchanged until either end closes the connection. Messages contain an
1732-bit payload length, encoded as 8 bytes of ASCII hexidecimal,
18followed by the payload. Upper, lower, or mixed case for the length
19are all accpetable and must be handled correctly. Payload lengths
20greater than 2^31 - 8 (ie: 2147483640) are not allowed.
22For version 1, the message payload is a bencoded dictionary, the
23valid keys and value formats for which are described below. Multiple
24keys may be used in one message.
26An example version 1 message:
30For version 2 the message payload is a bencoded list containing a
31message id string followed by a bencoded value, the format of which is
32the same for version 1. The value may be followed by an optional
33bencoded integer, this is a message tag and is described in more
34detail below.
36An example version 2 message:
40The same message with a tag:
44Once the connection is made both the client and server must send a
45version 1 style message (ie: the payload is a dictionary and may not
46contain a tag) with the dictionary key "version" and a value formatted
47as described below. The version should be the first but not
48necessarily only key in the dictionary. Any other keys should be
49ignored and not processed as messages.
51The version value should be a bencoded dictionary containing two keys,
52"max" and "min". These are the minimum and maximum supported protocol
53versions, respectively. Communication will take place using the
54highest protocol version supported by both the client and the server,
55and is not possible at all if there is no common version. A client may
56receive a version value that is an integer instead of a dictionary
57with "min" and "max" keys. This deprecated version format indicates
58the only version supported by the server.
60An example message containing minimum and maximum versions 1 and 2:
64Tagged messages, only supported in version 2, allow a client to tag a
65message with a positive non-zero integer. The server is then required
66to send a response to the message even if none would normally be
67required, and to tag the response with the same integer. When the
68server receives a tagged message it must send exactly one message back
69with the same tag. The client is allowed to use the same tag for
70multiple messages, even if a response to the first is not received
71before the second it sent. If a tagged message does not normally
72require a response then a "succeeded", "failed" or "not-supported"
73message will be sent back.
75An example tagged message and response:
80Dictionary keys are encoded in UTF-8 and case sensitive. Any character
81except a NUL (0x00) is valid. A server or client need not support
82every possible key and should silently ignore any that it does not
85A list of keys and the format of their values follows. Also listed is
86the minimum protocol version that the key may be used with.
89Key:     "addfiles"
90Version: 1
91Format:  list of strings
92Example: 8:addfilesl21:/torrents/foo.torrent20:/home/me/bar.torrente
93Details: Each string is the absolute path to a torrent file for the
94         server to add. Note that whether or not the torrent file is
95         copied (allowing the original to be moved or deleted safely)
96         is implementation dependent and may not currently be known or
97         changed with this protocol.
99Key:     "automap"
100Version: 2
101Format:  int, 0 or 1
102Example: 7:automapi1e
103Details: Enable (1) or disable (0) automatic port mapping on the
104         server. Other integer values will likely be treated as 1 but
105         this shold not be relied upon.
107Key:     "autostart"
108Version: 2
109Format:  int, 0 or 1
110Example: 9:autostarti0e
111Details: Enable (1) or disable (0) automatic starting of new torrents
112         added via "addfiles" message.
114Key:     "directory"
115Version: 2
116Format:  string
117Example: 9:directory21:/home/roger/downloads
118Details: Set the default directory used for any torrents added in the future.
120Key:     "downlimit"
121Version: 2
122Format:  int
123Example: 9:downlimiti100e
124Details: Set the server's download limit in kilobytes per second.
125         Negative values are interpreted as no limit.
127Key:     "failed"
128Version: 2
129Format:  string
130Example: 6:failed17:permission denied
131Details: Sent in response to a tagged message to indicate failure.
133Key:     "get-automap"
134Version: 2
135Format:  value is ignored
136Example: 11:get-automap0:
137Details: Requests that an "automap" message be sent back.
139Key:     "get-autostart"
140Version: 2
141Format:  value is ignored
142Example: 13:get-autostart0:
143Details: Requests that an "autostart" message be sent back.
145Key:     "get-directory"
146Version: 2
147Format:  value is ignored
148Example: 13:get-directory
149Details: Requests that an "directory" message be sent back.
151Key:     "get-downlimit"
152Version: 2
153Format:  value is ignored
154Example: 13:get-downlimit0:
155Details: Requests that a "downlimit" message be sent back.
157Key:     "get-info"
158Version: 2
159Format:  dict with keys "id" and "type" for lists of ints and strings
160Example: 8:get-infod2:idli4ei7ei2ee4:typel4:hash4:nameee
161Details: Requests that the server send back an "info" message with
162         info on all the torrent IDs in "id". The "type" key requests
163         what info will be returned. See below for valid values to use
164         here. Since the torrent ID is always included in an "info"
165         message an empty or missing "type" key will cause only the ID
166         to be returned. An "info" message will always be sent back,
167         even if it is empty.
169Key:     "get-info-all"
170Version: 2
171Format:  list of strings
172Example: 12:get-info-alll4:hash4:namee
173Details: Same as "getinfo" message with all torrent IDs specified.
175Key:     "get-port"
176Version: 2
177Format:  value is ignored
178Example: 8:get-port0:
179Details: Requests that a "port" message be sent back.
181Key:     "get-status"
182Version: 2
183Format:  dict with keys "id" and "type" for lists of ints and strings
184Example: 10:get-statusd2:idli4ei7ei2ee4:typel4:hash4:nameee
185Details: Same as "get-info" message except status type strings are used
186         instead and the server sends back a "status" message.
188Key:     "get-status-all"
189Version: 2
190Format:  list of strings
191Example: 14:get-status-alll4:hash4:namee
192Details: Same as "get-status" message with all torrent IDs specified.
194Key:     "get-supported"
195Version: 2
196Format:  list of strings
197Example: 13:get-supportedl6:lookup8:get-porte
198Details: Request that a "supported" message be returned with whichever
199         of the given message keys are supported.
201Key:     "get-uplimit"
202Version: 2
203Format:  value is ignored
204Example: 11:get-uplimit0:
205Details: Requests that an "uplimit" message be sent back.
207Key:     "lookup"
208Version: 2
209Format:  list of strings
210Example: 6:lookupl40:0f16ea6965ee5133ea4dbb1e7f516e9fcf3d899ee
211Details: Request that the server send back an "info" message with "id"
212         and "hash" keys for any torrents with the given hashes.
214Key:     "info"
215Version: 2
216Format:  list of dictionaries
217Example: 4:infold2:idi3e4:name3:fooed2:idi9e4:name3:baree
218Details: A list containing information for several torrents. The
219         dictionaries always contain at least an "id" key with the
220         integer ID for the torrent, other possible values are listed
221         below.
223Key:     "noop"
224Version: 2
225Format:  value is ignored
226Example: 4:noop0:
227Details: This does nothing but keep the connection alive. With a tag
228         it may be used as a ping.
230Key:     "not-supported"
231Version: 2
232Format:  value is ignored
233Example: 13:not-supported0:
234Details: Sent in response to a tagged message to indicated that the
235         message was not supported.
237Key:     "port"
238Version: 2
239Format:  int between 0 and 65535
240Example: 4:porti9090e
241Details: Change the port the server uses to listen for incoming peer
242         connections.
244Key:     "quit"
245Version: 1
246Format:  value is ignored
247Example: 4:quit0:
248Details: Cause the server to quit.
250Key:     "remove"
251Version: 2
252Format:  list of torrent ID ints
253Example: 5:removeli3ei8ei6ee
254Details: Stop and remove the specified torrents. Note that whether or
255         not the downloaded data or the original torrent files will be
256         removed is implementation dependent and may not currently be
257         known or changed with this protocol. If a saved copy of the
258         torrent file has been made then it will always be deleted.
260Key:     "remove-all"
261Version: 2
262Format:  value is ignored
263Example: 10:remove-all0:
264Details: Like "remove" with all torrent IDs specified.
266Key:     "start"
267Version: 2
268Format:  list of torrent ID ints
269Example: 5:startli3ei8ei6ee
270Details: List of torrent IDs to start.
272Key:     "start-all"
273Version: 2
274Format:  value is ignored
275Example: 9:start-all0:
276Details: Start all torrents.
278Key:     "status"
279Version: 2
280Format:  list of dictionaries
281Example: 4:infold2:idi3e4:name3:fooed2:idi9e4:name3:baree
282Details: Same as "info" message except status type keys are used.
284Key:     "stop"
285Version: 2
286Format:  list of torrent ID ints
287Example: 4:stopli3ei8ei6ee
288Details: List of torrent IDs to stop.
290Key:     "stop-all"
291Version: 2
292Format:  value is ignored
293Example: 8:stop-all0:
294Details: Stop all torrents.
296Key:     "succeeded"
297Version: 2
298Format:  value is ignored
299Example: 8:succeeded0:
300Details: This is used to indicate that a tagged message was processed
301         successfully.
303Key:     "supported"
304Version: 2
305Format:  list of strings
306Example: 9:supportedl6:lookupe
307Details: Sent in response to a "get-supported" message, indicates that
308         the given messages ate supported.
310Key:     "uplimit"
311Version: 2
312Format:  int
313Example: 7:uplimiti20e
314Details: Set the server's upload limit in kilobytes per second.
315         Negative values are interpreted as no limit.
317Key:     "version"
318Version: 1
319Format:  dict containing int "min" and "max"
320Example: 7:versiond3:mini1e3:maxi2ee
321Details: Described above.
324Individual torrents are identified by a unique integer. This integer
325is only valid for the current connection and may be invalid or refer
326to another torrent in a future connection. If a torrent is closed it's
327ID will never be reused to refer to another torrent for at least the
328duration of the connection. Negative integers or 0 are not valid IDs.
331Info types for "get-info" and "info" messages. The only type for which
332support is mandatory is "id".
334"id"       integer, torrent's ID for this connection
335"hash"     SHA-1 info hash as a 40-char hex string
336"name"     string, torrent name
337"path"     string, path to .torrent file
338"saved"    integer, 1 if a copy of this torrent was saved, 0 otherwise
339"private"  integer, 1 if the torrent is private, 0 otherwise
340"trackers" a list of lists of dictionaries containing tracker info:
341             "address"  string, hostname or ip address of tracker
342             "port"     integer, port for tracker
343             "announce" string, announce url on tracker
344             "scrape"   string, scrape url on tracker, may be absent
345"comment"  string, comment from torrent file
346"creator"  string, creator of torrent file
347"date"     integer, date of torrent creation (unix time_t format)
348"size"     integer, total size of all files in bytes
349"files"    list of dictionaries for the files in this torrent:
350             "name" string, name of file
351             "size" integer, size of file in bytes
354Status types for "get-status" and "status" messages. The only type for
355which support is mandatory is "id".
357"completed"         integer, bytes of data downloaded and verified
358"download-speed"    integer, download speed in bytes per second
359"download-total"    integer, total bytes downloaded so far
360"error"             string, one of the following:
361                      "assert"          something happened that shouldn't
362                      "io-parent"       I dunno
363                      "io-permissions"  filesystem permission error probably
364                      "io-other"        other filesystem i/o error
365                      "tracker-error"   tracker returned error message
366                      "tracker-warning" tracker returned warning message
367                      "other"           other error
368                      zero-length or missing string indicates no error
369"error-message"     string, printable error message
370"eta"               integer, estimated seconds until downloading is finished
371"id"                integer, torrent's ID for this connection
372"peers-downloading" integer, peers downloading from us
373"peers-from"        dict with the following int keys, peer connection sources:
374                      "incoming"    peers connected to our listening port
375                      "tracker"     peers discovered from tracker
376                      "cache"       peers retrieved from on-disk cache
377                      "pex"         peers discovered via peer exchange
378"peers-total"       integer, total connected peers
379"peers-uploading"   integer, peers uploading to us
380"running"           integer, 0 if torrent is stopped or stopping, 1 otherwise
381"state"             string, one of the following:
382                      "checking"    performing hash check on file data
383                      "downloading" downloading file data
384                      "seeding"     seeding file data to peers
385                      "stopping"    contacting tracker to send 'stopped' event
386                      "paused"      torrent is not active
387"swarm-speed"       integer, swarm speed in bytes per second
388"tracker"           dict with the following keys, current active tracker
389                      "address"     string, hostname or ip address of tracker
390                      "port"        integer, port for tracker
391                      "announce"    string, tracker announce url
392                      "scrape"      string, tracker scrape url, may be absent
393"scrape-completed"  integer, total completed peers as reported by tracker
394"scrape-leechers"   integer, current leechers as reported by tracker
395"scrape-seeders"    integer, current, seeders as reported by tracker
396"upload-speed"      integer, upload speed in bytes per second
397"upload-total"      integer, total bytes uploaded so far
Note: See TracBrowser for help on using the repository browser.