source: branches/1.1x/doc/ipcproto.txt

Last change on this file was 5144, checked in by charles, 9 years ago

fix typo

File size: 23.0 KB
Line 
1It is assumed the reader is familiar with bencoding, as described in
2the BitTorrent protocol specification at
3http://www.bittorrent.org/protocol.html
4
5Dictionary keys used below will be enclosed in quotation marks, these
6are used for clarity and are not part of the actual key.
7
8The IPC protocol is used to allow processes to control or retrieve
9information from Transmission frontend, such as transmission-daemon,
10or the GTK+ or Mac OS X frontends.  This communication is done
11over a unix-domain socket file such as
12~/.transmission/daemon/socket. In this document the Transmission
13frontend will be referred to as the server and the process connecting
14to it as the client.
15
16Once a client connects to the server's socket, messages may be
17exchanged until either end closes the connection. Messages contain an
1832-bit payload length, encoded as 8 bytes of ASCII hexadecimal,
19followed by the payload. Upper, lower, or mixed case for the length
20are all acceptable and must be handled correctly. Payload lengths
21greater than 2^31 - 8 (ie: 2147483640 decimal, 7FFFFFF8 hex) are not
22allowed.
23
24Bencoded messages will additionally be shown in the following format
25for better readability:
26str  - "this is a string"
27num  - 38795
28list - ("wheeee", 435, "writing docs is boring")
29dict - {"name": "Josh", "beverage": "coffee", "quantity": "too damn much" }
30
31For version 1, the message payload is a bencoded dictionary, the
32valid keys and value formats for which are described below. Multiple
33keys may be used in one message.
34
35An example version 1 message:
36
370000000Ed4:porti51413ee
38        {"port": 51413}
39
40For version 2 the message payload is a bencoded list containing a
41message id string followed by a bencoded value, the format of which is
42the same for version 1. The value may be followed by an optional
43bencoded integer, this is a message tag and is described in more
44detail below.
45
46An example version 2 message:
47
480000001El12:get-info-alll4:hashee
49        ("get-info-all", ("hash"))
50
51The same message with a tag:
52
5300000021l12:get-info-alll4:hashei5ee
54        ("get-info-all", ("hash"), 5)
55
56Once the connection is made both the client and server must send a
57version 1 style message (ie: the payload is a dictionary and may not
58contain a tag) with the dictionary key "version" and a value formatted
59as described below. The version should be the first but not
60necessarily only key in the dictionary. Any other keys should be
61ignored and not processed as messages. Neither the client nor the
62server should wait to receive a version message before sending one, it
63must be sent immediately. No other messages should be sent until the
64version is received.
65
66The version value should be a bencoded dictionary containing two keys,
67"max" and "min". These are the minimum and maximum supported protocol
68versions, respectively. Communication will take place using the
69highest protocol version supported by both the client and the server,
70and is not possible at all if there is no common version. A client may
71receive a version value that is an integer instead of a dictionary
72with "min" and "max" keys. This deprecated version format indicates
73the only version supported by the server.
74
75The version dictionary may optionally contain a key "label". This is a
76human-readable name for the software, it is not machine-readable and
77neither servers nor clients should attempt to parse it.
78
79An example message containing minimum and maximum versions 1 and 2:
80
810000001Dd7:versiond3:mini1e3:maxi2eee
82        {"version": {"min": 1, "max": 2}}
83
84Tagged messages, only supported in version 2, allow a client to tag a
85message with a positive non-zero integer. The server is then required
86to send a response to the message even if none would normally be
87required, and to tag the response with the same integer. When the
88server receives a tagged message it must send exactly one message back
89with the same tag. The client is allowed to use the same tag for
90multiple messages, even if a response to the first is not received
91before the second it sent. If a tagged message does not normally
92require a response then a "succeeded", "failed", "not-supported" or
93"bad-format" message will be sent back.
94
95An example tagged message and response:
96
9700000010l5:startli8eei15ee
98        ("start", (8), 15)
9900000011l8:succeeded0:i15ee
100        ("succeeded", "", 15)
101
102Some example sessions, including version handshake, are found at the
103end of this file.
104
105Dictionary keys are encoded in UTF-8 and case sensitive. Any character
106except a NUL (0x00) is valid. A server or client need not support
107every possible key and should silently ignore any that it does not
108understand.
109
110If a reference to a boolean is seen, it should be taken to mean an
111integer with a value of 0 representing false, 1 representing true, and
112any other value undefined.
113
114Individual torrents are identified by a unique integer. This integer
115is only valid for the current connection and may be invalid or refer
116to another torrent in a future connection. If a torrent is closed it's
117ID will never be reused to refer to another torrent for at least the
118duration of the connection. Negative integers or 0 are not valid IDs.
119
120A list of keys and the format of their values follows. Also listed is
121the minimum protocol version that the key may be used with.
122
123
124Key:     "addfiles"
125Version: 1
126Format:  list of strings
127Replies: "succeeded", "failed", "not-supported", "bad-format", "info"
128Example: 8:addfilesl21:/torrents/foo.torrent20:/home/me/bar.torrente
129         "addfiles", ("/torrents/foo.torrent", /home/me/bar.torrent")
130Details: Each string is the absolute path to a torrent metainfo file
131         for the server to add. Note that whether or not the torrent
132         metainfo file is copied (allowing the original to be moved or
133         deleted safely) is implementation dependent and may not
134         currently be known or changed with this protocol.
135
136Key:     "addfile-detailed"
137Version: 2
138Format:  dict
139Replies: "succeeded", "failed", "not-supported", "bad-format", "info"
140Example: 16:addfile-detailedd4:file19:/tor/wooble.torrente
141         "addfile-detailed", {"file": "/tor/wooble.torrent"}
142Details: Dictionary containing information about a torrent for the
143         server to add. Valid keys include:
144           "file"       string, filename of torrent metainfo file
145           "data"       string, contents of a torrent metainfo file
146           "directory"  string, directory for data files for the torrent
147           "autostart"  boolean, start the torrent automatically
148         Either "file" or "data" is required, but both are not allowed.
149
150Key:     "automap"
151Version: 2
152Format:  boolean
153Replies: "succeeded", "failed", "not-supported", "bad-format"
154Example: 7:automapi1e
155         "automap", 1
156Details: Enable (1) or disable (0) automatic port mapping on the server.
157
158Key:     "autostart"
159Version: 2
160Format:  boolean
161Replies: "succeeded", "failed", "not-supported", "bad-format"
162Example: 9:autostarti0e
163         "autostart", 0
164Details: Enable (1) or disable (0) automatic starting of new torrents
165         added via "addfiles" or "addfiles-detailed" messages.
166
167Key:     "bad-format"
168Version: 2
169Format:  value is ignored
170Replies: N/A
171Example: 10:bad-format0:
172         "bad-format", ""
173Details: Sent in response to a tagged message which was structured
174         incorrectly. For example, an "autostart" message with a
175         string value might cause this message to be returned.
176
177Key:     "directory"
178Version: 2
179Format:  string
180Replies: "succeeded", "failed", "not-supported", "bad-format"
181Example: 9:directory21:/home/roger/downloads
182         "directory", "/home/roger/downloads"
183Details: Set the default directory used for any torrents added in the future.
184
185Key:     "downlimit"
186Version: 2
187Format:  int
188Replies: "succeeded", "failed", "not-supported", "bad-format"
189Example: 9:downlimiti100e
190         "downlimit", 100
191Details: Set the server's download limit in kilobytes per second.
192         Negative values are interpreted as no limit.
193
194Key:     "encryption"
195Version: 2
196Format:  string
197Replies: "succeeded", "failed", "not-supported", "bad-format"
198Example: 10:encryption8:required
199         "encryption", "required"
200Details: Set the encryption mode for peer connections. Valid values
201         are "required", "preferred" and "plaintext".
202
203Key:     "failed"
204Version: 2
205Format:  string
206Replies: N/A
207Example: 6:failed17:permission denied
208         "failed", "permission denied"
209Details: Sent in response to a tagged message to indicate failure.
210
211Key:     "get-automap"
212Version: 2
213Format:  value is ignored
214Replies: "failed", "not-supported", "bad-format", "automap"
215Example: 11:get-automap0:
216         "get-automap", ""
217Details: Requests that an "automap" message be sent back.
218
219Key:     "get-autostart"
220Version: 2
221Format:  value is ignored
222Replies: "failed", "not-supported", "bad-format", "autostart"
223Example: 13:get-autostart0:
224         "get-autostart", ""
225Details: Requests that an "autostart" message be sent back.
226
227Key:     "get-directory"
228Version: 2
229Format:  value is ignored
230Replies: "failed", "not-supported", "bad-format", "directory"
231Example: 13:get-directory0:
232         "get-directory", ""
233Details: Requests that an "directory" message be sent back.
234
235Key:     "get-downlimit"
236Version: 2
237Format:  value is ignored
238Replies: "failed", "not-supported", "bad-format", "downlimit"
239Example: 13:get-downlimit0:
240         "get-downlimit", ""
241Details: Requests that a "downlimit" message be sent back.
242
243Key:     "get-encryption"
244Version: 2
245Format:  value is ignored
246Replies: "failed", "not-supported", "bad-format", "encryption"
247Example: 14:get-encryption0:
248         "get-encryption", ""
249Details: Requests that an "encryption" message be sent back.
250
251Key:     "get-info"
252Version: 2
253Format:  dict with keys "id" and "type" for lists of ints and strings
254Replies: "failed", "not-supported", "bad-format", "info"
255Example: 8:get-infod2:idli4ei7ei2ee4:typel4:hash4:nameee
256         "get-info", {"id": (4, 7, 2), "type": ("hash", "name")}
257Details: Requests that the server send back an "info" message with
258         info on all the torrent IDs in "id". The "type" key requests
259         what info will be returned. See below for valid values to use
260         here. Since the torrent ID is always included in an "info"
261         message an empty or missing "type" key will cause only the ID
262         to be returned. An "info" message will always be sent back,
263         even if it is empty.
264
265Key:     "get-info-all"
266Version: 2
267Format:  list of strings
268Replies: "failed", "not-supported", "bad-format", "info"
269Example: 12:get-info-alll4:hash4:namee
270         "get-info-all", ("hash", "name")
271Details: Same as "getinfo" message with all torrent IDs specified.
272
273Key:     "get-pex"
274Version: 2
275Format:  value is ignored
276Replies: "failed", "not-supported", "bad-format", "pex"
277Example: 7:get-pex0:
278         "get-pex", ""
279Details: Requests that a "pex" message be sent back.
280
281Key:     "get-port"
282Version: 2
283Format:  value is ignored
284Replies: "failed", "not-supported", "bad-format", "port"
285Example: 8:get-port0:
286         "get-port", ""
287Details: Requests that a "port" message be sent back.
288
289Key:     "get-status"
290Version: 2
291Format:  dict with keys "id" and "type" for lists of ints and strings
292Replies: "failed", "not-supported", "bad-format", "status"
293Example: 10:get-statusd2:idli4ei7ei2ee4:typel5:state9:completedee
294         "get-status", {"id": (4, 7, 4), "type": ("state", "completed")}
295Details: Same as "get-info" message except status type strings are used
296         instead and the server sends back a "status" message.
297
298Key:     "get-status-all"
299Version: 2
300Format:  list of strings
301Replies: "failed", "not-supported", "bad-format", "status"
302Example: 14:get-status-alll5:state9:completede
303         "get-status-all", ("state", "completed")
304Details: Same as "get-status" message with all torrent IDs specified.
305
306Key:     "get-supported"
307Version: 2
308Format:  list of strings
309Replies: "failed", "not-supported", "bad-format", "supported"
310Example: 13:get-supportedl6:lookup8:get-port16:addfile-detailede
311         "get-supported", ("lookup", "get-port", "addfile-detailed")
312Details: Request that a "supported" message be returned with whichever
313         of the given message keys are supported.
314
315Key:     "get-uplimit"
316Version: 2
317Format:  value is ignored
318Replies: "failed", "not-supported", "bad-format", "uplimit"
319Example: 11:get-uplimit0:
320         "get-uplimit", ""
321Details: Requests that an "uplimit" message be sent back.
322
323Key:     "lookup"
324Version: 2
325Format:  list of strings
326Replies: "failed", "not-supported", "bad-format", "info"
327Example: 6:lookupl40:0f16ea6965ee5133ea4dbb1e7f516e9fcf3d899ee
328         "lookup", ("0f16ea6965ee5133ea4dbb1e7f516e9fcf3d899e")
329Details: Request that the server send back an "info" message with "id"
330         and "hash" keys for any torrents with the given hashes.
331
332Key:     "info"
333Version: 2
334Format:  list of dictionaries
335Replies: N/A
336Example: 4:infold2:idi3e4:name3:fooed2:idi9e4:name3:baree
337         "info", ({"id": 4, "name": "foo"}, {"id": 9, "name": "bar"})
338Details: A list containing information for several torrents. The
339         dictionaries always contain at least an "id" key with the
340         integer ID for the torrent, other possible values are listed
341         below.
342
343Key:     "noop"
344Version: 2
345Format:  value is ignored
346Replies: "succeeded", "failed", "not-supported", "bad-format"
347Example: 4:noop0:
348         "noop", ""
349Details: This does nothing but keep the connection alive. With a tag
350         it may be used as a ping.
351
352Key:     "not-supported"
353Version: 2
354Format:  value is ignored
355Replies: N/A
356Example: 13:not-supported0:
357         "not-supported", ""
358Details: Sent in response to a tagged message to indicated that the
359         message was not supported.
360
361Key:     "pex"
362Version: 2
363Format:  boolean
364Replies: "succeeded", "failed", "not-supported", "bad-format"
365Example: 3:pexi0e
366         "pex", 0
367Details: Enables or disables peer exchange.
368
369Key:     "port"
370Version: 2
371Format:  int between 0 and 65535
372Replies: "succeeded", "failed", "not-supported", "bad-format"
373Example: 4:porti51413e
374         "port", 51413
375Details: Change the port the server uses to listen for incoming peer
376         connections.
377
378Key:     "quit"
379Version: 1
380Format:  value is ignored
381Replies: "succeeded", "failed", "not-supported", "bad-format"
382Example: 4:quit0:
383         "quit", ""
384Details: Cause the server to quit. Note that the connection might be
385         closed without a response being sent.
386
387Key:     "remove"
388Version: 2
389Format:  list of torrent ID ints
390Replies: "succeeded", "failed", "not-supported", "bad-format"
391Example: 5:removeli3ei8ei6ee
392         "remove", (3, 8, 6)
393Details: Stop and remove the specified torrents. Note that whether or
394         not the downloaded data or the original torrent files will be
395         removed is implementation dependent and may not currently be
396         known or changed with this protocol. If a saved copy of the
397         torrent file has been made then it will always be deleted.
398
399Key:     "remove-all"
400Version: 2
401Format:  value is ignored
402Replies: "succeeded", "failed", "not-supported", "bad-format"
403Example: 10:remove-all0:
404         "remove-all", ""
405Details: Like "remove" with all torrent IDs specified.
406
407Key:     "start"
408Version: 2
409Format:  list of torrent ID ints
410Replies: "succeeded", "failed", "not-supported", "bad-format"
411Example: 5:startli3ei8ei6ee
412         "start", (3, 8, 6)
413Details: List of torrent IDs to start.
414
415Key:     "start-all"
416Version: 2
417Format:  value is ignored
418Replies: "succeeded", "failed", "not-supported", "bad-format"
419Example: 9:start-all0:
420         "start-all", ""
421Details: Start all torrents.
422
423Key:     "status"
424Version: 2
425Format:  list of dictionaries
426Replies: N/A
427Example: 4:infold2:idi3e5:state7:seedinged2:idi9e5:state6:pausedee
428         "info", ({"id": 3, "state": "seeding"}, {"id": 9, "state" : "paused"})
429Details: Same as "info" message except status type keys are used.
430
431Key:     "stop"
432Version: 2
433Format:  list of torrent ID ints
434Replies: "succeeded", "failed", "not-supported", "bad-format"
435Example: 4:stopli3ei8ei6ee
436         "stop", (3, 8, 6)
437Details: List of torrent IDs to stop.
438
439Key:     "stop-all"
440Version: 2
441Format:  value is ignored
442Replies: "succeeded", "failed", "not-supported", "bad-format"
443Example: 8:stop-all0:
444         "stop-all", ""
445Details: Stop all torrents.
446
447Key:     "succeeded"
448Version: 2
449Format:  value is ignored
450Replies: N/A
451Example: 8:succeeded0:
452         "succeeded", ""
453Details: This is used to indicate that a tagged message was processed
454         successfully.
455
456Key:     "supported"
457Version: 2
458Format:  list of strings
459Replies: N/A
460Example: 9:supportedl8:get-port6:lookupe
461         "supported", ("get-port", "lookup")
462Details: Sent in response to a "get-supported" message, indicates that
463         the given messages ate supported.
464
465Key:     "uplimit"
466Version: 2
467Format:  int
468Replies: "succeeded", "failed", "not-supported", "bad-format"
469Example: 7:uplimiti20e
470         "uplimit", 20
471Details: Set the server's upload limit in kilobytes per second.
472         Negative values are interpreted as no limit.
473
474Key:     "verify"
475Version: 2
476Format:  list of torrent ID ints
477Replies: "succeeded", "failed", "not-supported", "bad-format"
478Example: 6:verifyli3ei8ei6ee
479         "verify", (3, 8, 6)
480Details: List of torrent IDs to stop.
481
482
483
484Info types for "get-info" and "info" messages. The only type for which
485support is mandatory is "id".
486
487"id"       integer, torrent's ID for this connection
488"hash"     SHA-1 info hash as a 40-char hex string
489"name"     string, torrent name
490"path"     string, path to .torrent file
491"saved"    boolean, true if a copy of this torrent was saved
492"private"  boolean, true if the torrent is private
493"trackers" a list of lists of dictionaries containing tracker info:
494             "address"  string, hostname or ip address of tracker
495             "port"     integer, port for tracker
496             "announce" string, announce url on tracker
497             "scrape"   string, scrape url on tracker, may be absent
498"comment"  string, comment from torrent file
499"creator"  string, creator of torrent file
500"date"     integer, date of torrent creation (unix time_t format)
501"size"     integer, total size of all files in bytes
502"files"    list of dictionaries for the files in this torrent:
503             "name" string, name of file
504             "size" integer, size of file in bytes
505
506
507Status types for "get-status" and "status" messages. The only type for
508which support is mandatory is "id".
509
510"completed"         integer, bytes of data downloaded and verified
511"download-speed"    integer, download speed in bytes per second
512"download-total"    integer, total bytes downloaded so far
513"error"             string, one of the following:
514                      "assert"          something happened that shouldn't
515                      "io-parent"       missing parent directory
516                      "io-permissions"  filesystem permission error
517                      "io-space"        not enough free space in filesystem
518                      "io-resource"     insufficient resources
519                      "io-other"        other filesystem i/o error
520                      "tracker-error"   tracker returned error message
521                      "tracker-warning" tracker returned warning message
522                      "other"           other error
523                      zero-length or missing string indicates no error
524"error-message"     string, printable error message
525"eta"               integer, estimated seconds until downloading is finished
526"id"                integer, torrent's ID for this connection
527"peers-downloading" integer, peers downloading from us
528"peers-from"        dict with the following int keys, peer connection sources:
529                      "incoming"    peers connected to our listening port
530                      "tracker"     peers discovered from tracker
531                      "cache"       peers retrieved from on-disk cache
532                      "pex"         peers discovered via peer exchange
533"peers-total"       integer, total connected peers
534"peers-uploading"   integer, peers uploading to us
535"running"           boolean, false if torrent is stopped or stopping
536"state"             string, one of the following:
537                      "checking"    performing hash check on file data
538                      "downloading" downloading file data
539                      "seeding"     seeding file data to peers
540                      "stopping"    contacting tracker to send 'stopped' event
541                      "paused"      torrent is not active
542                      "waiting to checking"
543                                    torrent is queued for hash check.
544                                    yes, this it really is called that.
545"swarm-speed"       integer, swarm speed in bytes per second
546"tracker"           dict with the following keys, current active tracker
547                      "address"     string, hostname or ip address of tracker
548                      "port"        integer, port for tracker
549                      "announce"    string, tracker announce url
550                      "scrape"      string, tracker scrape url, may be absent
551"scrape-completed"  integer, total completed peers as reported by tracker
552"scrape-leechers"   integer, current leechers as reported by tracker
553"scrape-seeders"    integer, current, seeders as reported by tracker
554"upload-speed"      integer, upload speed in bytes per second
555"upload-total"      integer, total bytes uploaded so far
556
557
558Examples:
559
560Data from the client to the server is prefixed with >>> and from
561server to client with <<<. These prefixes and newlines are added for
562clarity, they are not actually sent over the socket.
563
564Quit the server. Note that this is a version 1 client and so version 1
565messages are used.
566>>> 0000001Dd7:versiond3:mini1e3:maxi1eee
567            {"version", {"min": 1, "max": 1"}}
568<<< 0000001Dd7:versiond3:mini1e3:maxi2eee
569            {"version", {"min": 1, "max": 2"}}
570>>> 0000000Bd4:quit0:e
571            {"quit": ""}
572
573Pause all torrents and disable automapping. Note the server happens to
574have sent it's version before the client. The value for the stop-all
575message here is 5:fnord instead of 0: as used above, since the value
576is unused anything is allowed.
577<<< 0000001Dd7:versiond3:mini1e3:maxi2eee
578            {"version", {"min": 1, "max": 2"}}
579>>> 0000001Dd7:versiond3:mini1e3:maxi2eee
580            {"version", {"min": 1, "max": 2"}}
581>>> 0000000El8:stop-all5:fnorde
582            ("stop-all", "fnord")
583
584Change upload and download limits with tagged responses.
585>>> 0000001Dd7:versiond3:mini1e3:maxi2eee
586            {"version", {"min": 1, "max": 2"}}
587<<< 0000001Dd7:versiond3:mini1e3:maxi2eee
588            {"version", {"min": 1, "max": 2"}}
589>>> 00000017l9:downlimiti100ei47el
590            ("downlimit", 100, 47)
591>>> 00000017l9:uplimiti20ei48ee
592            ("uplimit", 20, 48)
593<<< 00000014l8:succeeded0:i47ee
594            ("succeeded", "", 47)
595<<< 00000014l8:succeeded0:i48ee
596            (succeeded"", "", 48)
597
598Retrieve the upload and download limits. Note that the server has
599returned the responses in a different order than the requests were
600sent. The server is allowed to do this, a client should use tags if
601this is a concern.
602>>> 0000001Dd7:versiond3:mini1e3:maxi2eee
603            {"version", {"min": 1, "max": 2"}}
604<<< 0000001Dd7:versiond3:mini1e3:maxi2eee
605            {"version", {"min": 1, "max": 2"}}
606>>> 00000015l13:get-downlimiti0ee00000013l13:get-uplimiti0ee
607            ("get-downlimit", 0)
608            ("get-uplimit", 0)
609<<< 0000000Fl9:uplimiti20ee00000012l9:downlimiti100ee
610            ("uplimit", 20)
611            ("downlimit", 100)
Note: See TracBrowser for help on using the repository browser.