NAME

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

SYNOPSIS

    use Net::BitTorrent;

    sub hash_pass {
        my ( $self, $piece ) = @_;
        printf( qq[on_hash_pass: piece number %04d of %s\n],
                $piece->index, $piece->session );
    }

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

    $client->set_callback_on_piece_hash_pass( \&hash_pass );

    # ...
    # set various callbacks if you so desire
    # ...

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

    while (1) {
        $client->do_one_loop();

        # Etc.
    }

DESCRIPTION

Net::BitTorrent is a class based implementation of the current BitTorrent Protocol Specification. Each Net::BitTorrent object is capable of handling several concurrent .torrent sessions.

CONSTRUCTOR

new ( { [ARGS] } )

Creates a Net::BitTorrent object. new ( ) accepts arguments as a hash, using key-value pairs, all of which are optional. The most common are:

LocalAddr

Local host bind address. The value must be an IPv4 ("dotted quad") IP-address of the xx.xx.xx.xx form. Unlike the LocalAddr key used by IO::Socket::INET, it does not (currently) support an embedded port number. LocalHost is a synonym for LocalAddr.

Default: 0.0.0.0 (any address)

LocalPort

TCP port opened to remote peers for incoming connections. If handed a list of ports, Net::BitTorrent will traverse the list, attempting to open on each of the ports until we succeed. If this value is undef or 0, we allow the OS to choose an open port at random.

Though the default in most clients is a random port in the 6881-6889 range, BitTorrent has not been assigned a port number or range by the IANA. Nor is such a standard needed.

Default: 0 (any avalible)

Timeout

The maximum amount of time, in seconds, possibly fractional, select() is allowed to wait before returning in "do_one_loop".

Default: 5.0

Besides these, there are a number of advanced options that can be set via the constructor. Use these with caution as they can greatly affect the basic functionality and usefullness of the module.

maximum_buffer_size

Amount of data, in bytes, we store from a peer before dropping their connection. Setting this too high leaves you open to DDoS-like attacks. Malicious or not.

Default: 131072 (2**17) (This default may change as the module matures)

maximum_peers_per_client

Maximum number of peers per client object.

Default: 300 (This default may change as the module matures)

maximum_peers_per_session

Maximum number of peers per session.

Default: 100 (This default may change as the module matures)

maximum_peers_half_open

Maximum number of sockets we have yet to receive a handshake from.

NOTE: On some OSes (WinXP, et al.), setting this too high can cause problems with the TCP stack.

Default: 8

maximum_requests_per_peer

Maximum number of requested blocks we keep in queue with each peer.

Default: 10

METHODS

Unless otherwise 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 a value, failure will result in undef or an empty list.

Besides these listed here, there are several set_callback[...] methods described in the "CALLBACKS" section.

add_session ( { ... } )

Loads a .torrent file and adds the new Net::BitTorrent::Session object to the client.

Most arguments passed to this method are handed directly to Net::BitTorrent::Session::new( ). The only mandatory parameter is path. path's value is the filename of the .torrent file to load. Please see Net::BitTorrent::Session::new( ) for a list of possible parameters.

In addition to Net::BitTorrent::Session::new( )'s supported arguments, add_session accepts a skip_hashcheck key. If this bool value is set to a true value, the files will not be checked for integrity and we assume that we have none of the data of this torrent.

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

as_string ( [ VERBOSE ] )

Returns a 'ready to print' dump of the Net::BitTorrent object's data structure. If called in void context, the structure is printed to STDERR.

Note: The serialized version returned by this method is not a full, accurate representation of the object and cannot be evaled into a new Net::BitTorrent object or used as resume data. The layout of and the data included in this dump is subject to change in future versions. This is a debugging method, not to be used under normal circumstances.

CALLBACKS

Net::BitTorrent provides a convenient callback system. To set a callback, use the equivalent set_callback_on_[action] method. For example, to catch all attempts to read from a file, use $client->set_callback_on_file_read(\&on_read).

Here is the current list of events fired by Net::BitTorrent and related classes as well as a brief description (soon) of them:

Peer level

Peer level events are triggered by Net::BitTorrent::Peer objects.

set_callback_on_peer_connect ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_disconnect ( CODEREF ): Callback arguments: ( CLIENT, PEER, [REASON] )
set_callback_on_peer_incoming_bitfield ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_block ( CODEREF ): Callback arguments: ( CLIENT, PEER, BLOCK )
set_callback_on_peer_incoming_cancel ( CODEREF ): Callback arguments: ( CLIENT, PEER, REQUEST )
set_callback_on_peer_incoming_choke ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_data ( CODEREF ): Callback arguments: ( CLIENT, PEER, LENGTH )
set_callback_on_peer_incoming_disinterested ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_handshake ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_have ( CODEREF ): Callback arguments: ( CLIENT, PEER, INDEX )
set_callback_on_peer_incoming_interested ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_keepalive ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_incoming_packet ( CODEREF ): Callback arguments: ( CLIENT, PEER, PACKET )
set_callback_on_peer_incoming_request ( CODEREF ): Callback arguments: ( CLIENT, PEER, REQUEST )
set_callback_on_peer_incoming_unchoke ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_bitfield ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_block ( CODEREF ): Callback arguments: ( CLIENT, PEER, REQUEST )
set_callback_on_peer_outgoing_cancel ( CODEREF ): Callback arguments: ( CLIENT, PEER, BLOCK )
set_callback_on_peer_outgoing_choke ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_data ( CODEREF ): Callback arguments: ( CLIENT, PEER, LENGTH )
set_callback_on_peer_outgoing_disinterested ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_handshake ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_have ( CODEREF ): Callback arguments: ( CLIENT, PEER, INDEX )
set_callback_on_peer_outgoing_interested ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_keepalive ( CODEREF ): Callback arguments: ( CLIENT, PEER )
set_callback_on_peer_outgoing_request ( CODEREF ): Callback arguments: ( CLIENT, PEER, BLOCK )
set_callback_on_peer_outgoing_unchoke ( CODEREF ): Callback arguments: ( CLIENT, PEER )

Tracker level

Peer level events are triggered by Net::BitTorrent::Tracker objects.

set_callback_on_tracker_announce ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )
set_callback_on_tracker_announce_okay ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )
set_callback_on_tracker_connect ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )
set_callback_on_tracker_disconnect ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )
set_callback_on_tracker_error ( CODEREF ): Callback arguments: ( CLIENT, TRACKER, MESSAGE )
set_callback_on_tracker_incoming_data ( CODEREF ): Callback arguments: ( CLIENT, TRACKER, LENGTH )
set_callback_on_tracker_outgoing_data ( CODEREF ): Callback arguments: ( CLIENT, TRACKER, LENGTH )
set_callback_on_tracker_scrape ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )
set_callback_on_tracker_scrape_okay ( CODEREF ): Callback arguments: ( CLIENT, TRACKER )

File level

File level events are triggered by Net::BitTorrent::Session::File objects.

set_callback_on_file_close ( CODEREF ): Callback arguments: ( CLIENT, FILE )
set_callback_on_file_error ( CODEREF ): Callback arguments: ( CLIENT, FILE, [REASON] )
set_callback_on_file_open ( CODEREF ): Callback arguments: ( CLIENT, FILE )
set_callback_on_file_read ( CODEREF ): Callback arguments: ( CLIENT, FILE, LENGTH )
set_callback_on_file_write ( CODEREF ): Callback arguments: ( CLIENT, FILE, LENGTH )

Piece level

Peer level events are triggered by Net::BitTorrent::Session::Piece objects.

set_callback_on_piece_hash_fail ( CODEREF ): Callback arguments: ( CLIENT, PIECE )
set_callback_on_piece_hash_pass ( CODEREF ): Callback arguments: ( CLIENT, PIECE )

Block level

Block level events are triggered by Net::BitTorrent::Session::Piece::Block objects.

set_callback_on_block_write ( CODEREF ): Callback arguments: ( CLIENT, BLOCK )

Debug level

Debug level callbacks can be from anywhere and are not object specific.

set_callback_on_log ( CODEREF )

Callback arguments: ( CLIENT, LEVEL, STRING )

IMPLEMENTED EXTENTIONS

Um, none yet. Fast Peers soon.

BUGS

Numerous, I'm sure. If you find one not listed in the Todo file included with this distribution, please report it.

List of know bugs:

Socket handling is most likely wonky.
Large files are probably mismanaged. If someone has the time, try dl'ing something huge (Fedora's DVD iso?) and let me know how it goes.
Callback system is incomplete.
Unicode filenames are un(der)tested and may not work properly. See perlunifaq. Don't blame me.

Okay, blame me...
Documentation is incomplete.
Test suite is incomplete.
This list of bugs is incomplete.

NOTES

Availability and Support

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

The project's website: For wiki and subversion repository access, please visit the project's home: http://net-bittorrent.googlecode.com/.
Bug and Issue Tracker: Use http://code.google.com/p/net-bittorrent/issues/list for bug tracking. Please include as much information as possible.

See Net::BitTorrent::FAQ for links to a mailing list, svn information, and more.

Dependencies

Net::BitTorrent requires version, and Digest::SHA. As of perl 5.10, these are 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.
All undocumented functionality is subject to change without notice.

Because it's still early in its development, Net::BitTorrent is filled with incomplete bits of stuff. I understand some of it seems stable, but 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 code to work with future releases.

Examples

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

Installation

This distribution uses Module::Build for installation, so use the following procedure:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't require the "./" notation, you can do this:

  perl Build.PL
  Build
  Build test
  Build install

If you would like to contribute automated test reports (and I hope you do), first install CPAN::Reporter from the CPAN shell and then install Net::BitTorrent:

 $ cpan
 cpan> install CPAN::Reporter
 cpan> reload cpan
 cpan> o conf init test_report
   [...follow the CPAN::Reporter setup prompts...]
 cpan> o conf commit
 cpan> install Net::BitTorrent

For more on becoming a CPAN tester and why this is useful, please see the CPAN::Reporter documentation, http://cpantesters.perl.org/, and the CPAN Testers Wiki (http://cpantest.grango.org/).

ACKNOWLEDGEMENTS

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

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 same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html or the LICENSE file included with this module.

All POD documentation is covered by the Creative Commons Attribution-Noncommercial-Share Alike 3.0 License (http://creativecommons.org/licenses/by-nc-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)