Net::BitTorrent::Protocol - Packet utilities for the BitTorrent protocol
use Net::BitTorrent::Protocol qw[:build parse_packet]; # Tell them what we want... my $handshake = build_handshake( pack('C*', split('', '00000000')), pack('H*', 'ddaa46b1ddbfd3564fca526d1b68420b6cd54201'), 'your-peer-id-in-here' ); # And the inverse... my ($reserved, $infohash, $peerid) = parse_packet( $handshake );
What would BitTorrent be without packets? TCP noise, mostly.
For similar work and links to the specifications behind these packets, move on down to the See Also section.
There are three types of functions exported by this module:
These functions return the BitTorrent
These create packets ready-to-send to remote peers. To import these in one go, use the :build tag.
:build
These are used to parse unknown data into sensable packets. To import these in one go, use the :parse tag.
:parse
build_handshake ( RESERVED, INFOHASH, PEERID )
Creates an initial handshake packet. All parameters must conform to the BitTorrent spec:
RESEREVED
...is the 8 byte string used to represent a client's capabilities for extentions to the protocol.
INFOHASH
...is the 20 byte SHA1 hash of the bencoded info from the metainfo file.
PEERID
...is 20 bytes.
build_keepalive ( )
Creates a keep-alive message. 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 (keep-alive or any other message) for a certain period of time, so a keep-alive message must be sent to maintain the connection alive if no command have been sent for a given amount of time. This amount of time is generally two minutes.
build_choke ( )
Creates a choke message. The choke message is fixed-length and has no payload.
See Also: http://tinyurl.com/NB-docs-choking - Choking and Optimistic Unchoking
build_unchoke ( )
Creates an unchoke message. The unchoke message is fixed-length and has no payload.
build_interested ( )
Creates an interested message. The interested message is fixed-length and has no payload.
build_not_interested ( )
Creates a not interested message. The not interested message is fixed-length and has no payload.
build_have ( INDEX )
Creates a have message. 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.
That is the strict definition, in reality some games may be played. In particular because peers are extremely unlikely to download pieces that they already have, a peer may choose not to advertise having a piece to a peer that already has that piece. At a minimum "HAVE supression" will result in a 50% reduction in the number of HAVE messages, this translates to around a 25-35% reduction in protocol overhead. At the same time, it may be worthwhile to send a HAVE message to a peer that has that piece already since it will be useful in determining which piece is rare.
A malicious peer might also choose to advertise having pieces that it knows the peer will never download. Due to this attempting to model peers using this information is a bad idea.
build_bitfield ( BITFIELD )
Creates a bitfield message. 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.
X
BITFIELD
A 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 or uses one of the Fast Extention packets: have all or have none.
build_request ( INDEX, OFFSET, LENGTH )
Creates a request message. The request message is fixed length, and is used to request a block. The payload contains the following information:
INDEX
...is an integer specifying the zero-based piece index.
OFFSET
...is an integer specifying the zero-based byte offset within the piece.
LENGTH
...is an integer specifying the requested length.
See Also: build_cancel
build_piece ( INDEX, OFFSET, DATA )
Creates a piece message. The piece message is variable length, where X is the length of the DATA. The payload contains the following information:
DATA
...is the block of data, which is a subset of the piece specified by INDEX.
Before sending pieces to remote peers, the client should verify that the piece matches the SHA1 hash related to it in the .torrent metainfo.
build_cancel ( INDEX, OFFSET, LENGTH )
Creates a cancel message. 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 Also: http://tinyurl.com/NB-docs-EndGame - End Game
build_extended ( DATA )
Creates an extended protocol message.
The following messages are either part of the base protocol or one of the common extentions but have either been superceeded or simply removed from the majority of clients. I have provided them here only for legacy support; they will not be removed in the future.
build_port ( PORT )
Creates a port message.
See also: http://bittorrent.org/beps/bep_0003.html - The BitTorrent Protocol Specification
build_allowed_fast ( INDEX )
Creates an Allowed Fast message.
uTorrent never advertises a fast set... why should we?
See also: http://bittorrent.org/beps/bep_0006.html - Fast Extension
build_suggest ( INDEX )
Creates a Suggest Piece message.
Super seeding is not supported by Net::BitTorrent. Yet.
build_reject ( INDEX, OFFSET, LENGTH )
Creates a Reject Request message.
build_have_all ( )
Creates a Have All message.
build_have_none ( )
Creates a Have None message.
Attempts to parse any known packet from the data (a scalar ref) passed to it. On success, the payload and type are returned and the packet is removed from the incoming data ref. undef is returned on failure.
undef
Visit the following for support and information related to Net::BitTorrent:
For links to a mailing list, svn information, and more, visit the project's home: http://sankorobinson.com/net-bittorrent/.
Use http://code.google.com/p/net-bittorrent/issues/list for bug tracking. For more, see the Issue Tracker, Bug Reporting, and Co-Development and Patch Submission sections of Net::BitTorrent::Notes.
http://bittorrent.org/beps/bep_0003.html - The BitTorrent Protocol Specification
http://bittorrent.org/beps/bep_0006.html - Fast Extension
http://bittorrent.org/beps/bep_0010.html - Extension Protocol
http://wiki.theory.org/BitTorrentSpecification - An annotated guide to the BitTorrent protocol
Net::BitTorrent::PeerPacket - by Joshua McAdams
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.
When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.
Neither this module nor the Author is affiliated with BitTorrent, Inc.
To install Net::BitTorrent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::BitTorrent
CPAN shell
perl -MCPAN -e shell install Net::BitTorrent
For more information on module installation, please visit the detailed CPAN module installation guide.