NAME

Net::BitTorrent - BitTorrent peer-to-peer protocol class

Synopsis

use Net::BitTorrent;

my $client = Net::BitTorrent->new();

$client->on_event(
    q[piece_hash_pass],
    sub {
        my ($self, $args) = @_;
        printf(qq[pass: piece number %04d of %s\n],
               $args->{q[Index]}, $args->{q[Torrent]}->infohash);
    }
);

my $torrent = $client->add_torrent({Path => q[a.legal.torrent]})
    or die q[Cannot load .torrent];

$torrent->hashcheck;  # Verify any existing data

$client->do_one_loop() while 1;

Description

Net::BitTorrent is a class based implementation of the BitTorrent Protocol for distributed data exchange.

Constructor

new ( { [ARGS] } )

Creates a Net::BitTorrent object. This constructor expects arguments as a hashref, using key-value pairs, all of which are optional. The most common are:

LocalHost

Local host bind address. The value must be an IPv4 ("dotted quad") IP- address of the xxx.xxx.xxx.xxx form.

Default: 0.0.0.0 (any address)

LocalPort

TCP and UDP port opened to remote peers for incoming connections. If handed a list of ports (ex. { LocalPort => [6952, 6881..6889] }), Net::BitTorrent will traverse the list, attempting to open on each of the ports until we succeed or run out of ports.

Default: 0 (any available, chosen by the OS)

Methods

Unless stated, all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns some other specific value, failure will result in undef or an empty list.

peerid ( )

Returns the Peer ID generated to identify this Net::BitTorrent object internally, with remote peers, and trackers.

See also: wiki.theory.org (http://tinyurl.com/4a9cuv), Peer ID Specification

torrents ( )

Returns the list of queued torrents.

add_torrent ( { ... } )

Loads a .torrent file and adds the Net::BitTorrent::Torrent object to the client's queue.

Aside from the Client parameter (which is filled in automatically), this method hands everything off to Net::BitTorrent::Torrent's constructor, so see Net::BitTorrent::Torrent::new( ) for a list of expected parameters.

This method returns the new Net::BitTorrent::Torrent object on success.

remove_torrent ( TORRENT )

Removes a Net::BitTorrent::Torrent object from the client's queue.

do_one_loop ( [TIMEOUT] )

Processes the internal schedule and handles activity of the various socket-containing objects (peers, trackers, DHT). This method should be called frequently to be of any use at all.

The optional TIMEOUT parameter is the maximum amount of time, in seconds, possibly fractional, select() is allowed to wait before returning. This TIMEOUT defaults to 1.0 (one second). To wait indefinitely, TIMEOUT should be -1.0 (...->do_one_loop(-1)).

on_event ( TYPE, CODEREF )

Net::BitTorrent provides a convenient callback system. To set a callback, use the on_event( ) method. For example, to catch all attempts to read from a file, use $client->on_event( 'file_read', \&on_read ).

See the Events section for a list of events sorted by their related classes.

Events

When triggered, callbacks receive two arguments: the Net::BitTorrent object and a hashref containing pertinent information.

This is the current list of events and the information passed to callbacks.

Note: This list is subject to change. Unless mentioned specifically, return values from callbacks do not affect behavior.

Net::BitTorrent::Peer

ip_filter

This gives a client author a chance to block or accept connections with a peer before an initial handshake is sent. The argument hash contains the following key:

Address: IPv4:port address of the potential peer.

Note: The return value from your ip_filter callback determines how we proceed. An explicitly false return value means this peer should not contacted and (in the case of an incoming peer) the connection will be dropped.

peer_connect

Triggered when we have both sent and received a valid handshake with the remote peer. The argument hash contains the following keys:

Peer: The remote peer with whom we have established a connection.

peer_disconnect

Triggered when a connection with a remote peer is lost or terminated. The argument hash contains the following keys:

Peer: The remote peer with whom we have established a connection.
Reason: When possible, this is a 'user friendly' reason for the disconnection.

peer_read

This is triggered whenever we send data to a remote peer via TCP. The argument hash contains the following keys:

Peer: The peer on the receiving end of this data.
Length: The amount of data, in bytes, sent to the remote peer.

peer_write

This is triggered whenever we send data to a remote peer via TCP. The argument hash contains the following keys:

Peer: The peer on the receiving end of this data.
Length: The amount of data, in bytes, sent to the remote peer.

packet_incoming_handshake

Triggered whenever a remote peer has attempted to establish communication and has sent a valid handshake according to the current BitTorrent spec. The argument hash contains the following keys:

Peer: The remote peer sending this data.
Payload: A list, as returned by Net::BitTorrent::Protocol, with these values: [ReservedBytes, Infohash, PeerID].

packet_outgoing_handshake

Triggered whenever we attempt to establish a communication with a remote peer and have sent a valid handshake according to the current BitTorrent spec. The argument hash contains the following keys:

Peer: The remote peer receiving this data.
Payload: A list, as returned by Net::BitTorrent::Protocol, with these values: [ReservedBytes, Infohash, PeerID].

packet_incoming_keepalive

Triggered when a remote peer has sent us a keepalive packet. The argument hash contains the following key:

Peer: The remote peer sending this data.

packet_outgoing_keepalive

Triggered when we send a keepalive packet to a remote peer. The argument hash contains the following key:

Peer: The remote peer receiving this data.

packet_incoming_choke

Triggered when a remote peer has sent us a choke packet. The argument hash contains the following key:

Peer: The remote peer sending this data.

packet_outgoing_choke

Triggered when we send a remote peer a choke packet. The argument hash contains the following key:

Peer: The remote peer receiving this data.

packet_incoming_unchoke

Triggered when a remote peer has sent us an unchoke packet. The argument hash contains the following key:

Peer: The remote peer sending this data.

packet_outgoing_unchoke

Triggered when we send a remote peer an unchoke packet. The argument hash contains the following key:

Peer: The remote peer receiving this data.

packet_incoming_interested

Triggered when a remote peer has sent us a packet indicating an interest in some data we have. The argument hash contains the following key:

Peer: The remote peer sending this data.

packet_outgoing_interested

Triggered when we send a remote peer a packet indicating an interest in some data they have. The argument hash contains the following key:

Peer: The remote peer receiving this data.

packet_incoming_not_interested

Triggered when a remote peer has sent us a packet indicating they are no longer interested. The argument hash contains the following key:

Peer: The remote peer sending this data.

packet_outgoing_not_interested

Triggered when we send a remote peer a packet indicating they are no longer interested. The argument hash contains the following key:

Peer: The remote peer receiving this data.

packet_incoming_have

Triggered when a remote peer has sent us a packet to let us know they have a certain piece available for transmission. The argument hash contains the following keys:

Peer: The remote peer sending this data.
Index: The zero based index of the piece the remote peer is advertising.

packet_outgoing_have

Triggered when we send a remote peer a packet indicating we have a particular piece available for transmission. The argument hash contains the following keys:

Peer: The remote peer receiving this data.
Index: The zero based index of the piece we advertising.

packet_incoming_bitfield

Triggered when a remote peer has sent us a bitfield packet. The argument hash contains the following keys:

Peer: The remote peer sending this data.

packet_outgoing_bitfield

Triggered when we send a remote peer a bitfield packet representing the pieces we have available for transmission. The argument hash contains the following keys:

Peer: The remote peer receiving this data.

packet_incoming_request

Triggered when a remote peer has sent us a packet requesting a sub-piece (or block) of data. The argument hash contains the following keys:

Peer: The remote peer sending this request.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data requested in bytes.

packet_outgoing_request

Triggered when we request a sub-piece (or block) of data from a remote peer. The argument hash contains the following keys:

Peer: The remote peer receiving this request.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data requested in bytes.

packet_incoming_block

Triggered when a remote peer has sent us a packet containing a sub-piece (or block) of data we previously requested from them. The argument hash contains the following keys:

Peer: The remote peer sending this request.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data requested in bytes.

packet_outgoing_block

Triggered when we send a remote peer a packet containing a sub-piece (or block) of data they previously requested. The argument hash contains the following keys:

Peer: The remote peer receiving this request.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data requested in bytes.

packet_incoming_cancel

Triggered when a remote peer has sent us a packet canceling a request they made. The argument hash contains the following keys:

Peer: The remote peer sending this packet.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data originally requested in bytes.

packet_outgoing_cancel

Triggered when we cancel a request made for a certain sub-piece (or block) of data. The argument hash contains the following keys:

Peer: The remote peer on the receiving end of this packet.
Index: The zero-based index of the piece in which this particular block is located.
Offset: The offset, in bytes, from the beginning of the aforementioned piece where the requested data is located.
Length: The amount of data originally requested in bytes.

packet_incoming_extended

Triggered when a remote peer has sends us a packet containing extended protocol data. The argument hash contains the following keys:

Peer: The remote peer sending this packet.
ID: The numeric ID for this packet.
Payload: The data sent as the body of this message.

Please see the official documentation for more: http://bittorrent.org/beps/bep_0010.html

packet_outgoing_extended

Triggered when we send an extended protocol packet to a remote peer. The argument hash contains the following keys:

Peer: The remote peer receiving this packet.
ID: The numeric ID for this packet.
Payload: The data sent as the body of this message.

Please see the official documentation for more: http://bittorrent.org/beps/bep_0010.html

Net::BitTorrent::Torrent::File

file_error

Triggered when we run into an error handling the file in some way. The argument hash contains the following keys:

File: The file object related to this fault.
Message: The error message describing what (may have) gone wrong.

file_open

Triggered every time we open a file represented in a Net::BitTorrent::Torrent object. The argument hash contains the following keys:

File: The file object.
Mode: How the file is opened. To simplify things, Net::BitTorrent currently uses 'r' for read access and 'w' for write.

file_close

Triggered every time we close a file represented in a Net::BitTorrent::Torrent object. The argument hash contains the following keys:

File: The file object.

file_write

Triggered every time we write data to a file.

File: The file object.
Length: The actual amount of data written to the file.

file_read

Triggered every time we read data from a file.

File: The file object related to this fault.
Length: The actual amount of data written to the file.

Net::BitTorrent::Torrent::Tracker::HTTP/Net::BitTorrent::Torrent::Tracker::UDP

Note: The tracker objects passed to these callbacks will either be a Net::BitTorrent::Torrent::Tracker::HTTP or a Net::BitTorrent::Torrent::Tracker::UDP.

tracker_connect

Triggered when we connect to a remote tracker. The argument hash contains the following keys:

Tracker: The tracker object related to this event.
Event: If defined, this describes why we are contacting the tracker. See the BitTorrent specification for more.

Note: This callback is only triggered from TCP trackers, as UDP is 'connection-less.'

tracker_disconnect

Triggered when we disconnect from a remote tracker. The argument hash contains the following key:

Tracker: The tracker object related to this event.

Note: This callback is only triggered from TCP trackers, as UDP is 'connection-less.'

tracker_success

Triggered when an announce attempt succeeds. The argument hash contains the following keys:

Tracker

The tracker object related to this event.

Payload

The data returned by the tracker in a hashref. The content of this payload may vary, but these are the typical keys found therein:

complete: The number of seeds in the swarm according to the tracker.
incomplete: The number of leeches in the swarm according to the tracker.
peers: A compact list of peers in the swarm.
min_interval: The minimum amount of time before we should contact the tracker again.

tracker_failure

Triggered when an announce attempt fails. The argument hash contains the following keys:

Tracker: The tracker object related to this event.
Reason: The reason given by the remote tracker (when applicable) or as defined by Net::BitTorrent on socket errors.

tracker_write

Triggered when we write data to a remote tracker. The argument hash contains the following keys:

Tracker: The tracker object related to this event.
Length: The amount of data sent to the remote tracker.

tracker_read

Triggered when data is read from a tracker. The argument hash contains the following keys:

Tracker: The tracker object related to this event.
Length: The amount of data received from the remote tracker.

Net::BitTorrent::Torrent

piece_hash_fail

Triggered when a piece fails to validate. The argument hash contains the following keys:

Torrent: The Net::BitTorrent::Torrent object related to this event.
Index: The zero-based index of the piece that failed to match the hash defined for it in the .torrent metadata.

piece_hash_pass

Triggered when a previously missing piece validates. The argument hash contains the following keys:

Torrent: The Net::BitTorrent::Torrent object related to this event.
Index: The zero-based index of the piece that was verified against the .torrent metadata.

Bugs

Numerous, I'm sure.

Please see the section entitled "Bug Reporting" in Net::BitTorrent::Notes.

Notes

Support and Availability

Visit the following for support and information related to Net::BitTorrent:

The project's website

For SVN info, please visit the project's home: http://sankorobinson.com/net-bittorrent/.

Bug and Issue Tracker

Use http://code.google.com/p/net-bittorrent/issues/list for bug tracking.

Before sending a report, make sure the bug is reproducible. If the problem requires a specific .torrent file, the issue tracker allows attachments. Make sure you are using the a recent release of Net::BitTorrent. This may mean checking out the latest SVN commit.

See Net::BitTorrent::Notes for links to a mailing list, SVN information, and more.

Dependencies

Net::BitTorrent requires version and Digest::SHA to function and relies upon Module::Build for installation. As of perl 5.10, these are all CORE modules; they come bundled with the distribution.

Development Policy

All APIs are subject to change.

Changes to documented or well established parts will be clearly listed and archived in the CHANGES file.

Functions and parameters that are all_lower_case_and_contain_underscores are typically experimental and have a very good chance of being depreciated in a future version.
All undocumented functionality is subject to change without notice.

Net::BitTorrent is just asploding with incomplete bits of stuff so I reserve the right to change or eliminate code at any time without warning unless functionality is defined in POD documentation.

If you sift through the source and find something nifty that isn't described in full in POD, don't expect your client to work with future releases.

Examples

For a demonstration of Net::BitTorrent, see scripts/bittorrent.pl.

Installation

See Net::BitTorrent::Notes.

Acknowledgments

Bram Cohen, for designing the base protocol and letting the community decide what to do with it.

L Rotger

#bittorrent on Freenode for letting me idle.

Michel Valdrighi for b2

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

	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)