NAME

Net::BitTorrent::Protocol::BEP03 - Packet Utilities for BEP03, the Basic BitTorrent Wire Protocol

Synopsis

use Net::BitTorrent::Protocol::BEP03 qw[:build];

# Tell them what we want...
my $handshake = build_handshake(
    pack('C*', split('', '00000000')),
    pack('H*', 'ddaa46b1ddbfd3564fca526d1b68420b6cd54201'),
    'your-peer-id-in-here'
);

# And the inverse...
use Net::BitTorrent::Protocol::BEP03 qw[:parse];
my ($reserved, $infohash, $peerid) = parse_handshake( $handshake );

Description

What would BitTorrent be without packets? TCP noise, mostly.

For similar work and the specifications behind these packets, move on down to the See Also section.

If you're looking for quick, pure Perl bencode/bdecode functions, you should give Net::BitTorrent::Protocol::BEP03::Bencode a shot.

Importing from Net::BitTorrent::Protocol::BEP03

There are three tags available for import. To get them all in one go, use the :all tag.

:types

Packet types

For more on what these packets actually mean, see the BitTorrent Spec. This is a list of the currently supported packet types:

$HANDSHAKE
$KEEPALIVE
$CHOKE
$UNCHOKE
$INTERESTED
$NOT_INTERESTED
$HAVE
$BITFIELD
$REQUEST
$PIECE
$CANCEL
$PORT

:build

These create packets ready-to-send to remote peers. See Building Functions.

:parse

These are used to parse unknown data into sensible packets. The same packet types we can build, we can also parse. See Parsing Functions.

Building Functions

build_handshake ( $reserved, $infohash, $peerid )

Creates an initial handshake packet. All parameters must conform to the BitTorrent spec:

$reserved: ...is the 8 byte string used to represent a client's capabilities for extensions to the protocol.
$infohash: ...is the 20 byte SHA1 hash of the bencoded info from the metainfo file.
$peerid: ...is 20 bytes. Be creative.

build_keepalive ( )

Creates a keep-alive packet. The keep-alive packet is 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 packets (keep-alive or any other packet) for a certain period of time, so a keep-alive packet 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 packet. The choke packet is fixed-length and has no payload.

See Also: http://tinyurl.com/NB-docs-choking - Choking and Optimistic Unchoking

build_unchoke ( )

Creates an unchoke packet. The unchoke packet is fixed-length and has no payload.

See Also: http://tinyurl.com/NB-docs-choking - Choking and Optimistic Unchoking

build_interested ( )

Creates an interested packet. The interested packet is fixed-length and has no payload.

build_not_interested ( )

Creates a not interested packet. The not interested packet is fixed-length and has no payload.

build_have ( $index )

Creates a have packet. The have packet 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 suppression" will result in a 50% reduction in the number of HAVE packets, this translates to around a 25-35% reduction in protocol overhead. At the same time, it may be worthwhile to send a HAVE packet 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 packet. The bitfield packet 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 packet may only be sent immediately after the handshake sequence is completed, and before any other packets are sent. It is optional, and need not be sent if a client has no pieces or uses one of the Fast Extension packets: have all or have none.

build_request ( $index, $offset, $length )

Creates a request packet. The request packet 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.

Parsing Functions

These are the parsing counterparts for the build_ functions.

When the packet is invalid, a hash reference is returned with the following keys:

error: The value is a string describing what went wrong.
fatal: If parsing the packet is impossible, this is true. For other problems (not enough data, etc.), an untrue value is here.

Return values for valid packets are explained below.

parse_handshake( $data ): Returns an array reference containing the $reserved_bytes, $infohash, and $peerid].
parse_keepalive( $data ): Returns an empty list. Keepalive packets do not contain a playload.
parse_choke( $data ): Returns an empty list. Choke packets do not contain a playload.
parse_unchoke( $data ): Returns an empty list. Unchoke packets do not contain a playload.
parse_interested( $data ): Returns an empty list. Interested packets do not contain a playload.
parse_not_interested( $data ): Returns an empty list. Not interested packets do not contain a playload.
parse_have( $data ): Returns an integer.
parse_bitfield( $data ): Returns the packed bitfield in ascending order. This makes things easy when working with vec(...).
parse_request( $data ): Returns an array reference containing the $index, $offset, and $length.
parse_piece( $data ): Returns an array reference containing teh $index, $offset, and $block.
parse_cancel( $data ): Returns an array reference containing the $index, $offset, and $length.
parse_port( $data ): Returns a single integer containing the listen port a peer's DHT node is listening on.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

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 notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

Neither this module nor the Author is affiliated with BitTorrent, Inc.

To install Net::BitTorrent::Protocol, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::BitTorrent::Protocol

CPAN shell

perl -MCPAN -e shell
install Net::BitTorrent::Protocol

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)