NAME

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

Synopsis

use Net::BitTorrent;

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

# ...
# Set various callbacks if you so desire
# ...
$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);
    }
);
$client->on_event(
    q[piece_hash_fail],
    sub {
        my ($self, $args) = @_;
        printf(qq[fail: 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

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

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

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|Net::BitTorrent::Version|/"gen_peerid ( )"> 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.

See also: add_torrent ( ), remove_torrent ( )

add_torrent ( { ... } )

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

Most arguments passed to this method are handed directly to Net::BitTorrent::Torrent::new( ). Please see Net::BitTorrent::Torrent::new( ) for a list of expected parameters. Note: The Client parameter, is automatically filled and should not be passed to Net::BitTorrent-add_torrent ( )>.

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

See also: torrents, remove_torrent, Net::BitTorrent::Torrent

remove_torrent ( TORRENT )

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

See also: torrents ( ), add_torrent, Net::BitTorrent::Torrent

do_one_loop ( [TIMEOUT] )

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

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

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

Net::BitTorrent and related classes trigger a number of events

TODO

Author

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

CPAN ID: SANKO

License and Legal

Copyright (C) 2008 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.