GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::BitTorrent(3) User Contributed Perl Documentation Net::BitTorrent(3)

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

  use Net::BitTorrent;

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

  $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);
      }
  );

  my $torrent = $client->add_torrent({Path => q[a.legal.torrent]})
      or die q[Cannot load .torrent];

  $torrent->hashcheck;  # Verify any existing data

  $client->do_one_loop() while 1;

Net::BitTorrent is a class based implementation of the BitTorrent Protocol for distributed data exchange.

"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 and UDP 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 or run out of ports.

Default: 0 (any available, chosen by the OS)

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.
"add_torrent ( { ... } )"
Loads a .torrent file and adds the Net::BitTorrent::Torrent object to the client's queue.

Aside from the "Client" parameter (which is filled in automatically), this method hands everything off to Net::BitTorrent::Torrent's constructor, so see Net::BitTorrent::Torrent::new( ) for a list of expected parameters.

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

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

"do_one_loop ( [TIMEOUT] )"
Processes the internal schedule and handles activity of the various socket-containing objects (peers, trackers, DHT). This method should be called frequently to be of any use at all.

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

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

"peerid ( )"
Returns the Peer ID 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

"remove_torrent ( TORRENT )"
Removes a Net::BitTorrent::Torrent object from the client's queue.

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

"torrents ( )"
Returns the list of queued torrents.

See also: add_torrent ( ), remove_torrent ( )

When triggered, client-wide callbacks receive two arguments: the "Net::BitTorrent" object and a hashref containing pertinent information. For per-torrent callbacks, please see Net::BitTorrent::Torrent

This is the current list of events and the information passed to callbacks.

Note: This list is subject to change. Unless mentioned specifically, return values from callbacks do not affect behavior.

"ip_filter"
This gives a client author a chance to block or accept connections with a peer before an initial handshake is sent. The argument hash contains the following key:
"Address"
IPv4:port (or, on rare occasions, hostname:port) address of the potential peer.

Note: The return value from your "ip_filter" callback determines how we proceed. An explicitly false return value (ie 0) means this peer should not be contacted and (in the case of an incoming peer) the connection is dropped.

"peer_connect"
Triggered when we have both sent and received a valid handshake with the remote peer. The argument hash contains the following keys:
"Peer"
The remote peer with whom we have established a connection.
"peer_disconnect"
Triggered when a connection with a remote peer is lost or terminated. The argument hash contains the following keys:
"Peer"
The remote peer with whom we have established a connection.
"Reason"
When possible, this is a 'user friendly' string.
"peer_read"
This is triggered whenever we receive data from a remote peer via TCP. The argument hash contains the following keys:
"Peer"
The peer who sent the packet.
"Length"
The amount of data, in bytes, sent by the peer.
"peer_write"
This is triggered whenever we send data to a remote peer via TCP. The argument hash contains the following keys:
"Peer"
The peer on the receiving end of this data.
"Length"
The amount of data, in bytes, sent to the remote peer.
"outgoing_packet"
Triggered when we send a packet to a remote peer. The argument hash contains the following keys:
"Payload"
The parsed data sent in the packet (when applicable) in a hashref.
"Peer"
The remote peer receiving this data.
"Type"
The type of packet sent. These values match the packet types exported from Net::BitTorrent::Protocol.
"incoming_packet"
Triggered when we receive a packet to a remote peer. The argument hash contains the following keys:
"Payload"
The parsed data sent in the packet (when applicable) in a hashref.
"Peer"
The remote peer sending this data.
"Type"
The type of packet sent. These values match the packet types exported from Net::BitTorrent::Protocol.

"file_error"
Triggered when we run into an error handling the file in some way. The argument hash contains the following keys:
"File"
The file object related to this fault.
"Message"
The error message describing what (may have) gone wrong.
"file_open"
Triggered every time we open a file represented in a Net::BitTorrent::Torrent object. The argument hash contains the following keys:
"File"
The file object.
"Mode"
How the file is opened. To simplify things, "Net::BitTorrent" currently uses 'r' for read access and 'w' for write.
"file_close"
Triggered every time we close a file. The argument hash contains the following key:
"File"
The file object.
"file_write"
Triggered every time we write data to a file. The argument hash contains the following keys:
"File"
The file object.
"Length"
The actual amount of data written to the file.
"file_read"
Triggered every time we read data from a file. The argument hash contains the following keys:
"File"
The file object related to this fault.
"Length"
The actual amount of data written to the file.

Note: The tracker objects passed to these callbacks will either be a Net::BitTorrent::Torrent::Tracker::HTTP or a Net::BitTorrent::Torrent::Tracker::UDP.
"tracker_connect"
Triggered when we connect to a remote tracker. The argument hash contains the following keys:
"Tracker"
The tracker object related to this event.
"Event"
If defined, this describes why we are contacting the tracker. See the BitTorrent specification for more.

Note: This callback is only triggered from TCP trackers, as UDP is 'connection-less.'

"tracker_disconnect"
Triggered when we disconnect from a remote tracker. The argument hash contains the following key:
"Tracker"
The tracker object related to this event.

Note: This callback is only triggered from TCP trackers, as UDP is 'connection-less.'

"tracker_success"
Triggered when an announce attempt succeeds. The argument hash contains the following keys:
"Tracker"
The tracker object related to this event.
"Payload"
The data returned by the tracker in a hashref. The content of this payload based on what we receive from the tracker but these are the typical keys found therein:
"complete"
The number of seeds in the swarm according to the tracker.
"incomplete"
The number of leeches in the swarm according to the tracker.
"peers"
A compact list of peers in the swarm.
"min_interval"
The minimum amount of time before we should contact the tracker again.
"tracker_failure"
Triggered when an announce attempt fails. The argument hash contains the following keys:
"Tracker"
The tracker object related to this event.
"Reason"
The reason given by the remote tracker (when applicable) or as defined by "Net::BitTorrent" on socket errors.
"tracker_write"
Triggered when we write data to a remote tracker. The argument hash contains the following keys:
"Tracker"
The tracker object related to this event.
"Length"
The amount of data sent to the remote tracker.
"tracker_read"
Triggered when data is read from a tracker. The argument hash contains the following keys:
"Tracker"
The tracker object related to this event.
"Length"
The amount of data received from the remote tracker.

"piece_hash_fail"
Triggered when a piece fails to validate. The argument hash contains the following keys:
"Torrent"
The Net::BitTorrent::Torrent object related to this event.
"Index"
The zero-based index of the piece that failed to match the hash defined for it in the .torrent metadata.
"piece_hash_pass"
Triggered when a previously missing piece validates. The argument hash contains the following keys:
"Torrent"
The Net::BitTorrent::Torrent object related to this event.
"Index"
The zero-based index of the piece that was verified against the .torrent metadata.
"as_string ( [ VERBOSE ] )"
Returns a 'ready to print' dump of the object's data structure. If called in void context, the structure is printed to "STDERR". "VERBOSE" is a boolean value.

Numerous, I'm sure.

Please see the section entitled "Bug Reporting" in Net::BitTorrent::Notes if you've found one.

Please refer to Net::BitTorrent::Notes.

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.

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

See Net::BitTorrent::Notes.

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.

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 for b2

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

CPAN ID: SANKO

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

2022-04-09 perl v5.32.1
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.