NAME

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

Synopsis

    use Net::BitTorrent;

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

    my $client = Net::BitTorrent->new();
    $client->set_callback(q[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 available)

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 usefulness of the module.

max_buffer_per_conn

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)

conns_per_client

Maximum number of peers per client object.

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

conns_per_session

Maximum number of peers per session.

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

max_halfopen

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

ul_slots_per_session

Maximum number of <requests|Net::BitTorrent::Session::Peer::Request> we keep in queue with each peer.

Default: 10

max_ul_rate

Maximum amount of data transfered per second to remote hosts.

Default: 0 (unlimited)

max_dl_rate

Maximum amount of data transfered per second from remote hosts.

Default: 0 (unlimited)

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 is also the set_callback( ) method 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.

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

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.

See also: http://perlmonks.org/?node_id=317520#debugging

get_debug_level ( )

Get the minimum level of messages passed to the log callback handler. See LOG LEVELS for more.

set_debug_level ( NEWVAL )

Set the minimum level of messages passed to the log callback handler. See LOG LEVELS for more.

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.

process_connections ( READERSREF, WRITERSREF, ERRORSREF )

Use this method when you want to implement your own select statement for event processing instead of using Net::BitTorrent's do_one_loop( ) method. The parameters are references to the readers, writers, and errors parameters used by the select statement.

Use the internal _get_fileno( ) method to set up the necessary bit vectors for your select call.

This is experimental and may be improved in the future.

See Also: Alternative Event Processing

process_timers ( )

Net::BitTorrent relies heavily on internal timing of various events (socket timeouts, tracker requests, etc.) and simply cannot function without processing these timers from time to time.

Use this method only if you have implemented your own select statement for event processing instead of Net::BitTorrent's do_one_loop( ) method.

See Also: Alternative Event Processing

get_max_buffer_per_conn ( )

Get the amount of unparsed data, in bytes, we store from a peer before dropping their connection.

See Also: set_max_buffer_per_conn ( NEWVAL )

set_max_buffer_per_conn ( NEWVAL )

Set the amount of unparsed data, in bytes, we store from a peer before dropping their connection. Be sure to keep this value high enough to allow incoming blocks (2**16 by default) to be held in memory without trouble but low enough to keep DDoS-like attacks at bay.

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

See Also: get_max_buffer_per_conn ( )

get_max_halfopen ( )

Get the maximum number of peers we have yet to receive a handshake from. These include sockets that have not connected yet.

See Also: set_max_halfopen ( NEWVAL )

set_max_halfopen ( NEWVAL )

Set the maximum number of peers we have yet to receive a handshake from. These include sockets that have not connected yet.

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

Default: 8

See Also: get_max_halfopen ( )

get_conns_per_client ( )

Get the maximum number of peers per client object.

See Also: set_conns_per_client ( )

set_conns_per_client ( NEWVAL )

Set the maximum number of peers per client object.

Default: 300

See also: theory.org (http://tinyurl.com/4jgdnl), get_conns_per_client ( )

get_conns_per_session ( )

Get the maximum number of peers per session.

See Also: set_conns_per_session ( )

set_conns_per_session ( NEWVAL )

Set the maximum number of peers per session.

Default: 100

See Also: get_conns_per_session ( )

get_ul_slot_size ( )

Get the maximum size, in bytes, a peer is allowed to request from us as a single block of data.

See Also: set_ul_slot_size ( )

set_ul_slot_size ( NEWVAL )

Set the maximum size, in bytes, a peer is allowed to request from us as a single block of data.

Default: 32768

See also: theory.org (http://tinyurl.com/32k7wu), get_ul_slot_size ( )

get_ul_slots_per_session ( )

Get the maximum number of blocks we have in queue from each peer.

See Also: set_ul_slots_per_session ( )

set_ul_slots_per_session ( NEWVAL )

Set the maximum number of blocks we have in queue from each peer.

Default: 10

See Also: get_ul_slots_per_session ( )

get_ul_slots_per_conn ( )

Get the maximum number of blocks we have in queue from each peer. Currently, this is 80.

See Also: set_ul_slots_per_conn ( )

set_ul_slots_per_conn ( NEWVAL )

Set the maximum number of blocks we have in queue from each peer. Currently, this is a NOOP. Yeah, yeah... It's on my Todo list...

See Also: get_ul_slots_per_conn ( )

get_max_ul_rate ( )

Get the maximum amount of data transfered per second from remote hosts in kilobytes. This rate limits both peers and trackers. To remove transfer limits, set this value to 0.

Note: This functionality requires the use of do_one_loop( ) for event processing.

See Also: set_max_ul_rate ( )

set_max_ul_rate ( NEWVAL )

Set the maximum amount of data transfered per second from remote hosts in kilobytes. This rate limits both peers and trackers. To remove transfer limits, set this value to 0.

Note: This functionality requires the use of do_one_loop( ) for event processing.

Default: 0 (unlimited)

See Also: get_max_ul_rate ( )

get_max_dl_rate ( )

Get the maximum amount of data transfered per second from remote hosts in kilobytes. This rate limits both peers and trackers. To remove transfer limits, set this value to 0.

Note: This functionality requires the use of do_one_loop( ) for event processing.

See Also: get_max_dl_rate ( )

set_max_dl_rate ( NEWVAL )

Set the maximum amount of data transfered per second from remote hosts in kilobytes. This rate limits both peers and trackers. To remove transfer limits, set this value to 0.

Note: This functionality requires the use of do_one_loop( ) for event processing.

Default: 0 (unlimited)

See Also: get_max_dl_rate ( )

get_peer_id ( )

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

get_dht ( )

Returns the Net::BitTorrent::DHT object related to this client.

See Also: Net::BitTorrent::DHT

remove_session ( SESSION )

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

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

get_sessions ( )

Returns a list of loaded Net::BitTorrent::Session objects.

See Also: add_session, remove_session, Net::BitTorrent::Session

get_sockaddr ( )

Return the address part of the sockaddr structure for the TCP socket.

See also: "sockaddr" in IO::Socket::INET

get_sockport ( )

Return the port number that the TCP socket is using on the local host.

See also: "sockport" in IO::Socket::INET

Callbacks

set_callback( TYPE, CODEREF )

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

Here is the current list of events fired by Net::BitTorrent sorted by their related classes:

Peer level

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

peer_connect

Callback arguments: ( CLIENT, PEER )

peer_disconnect

Callback arguments: ( CLIENT, PEER, [REASON] )

peer_incoming_bitfield

Callback arguments: ( CLIENT, PEER )

peer_incoming_block

Callback arguments: ( CLIENT, PEER, BLOCK )

peer_incoming_cancel

Callback arguments: ( CLIENT, PEER, REQUEST )

peer_incoming_choke

Callback arguments: ( CLIENT, PEER )

peer_incoming_data

Callback arguments: ( CLIENT, PEER, LENGTH )

peer_incoming_disinterested

Callback arguments: ( CLIENT, PEER )

peer_incoming_handshake

Callback arguments: ( CLIENT, PEER )

peer_incoming_have

Callback arguments: ( CLIENT, PEER, INDEX )

peer_incoming_interested

Callback arguments: ( CLIENT, PEER )

peer_incoming_keepalive

Callback arguments: ( CLIENT, PEER )

peer_incoming_packet

Callback arguments: ( CLIENT, PEER, PACKET )

peer_incoming_request

Callback arguments: ( CLIENT, PEER, REQUEST )

peer_incoming_unchoke

Callback arguments: ( CLIENT, PEER )

peer_outgoing_bitfield

Callback arguments: ( CLIENT, PEER )

peer_outgoing_block

Callback arguments: ( CLIENT, PEER, REQUEST )

peer_outgoing_cancel

Callback arguments: ( CLIENT, PEER, BLOCK )

peer_outgoing_choke

Callback arguments: ( CLIENT, PEER )

peer_outgoing_data

Callback arguments: ( CLIENT, PEER, LENGTH )

peer_outgoing_disinterested

Callback arguments: ( CLIENT, PEER )

peer_outgoing_handshake

Callback arguments: ( CLIENT, PEER )

peer_outgoing_have

Callback arguments: ( CLIENT, PEER, INDEX )

peer_outgoing_interested

Callback arguments: ( CLIENT, PEER )

peer_outgoing_keepalive

Callback arguments: ( CLIENT, PEER )

peer_outgoing_request

Callback arguments: ( CLIENT, PEER, BLOCK )

peer_outgoing_unchoke

Callback arguments: ( CLIENT, PEER )

peer_outgoing_port

Callback arguments: ( CLIENT, PEER )

Tracker level

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

tracker_announce

Callback arguments: ( CLIENT, TRACKER )

tracker_announce_okay

Callback arguments: ( CLIENT, TRACKER )

tracker_connect

Callback arguments: ( CLIENT, TRACKER )

tracker_disconnect

Callback arguments: ( CLIENT, TRACKER )

tracker_error

Callback arguments: ( CLIENT, TRACKER, MESSAGE )

tracker_incoming_data

Callback arguments: ( CLIENT, TRACKER, LENGTH )

tracker_outgoing_data

Callback arguments: ( CLIENT, TRACKER, LENGTH )

tracker_scrape

Callback arguments: ( CLIENT, TRACKER )

tracker_scrape_okay

Callback arguments: ( CLIENT, TRACKER )

File level

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

file_close

Callback arguments: ( CLIENT, FILE )

file_error

Callback arguments: ( CLIENT, FILE, [REASON] )

file_open

Callback arguments: ( CLIENT, FILE )

file_read

Callback arguments: ( CLIENT, FILE, LENGTH )

file_write

Callback arguments: ( CLIENT, FILE, LENGTH )

Piece level

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

piece_hash_fail

Callback arguments: ( CLIENT, PIECE )

piece_hash_pass

Callback arguments: ( CLIENT, PIECE )

Block level

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

block_write

Callback arguments: ( CLIENT, BLOCK )

Debug level

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

log

Callback arguments: ( CLIENT, LEVEL, STRING )

See also: Log Levels in Net::BitTorrent::Util

Implemented Extensions

See Net::BitTorrent::Notes

Bugs

Numerous, I'm sure.

Found bugs should be reported through http://code.google.com/p/net-bittorrent/issues/list. Please include as much information as possible. For more, see Net::BitTorrent::Todo as well as Issue Tracker, Bug Reporting, and Co-Development and Patch Submission information from the Net::BitTorrent::Notes.

Notes

Support and Availability

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://sankorobinson.com/net-bittorrent/.

Bug and Issue Tracker

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

Before creating and sending a report, please review the following list:

  • Make sure you are using the most recent release of Net::BitTorrent. This may mean checking out the latest svn commit.

  • Make sure the bug is reproducible.

  • See the complete checklist in the Net::BitTorrent::Notes.

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.

    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 and "web-gui.pl" in scripts.

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

Alternative Event Processing

To making integrating Net::BitTorrent into an existing select-based event loop just a little easier, an alternative way of doing event processing (vs. do_one_loop ( )) has been designed... uh, I mean ganked. Simply call the process_connections( ) method with references to the lists of readers, writers, and errors given to you by select. Connections that don't belong to the object will be ignored, and connections that do belong to the object will be removed from the select lists so that you can use the lists for your own purposes.

Here's a painfully simple example:

  while (1) {
      my ($rin, $win, $ein) = (q[], q[], q[]);
      vec($rin, fileno($server), 1) = 1;
      for my $object (values %{$bittorrent->_get_connections}) {
          vec($rin, $object->_get_fileno, 1) = 1;
          vec($win, $object->_get_fileno, 1) = 1
              if $object ne $bittorrent and $object->_get_queue_outgoing;
      }

      # Add your other sockets to the bit vectors

      $ein = $rin | $win;
      my ($nfound) = select($rin, $win, $ein, 1);
      $bittorrent->process_connections(\$rin, \$win, \$ein)
          if $nfound and $nfound != -1;
      $bittorrent->process_timers;    # Don't forget this!

      # Now $rin, $win, and $ein only have the file descriptors not
      # associated with Net::BitTorrent (related) objects in them -
      # we can process our events.
  }

For a working demonstration, see scripts/web-gui.pl.

This is experimental and may be improved in the future.

See Also

http://bittorrent.org/beps/bep_0003.html - BitTorrent Protocol Specification

Net::BitTorrent::Notes - Random stuff. More jibba jabba.

Peer ID Specification - The standard used to identify Net::BitTorrent in the wild.

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

Author

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

CPAN ID: SANKO

License and Legal

Copyright 2008 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10 (or higher). See http://www.perl.com/perl/misc/Artistic.html or the LICENSE file included with this distribution.

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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 1524:

alternative text 'scripts/client.pl' contains non-escaped | or /

Around line 1600:

alternative text 'scripts/web-gui.pl' contains non-escaped | or /