GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::BitTorrent::Protocol(3) User Contributed Perl Documentation Net::BitTorrent::Protocol(3)

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 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
SUGGEST
HAVE_ALL
HAVE_NONE
REJECT
ALLOWED_FAST
EXTPROTOCOL
":build"
These create packets ready-to-send to remote peers. See Building Functions.
":parse"
These are used to parse unknown data into sensible packets.

"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.
"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 handshaking 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.

See Also: build_cancel

"build_piece ( INDEX, OFFSET, DATA )"
Creates a piece packet. The piece packet is variable length, where "X" is the length of the DATA. 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.
"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 packet. The cancel packet is fixed length, and is used to cancel block requests. The payload is identical to that of the request packet. It is typically used during 'End Game.'

See Also: http://tinyurl.com/NB-docs-EndGame - End Game

"build_extended ( DATA )"
Creates an extended protocol packet.

Legacy Packets

The following packets are either part of the base protocol or one of the common extensions but have either been superseded 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 packet.

See also: http://bittorrent.org/beps/bep_0003.html - The BitTorrent Protocol Specification

"build_allowed_fast ( INDEX )"
Creates an Allowed Fast packet.

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 packet.

Super seeding is not supported by Net::BitTorrent. Yet.

See also: http://bittorrent.org/beps/bep_0006.html - Fast Extension

"build_reject ( INDEX, OFFSET, LENGTH )"
Creates a Reject Request packet.

See also: http://bittorrent.org/beps/bep_0006.html - Fast Extension

"build_have_all ( )"
Creates a Have All packet.

See also: http://bittorrent.org/beps/bep_0006.html - Fast Extension

"build_have_none ( )"
Creates a Have None packet.

See also: http://bittorrent.org/beps/bep_0006.html - Fast Extension

"parse_packet( DATA )"
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.

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-2009 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.

2022-04-09 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.