| 1 | It is assumed the reader is familiar with bencoding, as described in |
|---|
| 2 | the BitTorrent protocol specification at |
|---|
| 3 | http://www.bittorrent.org/protocol.html |
|---|
| 4 | |
|---|
| 5 | Dictionary keys used below will be enclosed in quotation marks, these |
|---|
| 6 | are used for clarity and are not part of the actual key. |
|---|
| 7 | |
|---|
| 8 | The IPC protocol is used to allow processes to control or retrieve |
|---|
| 9 | information from a Transmission frontend, such as transmission-daemon |
|---|
| 10 | or transmission-gtk. This communication is done over a unix-domain |
|---|
| 11 | socket file, such as ~/.transmission/daemon/socket. In this document |
|---|
| 12 | the Transmission frontend will be referred to as the server and the |
|---|
| 13 | process connecting to it as the client. |
|---|
| 14 | |
|---|
| 15 | Once a client connects to the server's socket, messages may be |
|---|
| 16 | exchanged until either end closes the connection. Messages contain an |
|---|
| 17 | 32-bit payload length, encoded as 8 bytes of ASCII hexidecimal, |
|---|
| 18 | followed by the payload. Upper, lower, or mixed case for the length |
|---|
| 19 | are all accpetable and must be handled correctly. Payload lengths |
|---|
| 20 | greater than 2^31 - 8 (ie: 2147483640) are not allowed. |
|---|
| 21 | |
|---|
| 22 | For version 1, the message payload is a bencoded dictionary, the |
|---|
| 23 | valid keys and value formats for which are described below. Multiple |
|---|
| 24 | keys may be used in one message. |
|---|
| 25 | |
|---|
| 26 | An example version 1 message: |
|---|
| 27 | |
|---|
| 28 | 0000000Ed4:porti9090ee |
|---|
| 29 | |
|---|
| 30 | For version 2 the message payload is a bencoded list containing a |
|---|
| 31 | message id string followed by a bencoded value, the format of which is |
|---|
| 32 | the same for version 1. The value may be followed by an optional |
|---|
| 33 | bencoded integer, this is a message tag and is described in more |
|---|
| 34 | detail below. |
|---|
| 35 | |
|---|
| 36 | An example version 2 message: |
|---|
| 37 | |
|---|
| 38 | 0000001El12:get-info-alll4:hashee |
|---|
| 39 | |
|---|
| 40 | The same message with a tag: |
|---|
| 41 | |
|---|
| 42 | 00000021l12:get-info-alll4:hashei5ee |
|---|
| 43 | |
|---|
| 44 | Once the connection is made both the client and server must send a |
|---|
| 45 | version 1 style message (ie: the payload is a dictionary and may not |
|---|
| 46 | contain a tag) with the dictionary key "version" and a value formatted |
|---|
| 47 | as described below. The version should be the first but not |
|---|
| 48 | necessarily only key in the dictionary. Any other keys should be |
|---|
| 49 | ignored and not processed as messages. |
|---|
| 50 | |
|---|
| 51 | The version value should be a bencoded dictionary containing two keys, |
|---|
| 52 | "max" and "min". These are the minimum and maximum supported protocol |
|---|
| 53 | versions, respectively. Communication will take place using the |
|---|
| 54 | highest protocol version supported by both the client and the server, |
|---|
| 55 | and is not possible at all if there is no common version. A client may |
|---|
| 56 | receive a version value that is an integer instead of a dictionary |
|---|
| 57 | with "min" and "max" keys. This deprecated version format indicates |
|---|
| 58 | the only version supported by the server. |
|---|
| 59 | |
|---|
| 60 | An example message containing minimum and maximum versions 1 and 2: |
|---|
| 61 | |
|---|
| 62 | 0000001Dd7:versiond3:mini1e3:maxi2eee |
|---|
| 63 | |
|---|
| 64 | Tagged messages, only supported in version 2, allow a client to tag a |
|---|
| 65 | message with a positive non-zero integer. The server is then required |
|---|
| 66 | to send a response to the message even if none would normally be |
|---|
| 67 | required, and to tag the response with the same integer. When the |
|---|
| 68 | server receives a tagged message it must send exactly one message back |
|---|
| 69 | with the same tag. The client is allowed to use the same tag for |
|---|
| 70 | multiple messages, even if a response to the first is not received |
|---|
| 71 | before the second it sent. If a tagged message does not normally |
|---|
| 72 | require a response then a "succeeded", "failed" or "not-supported" |
|---|
| 73 | message will be sent back. |
|---|
| 74 | |
|---|
| 75 | An example tagged message and response: |
|---|
| 76 | |
|---|
| 77 | 00000010l5:startli8eei15ee |
|---|
| 78 | 00000011l8:succeeded0:i15ee |
|---|
| 79 | |
|---|
| 80 | Dictionary keys are encoded in UTF-8 and case sensitive. Any character |
|---|
| 81 | except a NUL (0x00) is valid. A server or client need not support |
|---|
| 82 | every possible key and should silently ignore any that it does not |
|---|
| 83 | understand. |
|---|
| 84 | |
|---|
| 85 | A list of keys and the format of their values follows. Also listed is |
|---|
| 86 | the minimum protocol version that the key may be used with. |
|---|
| 87 | |
|---|
| 88 | |
|---|
| 89 | Key: "addfiles" |
|---|
| 90 | Version: 1 |
|---|
| 91 | Format: list of strings |
|---|
| 92 | Example: 8:addfilesl21:/torrents/foo.torrent20:/home/me/bar.torrente |
|---|
| 93 | Details: 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. |
|---|
| 98 | |
|---|
| 99 | Key: "automap" |
|---|
| 100 | Version: 2 |
|---|
| 101 | Format: int, 0 or 1 |
|---|
| 102 | Example: 7:automapi1e |
|---|
| 103 | Details: 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. |
|---|
| 106 | |
|---|
| 107 | Key: "autostart" |
|---|
| 108 | Version: 2 |
|---|
| 109 | Format: int, 0 or 1 |
|---|
| 110 | Example: 9:autostarti0e |
|---|
| 111 | Details: Enable (1) or disable (0) automatic starting of new torrents |
|---|
| 112 | added via "addfiles" message. |
|---|
| 113 | |
|---|
| 114 | Key: "directory" |
|---|
| 115 | Version: 2 |
|---|
| 116 | Format: string |
|---|
| 117 | Example: 9:directory21:/home/roger/downloads |
|---|
| 118 | Details: Set the default directory used for any torrents added in the future. |
|---|
| 119 | |
|---|
| 120 | Key: "downlimit" |
|---|
| 121 | Version: 2 |
|---|
| 122 | Format: int |
|---|
| 123 | Example: 9:downlimiti100e |
|---|
| 124 | Details: Set the server's download limit in kilobytes per second. |
|---|
| 125 | Negative values are interpreted as no limit. |
|---|
| 126 | |
|---|
| 127 | Key: "failed" |
|---|
| 128 | Version: 2 |
|---|
| 129 | Format: string |
|---|
| 130 | Example: 6:failed17:permission denied |
|---|
| 131 | Details: Sent in response to a tagged message to indicate failure. |
|---|
| 132 | |
|---|
| 133 | Key: "get-automap" |
|---|
| 134 | Version: 2 |
|---|
| 135 | Format: value is ignored |
|---|
| 136 | Example: 11:get-automap0: |
|---|
| 137 | Details: Requests that an "automap" message be sent back. |
|---|
| 138 | |
|---|
| 139 | Key: "get-autostart" |
|---|
| 140 | Version: 2 |
|---|
| 141 | Format: value is ignored |
|---|
| 142 | Example: 13:get-autostart0: |
|---|
| 143 | Details: Requests that an "autostart" message be sent back. |
|---|
| 144 | |
|---|
| 145 | Key: "get-directory" |
|---|
| 146 | Version: 2 |
|---|
| 147 | Format: value is ignored |
|---|
| 148 | Example: 13:get-directory |
|---|
| 149 | Details: Requests that an "directory" message be sent back. |
|---|
| 150 | |
|---|
| 151 | Key: "get-downlimit" |
|---|
| 152 | Version: 2 |
|---|
| 153 | Format: value is ignored |
|---|
| 154 | Example: 13:get-downlimit0: |
|---|
| 155 | Details: Requests that a "downlimit" message be sent back. |
|---|
| 156 | |
|---|
| 157 | Key: "get-info" |
|---|
| 158 | Version: 2 |
|---|
| 159 | Format: dict with keys "id" and "type" for lists of ints and strings |
|---|
| 160 | Example: 8:get-infod2:idli4ei7ei2ee4:typel4:hash4:nameee |
|---|
| 161 | Details: 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. |
|---|
| 168 | |
|---|
| 169 | Key: "get-info-all" |
|---|
| 170 | Version: 2 |
|---|
| 171 | Format: list of strings |
|---|
| 172 | Example: 12:get-info-alll4:hash4:namee |
|---|
| 173 | Details: Same as "getinfo" message with all torrent IDs specified. |
|---|
| 174 | |
|---|
| 175 | Key: "get-port" |
|---|
| 176 | Version: 2 |
|---|
| 177 | Format: value is ignored |
|---|
| 178 | Example: 8:get-port0: |
|---|
| 179 | Details: Requests that a "port" message be sent back. |
|---|
| 180 | |
|---|
| 181 | Key: "get-status" |
|---|
| 182 | Version: 2 |
|---|
| 183 | Format: dict with keys "id" and "type" for lists of ints and strings |
|---|
| 184 | Example: 10:get-statusd2:idli4ei7ei2ee4:typel4:hash4:nameee |
|---|
| 185 | Details: Same as "get-info" message except status type strings are used |
|---|
| 186 | instead and the server sends back a "status" message. |
|---|
| 187 | |
|---|
| 188 | Key: "get-status-all" |
|---|
| 189 | Version: 2 |
|---|
| 190 | Format: list of strings |
|---|
| 191 | Example: 14:get-status-alll4:hash4:namee |
|---|
| 192 | Details: Same as "get-status" message with all torrent IDs specified. |
|---|
| 193 | |
|---|
| 194 | Key: "get-supported" |
|---|
| 195 | Version: 2 |
|---|
| 196 | Format: list of strings |
|---|
| 197 | Example: 13:get-supportedl6:lookup8:get-porte |
|---|
| 198 | Details: Request that a "supported" message be returned with whichever |
|---|
| 199 | of the given message keys are supported. |
|---|
| 200 | |
|---|
| 201 | Key: "get-uplimit" |
|---|
| 202 | Version: 2 |
|---|
| 203 | Format: value is ignored |
|---|
| 204 | Example: 11:get-uplimit0: |
|---|
| 205 | Details: Requests that an "uplimit" message be sent back. |
|---|
| 206 | |
|---|
| 207 | Key: "lookup" |
|---|
| 208 | Version: 2 |
|---|
| 209 | Format: list of strings |
|---|
| 210 | Example: 6:lookupl40:0f16ea6965ee5133ea4dbb1e7f516e9fcf3d899ee |
|---|
| 211 | Details: Request that the server send back an "info" message with "id" |
|---|
| 212 | and "hash" keys for any torrents with the given hashes. |
|---|
| 213 | |
|---|
| 214 | Key: "info" |
|---|
| 215 | Version: 2 |
|---|
| 216 | Format: list of dictionaries |
|---|
| 217 | Example: 4:infold2:idi3e4:name3:fooed2:idi9e4:name3:baree |
|---|
| 218 | Details: 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. |
|---|
| 222 | |
|---|
| 223 | Key: "noop" |
|---|
| 224 | Version: 2 |
|---|
| 225 | Format: value is ignored |
|---|
| 226 | Example: 4:noop0: |
|---|
| 227 | Details: This does nothing but keep the connection alive. With a tag |
|---|
| 228 | it may be used as a ping. |
|---|
| 229 | |
|---|
| 230 | Key: "not-supported" |
|---|
| 231 | Version: 2 |
|---|
| 232 | Format: value is ignored |
|---|
| 233 | Example: 13:not-supported0: |
|---|
| 234 | Details: Sent in response to a tagged message to indicated that the |
|---|
| 235 | message was not supported. |
|---|
| 236 | |
|---|
| 237 | Key: "port" |
|---|
| 238 | Version: 2 |
|---|
| 239 | Format: int between 0 and 65535 |
|---|
| 240 | Example: 4:porti9090e |
|---|
| 241 | Details: Change the port the server uses to listen for incoming peer |
|---|
| 242 | connections. |
|---|
| 243 | |
|---|
| 244 | Key: "quit" |
|---|
| 245 | Version: 1 |
|---|
| 246 | Format: value is ignored |
|---|
| 247 | Example: 4:quit0: |
|---|
| 248 | Details: Cause the server to quit. |
|---|
| 249 | |
|---|
| 250 | Key: "remove" |
|---|
| 251 | Version: 2 |
|---|
| 252 | Format: list of torrent ID ints |
|---|
| 253 | Example: 5:removeli3ei8ei6ee |
|---|
| 254 | Details: 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. |
|---|
| 259 | |
|---|
| 260 | Key: "remove-all" |
|---|
| 261 | Version: 2 |
|---|
| 262 | Format: value is ignored |
|---|
| 263 | Example: 10:remove-all0: |
|---|
| 264 | Details: Like "remove" with all torrent IDs specified. |
|---|
| 265 | |
|---|
| 266 | Key: "start" |
|---|
| 267 | Version: 2 |
|---|
| 268 | Format: list of torrent ID ints |
|---|
| 269 | Example: 5:startli3ei8ei6ee |
|---|
| 270 | Details: List of torrent IDs to start. |
|---|
| 271 | |
|---|
| 272 | Key: "start-all" |
|---|
| 273 | Version: 2 |
|---|
| 274 | Format: value is ignored |
|---|
| 275 | Example: 9:start-all0: |
|---|
| 276 | Details: Start all torrents. |
|---|
| 277 | |
|---|
| 278 | Key: "status" |
|---|
| 279 | Version: 2 |
|---|
| 280 | Format: list of dictionaries |
|---|
| 281 | Example: 4:infold2:idi3e4:name3:fooed2:idi9e4:name3:baree |
|---|
| 282 | Details: Same as "info" message except status type keys are used. |
|---|
| 283 | |
|---|
| 284 | Key: "stop" |
|---|
| 285 | Version: 2 |
|---|
| 286 | Format: list of torrent ID ints |
|---|
| 287 | Example: 4:stopli3ei8ei6ee |
|---|
| 288 | Details: List of torrent IDs to stop. |
|---|
| 289 | |
|---|
| 290 | Key: "stop-all" |
|---|
| 291 | Version: 2 |
|---|
| 292 | Format: value is ignored |
|---|
| 293 | Example: 8:stop-all0: |
|---|
| 294 | Details: Stop all torrents. |
|---|
| 295 | |
|---|
| 296 | Key: "succeeded" |
|---|
| 297 | Version: 2 |
|---|
| 298 | Format: value is ignored |
|---|
| 299 | Example: 8:succeeded0: |
|---|
| 300 | Details: This is used to indicate that a tagged message was processed |
|---|
| 301 | successfully. |
|---|
| 302 | |
|---|
| 303 | Key: "supported" |
|---|
| 304 | Version: 2 |
|---|
| 305 | Format: list of strings |
|---|
| 306 | Example: 9:supportedl6:lookupe |
|---|
| 307 | Details: Sent in response to a "get-supported" message, indicates that |
|---|
| 308 | the given messages ate supported. |
|---|
| 309 | |
|---|
| 310 | Key: "uplimit" |
|---|
| 311 | Version: 2 |
|---|
| 312 | Format: int |
|---|
| 313 | Example: 7:uplimiti20e |
|---|
| 314 | Details: Set the server's upload limit in kilobytes per second. |
|---|
| 315 | Negative values are interpreted as no limit. |
|---|
| 316 | |
|---|
| 317 | Key: "version" |
|---|
| 318 | Version: 1 |
|---|
| 319 | Format: dict containing int "min" and "max" |
|---|
| 320 | Example: 7:versiond3:mini1e3:maxi2ee |
|---|
| 321 | Details: Described above. |
|---|
| 322 | |
|---|
| 323 | |
|---|
| 324 | Individual torrents are identified by a unique integer. This integer |
|---|
| 325 | is only valid for the current connection and may be invalid or refer |
|---|
| 326 | to another torrent in a future connection. If a torrent is closed it's |
|---|
| 327 | ID will never be reused to refer to another torrent for at least the |
|---|
| 328 | duration of the connection. Negative integers or 0 are not valid IDs. |
|---|
| 329 | |
|---|
| 330 | |
|---|
| 331 | Info types for "get-info" and "info" messages. The only type for which |
|---|
| 332 | support is mandatory is "id". |
|---|
| 333 | |
|---|
| 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 |
|---|
| 352 | |
|---|
| 353 | |
|---|
| 354 | Status types for "get-status" and "status" messages. The only type for |
|---|
| 355 | which support is mandatory is "id". |
|---|
| 356 | |
|---|
| 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 |
|---|
