Net::BitTorrent - BitTorrent client class
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. }
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.
Net::BitTorrent
BitTorrent is a free speech tool.
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:
PARAMETERS
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.
xx.xx.xx.xx
Note: this differs from the LocalAddr key used by IO::Socket::INET
LocalAddr
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.
undef
0
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)
select()
If the constructor fails, undef will be returned and the value of $! and $^E should be checked.
$!
$^E
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.
true
false
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.
select
timeout ( [TIMEOUT] )
Gets or sets the timeout value used by the "do_one_loop ( )" method. The default timeout is 5 seconds.
See Also: "do_one_loop ( )", "new ( [PARAMETERS] )"
sessions ( )
Returns a list of all (if any) loaded Net::BitTorrent::Session objects.
See Also: "add_session ( { ... } )", "remove_session ( SESSION )", Net::BitTorrent::Session
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.
Net::BitTorrent::Session::new()
This method returns undef on failure or a new Net::BitTorrent::Session object on success.
See also: "sessions ( )", "remove_session ( SESSION )", Net::BitTorrent::Session
remove_session ( SESSION )
Removes a Net::BitTorrent::Session object from the client.
Net::BitTorrent::Session
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.
See also: "sessions ( )", "add_session ( { ... } )", Net::BitTorrent::Session
peer_id ( )
Retrieve the peer_id generated for this Net::BitTorrent object.
See also: [theory://peer_id]
sockaddr ( )
Return the address part of the sockaddr structure for the socket.
See also: "sockaddr" in IO::Socket::INET
sockport ( )
Return the port number that the socket is using on the local host.
See also: "sockport" in IO::Socket::INET
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. (Defaults to 98304)
maximum_peers_per_client ( )
Max number of peers per client object.
Default: 300
See also: [theory://Algorithms:_Queuing>]
maximum_peers_per_session ( )
Max number of peers per session.
Default: 100
maximum_peers_half_open ( )
Max 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_size ( )
Maximum size, in bytes, a peer is allowed to request from us as a single block.
Default: 32768
See also: [talk://Messages:_request]
maximum_requests_per_peer ( )
Maximum number of blocks we have in queue from each peer.
Default: 10
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.
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.
eval
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: [id://317520]
use_unicode ( [VALUE] )
Win32 perl does not handle filenames with extended characters properly.
This is an experimental workaround that may or may not be removed or improved in the future.
See also [id://538097], [id://229642], [id://445883], [http://groups.google.com/group/perl.unicode/msg/86ab5af239975df7]
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).
set_callback_on_[action]
$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 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 )
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 )
set_callback_on_peer_incoming_data ( CODEREF )
Callback arguments: ( CLIENT, PEER, LENGTH )
set_callback_on_peer_incoming_disinterested ( CODEREF )
set_callback_on_peer_incoming_handshake ( CODEREF )
set_callback_on_peer_incoming_have ( CODEREF )
Callback arguments: ( CLIENT, PEER, INDEX )
set_callback_on_peer_incoming_interested ( CODEREF )
set_callback_on_peer_incoming_keepalive ( CODEREF )
set_callback_on_peer_incoming_packet ( CODEREF )
Callback arguments: ( CLIENT, PEER, PACKET )
set_callback_on_peer_incoming_request ( CODEREF )
set_callback_on_peer_incoming_unchoke ( CODEREF )
set_callback_on_peer_outgoing_bitfield ( CODEREF )
set_callback_on_peer_outgoing_block ( CODEREF )
set_callback_on_peer_outgoing_cancel ( CODEREF )
set_callback_on_peer_outgoing_choke ( CODEREF )
set_callback_on_peer_outgoing_data ( CODEREF )
set_callback_on_peer_outgoing_disinterested ( CODEREF )
set_callback_on_peer_outgoing_handshake ( CODEREF )
set_callback_on_peer_outgoing_have ( CODEREF )
set_callback_on_peer_outgoing_interested ( CODEREF )
set_callback_on_peer_outgoing_keepalive ( CODEREF )
set_callback_on_peer_outgoing_packet ( CODEREF )
set_callback_on_peer_outgoing_request ( CODEREF )
set_callback_on_peer_outgoing_unchoke ( CODEREF )
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 )
set_callback_on_tracker_connect ( CODEREF )
set_callback_on_tracker_disconnect ( CODEREF )
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 )
set_callback_on_tracker_scrape ( CODEREF )
set_callback_on_tracker_scrape_okay ( CODEREF )
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 )
set_callback_on_file_read ( CODEREF )
Callback arguments: ( CLIENT, FILE, LENGTH )
set_callback_on_file_write ( CODEREF )
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 )
Block level events are triggered by Net::BitTorrent::Session::Piece::Block objects.
set_callback_on_block_write ( CODEREF )
Callback arguments: ( BLOCK )
Debug level callbacks can be from anywhere and are not object specific.
set_callback_on_log ( CODEREF )
Callback arguments: ( CLIENT, STRING )
...none yet.
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.
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::Reporter
$ 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/]).
Net::BitTorrent requires [cpan://version], and [cpan://Digest::SHA]. As of perl 5.10, these are CORE modules; they come bundled with the distribution.
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.
Throughout the source (in POD and inline comments), I have used bracketed tags when linking to reference material. The basis for these tags is the list from PerlMonks ([id://43037]) with the addition of the following:
These are links to [http://wiki.theory.org/] documentation. The base URL for these is [http://wiki.theory.org/BitTorrentSpecification] where the tag's value is either a named anchor or easily noted section name.
These are links to [http://wiki.theory.org/] discussions of disputed parts of the protocol's implementation. The base URL for these is [http://wiki.theory.org/Talk:BitTorrentSpecification] where the tag's value is a named anchor.
BEP stands for BitTorrent Enhancement Proposal. A BEP is a design document providing information to the BitTorrent community, or describing a new feature for the BitTorrent protocols. See [http://bittorrent.org/beps/bep_0000.html] for the current list of BEPs and [http://bittorrent.org/beps/bep_0001.html] for more on BEPs.
For a demonstration of Net::BitTorrent, see /scripts/client.pl.
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.
BitTorrent Protocol Specification - [bep://3]
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.
Sanko Robinson <sanko@cpan.org> - [http://sankorobinson.com/]
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 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.