Messages
All of the remaining messages in the protocol take the form of <length prefix><message ID><payload>. The length prefix is a four byte big-endian value. The message ID is a single decimal character. The payload is message dependent.
keep-alive: <len=0000>
The keep-alive message is a message with zero bytes, specified with the length prefix set to zero. There is no message ID and no payload. Peers may close a connection if they receive no messages for a certain period of time, so a keep-alive message can be sent to maintain the connection. A keep-alive message is generally sent once every two minutes.
choke: <len=0001><id=0>
The choke message is fixed-length and has no payload.
unchoke: <len=0001><id=1>
The unchoke message is fixed-length and has no payload.
interested: <len=0001><id=2>
The interested message is fixed-length and has no payload.
not interested: <len=0001><id=3>
The not interested message is fixed-length and has no payload.
have: <len=0005><id=4><piece index>
The have message is fixed length. The payload is the zero-based index of a piece that has just been successfully downloaded and verified via the hash.
bitfield: <len=0001+X><id=5><bitfield>
The bitfield message may only be sent immediately after the handshaking sequence is completed, and before any other messages are sent. It is optional, and need not be sent if a client has no pieces.
The bitfield message is variable length, where X is the length of the bitfield. The payload is a bitfield representing the pieces that have been successfully downloaded. The high bit in the first byte corresponds to piece index 0. Bits that are cleared indicated a missing piece, and set bits indicate a valid and available piece. Spare bits at the end are set to zero.
A bitfield of the wrong length is considered an error. Clients should drop the connection if they receive bitfields that are not of the correct size, or if the bitfield has any of the spare bits set.
request: <len=0013><id=6><index><begin><length>
- The request message is fixed length, and is used to request a block. The payload contains the following information
-
- index: integer specifying the zero-based piece index
- begin: integer specifying the zero-based byte offset within the piece
- length: integer specifying the requested length. This value should normally be 2^14 (16384) bytes. Smaller values may be used but are usually not needed except in rare cases like a piece length not divisible by 16384.
The observant reader will note that a block is typically smaller than a piece (which is commonly >= 2^18 bytes). A client may close the connection if it receives a request for more than 16384 bytes.
piece: <len=0009+X><id=7><index><begin><block>
- The piece message is variable length, where X is the length of the block. The payload contains the following information
-
- index: integer specifying the zero-based piece index
- begin: integer specifying the zero-based byte offset within the piece
- block: block of data, which is a subset of the piece specified by index.
cancel: <len=0013><id=8><index><begin><length>
The cancel message is fixed length, and is used to cancel block requests. The payload is identical to that of the "request" message. It is typically used during "End Game" (see the Algorithms section below).
Algorithms
Super Seeding
(This was not part of the original specification)
The super-seed feature in S-5.5 and on is a new seeding algorithm designed to help a torrent initiator with limited bandwidth "pump up" a large torrent, reducing the amount of data it needs to upload in order to spawn new seeds in the torrent.
