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[Session]}->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[Session]}->infohash);
      }
  );

  my $torrent = $client->add_session({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 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:

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, 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 available)

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 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 trackers, and with remote peers.

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

sessions( )

Returns the list of loaded .torrent sessions.

See also: add_session ( ), remove_session ( )

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.

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

See also: sessions, remove_session, Net::BitTorrent::Session

remove_session ( SESSION )

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

See also: sessions ( ), add_session, Net::BitTorrent::Session

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

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.