NAME

Net::BitTorrent - BitTorrent client 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 a simple BitTorrent client in Perl as described in the latest BitTorrent Protocol Specification. Each Net::BitTorrent object is capable of handling several concurrent torrent sessions.

OVERVIEW

BitTorrent is a free speech tool.

CONSTRUCTOR

new ( [PARAMETERS] )

This is the constructor for a new Net::BitTorrent object.

PARAMETERS are passed as a hash, using key and value pairs, all of which are optional. Possible options are:

LocalAddr - Local host bind address. The value must be a IPv4 ("dotted quad") IP-address of the xx.xx.xx.xx form. This parameter is only useful on multihomed hosts.

Note: this differs from the LocalAddr key used by IO::Socket::INET

LocalPort - TCP port (or range if passed in array context) opened to remote peers for incoming connections. If handed a range of numbers, 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.

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

Timeout - The maximum amount of time select() is allowed to wait before returning, in seconds, possibly fractional. (Defaults to 5.0)

If the constructor fails, undef will be returned and the value of $! and $^E should be checked.

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 be returned as undef or an empty list.

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

do_one_loop ( )

Processes the various socket-containing objects held by this Net::BitTorrent object. This method should be called frequently.

See Also: "timeout ( [TIMEOUT] )" method to set the timeout interval used by this method's select call.

timeout ( [TIMEOUT] )

Gets or sets the timeout value used by the "do_one_loop ( )" method. The default timeout is 5 seconds.

sessions ( )

Returns a list of all (if any) loaded Net::BitTorrent::Session objects.

add_session ( { ... } )

Loads a .torrent file and starts a new BitTorrent session.

Parameters passed to this method are handed directly to Net::BitTorrent::Session::new(), so see the Net::BitTorrent::Session documentation for a list of required and optional parameters.

This method returns undef on failure or a new Net::BitTorrent::Session object on success.

remove_session ( SESSION )

Removes a Net::BitTorrent::Session object from the client.

Before the torrent session is closed, we announce to the tracker that we have 'stopped' downloading and the callback to store the current state is called.

peer_id ( )

Retrieve the peer_id generated for this Net::BitTorrent object.

CALLBACKS

Net::BitTorrent provides a convenient callback system for client developers. 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_packet ( CODEREF ): Callback arguments: ( CLIENT, PEER, PACKET )
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, MESSAGE )
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: ( BLOCK )

Debug level

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

set_callback_on_log ( CODEREF ): Callback arguments: ( CLIENT, STRING )

CAVEATS

...none yet.

BUGS/TODO

Numerous. 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 not well managed. 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 [perldoc://perlunifaq]. Don't blame me.

Okay, blame me...
Documentation is incomplete.
A more complete test suite needs to be written to test the small things just in case.

NOTES

INSTALLATION

The current distribution uses the CORE ExtUtils::MakeMaker module, so the standard procedure will suffice:

perl Makefile.PL
make
make test
make 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://CPAN::Reporter] documentation, [http://cpantesters.perl.org/], and the CPAN Testers Wiki ([http://cpantest.grango.org/]).

DEPENDENCIES

Net::BitTorrent requires [cpan://version], and [cpan://Digest::SHA]. As of perl 5.10, these are CORE modules; they come bundled with the distribution.

INTERNALS vs. DOCUMENTATION

All undocumented functionality is subject to change without notice.

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. Again, all undocumented functionality is subject to change without notice.

Changes to documented or well established parts will be clearly listed and archived in the CHANGES file bundled with this software package.

EXAMPLES

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

AVAILABILITY AND SUPPORT

See [http://net-bittorrent.googlecode.com/] for support and SVN repository access.

For now, please use [http://code.google.com/p/net-bittorrent/issues/list] for bug tracking. When reporting bugs/problems please include as much information as possible. It may be difficult for me to reproduce the problem as almost every setup is different.

CREDITS

Bram Cohen ([wikipedia://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.

AUTHOR

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

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.

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)

NAME

SYNOPSIS

DESCRIPTION

OVERVIEW

CONSTRUCTOR

METHODS

CALLBACKS

Peer level

Tracker level

File level

Piece level

Block level

Debug level

CAVEATS

BUGS/TODO

NOTES

INSTALLATION

DEPENDENCIES

INTERNALS vs. DOCUMENTATION

TAGS

EXAMPLES

AVAILABILITY AND SUPPORT

SEE ALSO

CREDITS

AUTHOR

LICENSE AND LEGAL

NAME

SYNOPSIS

DESCRIPTION

OVERVIEW

CONSTRUCTOR

METHODS

CALLBACKS

Peer level

Tracker level

File level

Piece level

Block level

Debug level

CAVEATS

BUGS/TODO

NOTES

INSTALLATION

DEPENDENCIES

INTERNALS vs. DOCUMENTATION

TAGS

EXAMPLES

AVAILABILITY AND SUPPORT

SEE ALSO

CREDITS

AUTHOR

LICENSE AND LEGAL

Module Install Instructions