Net::BitTorrent::Callbacks - Callback API documentation
Note: If kept up to date, this file will list and describe all callbacks supported by the Net::BitTorrent distribution. Currently, only a few callbacks are implemented and they're all subject to chagne but until I get a stable version from this branch, consider this the official specification.
TMTOWTDI. The first (and probably the least troublesome) is to set callbacks in the object's constructor:
use Net::BitTorrent; my $client = Net::BitTorrent->new( on_file_error => sub { ... } );
You can also register a callback with $obj->on_[event]( &coderef ). For example:
$obj->on_[event]( &coderef )
$client->on_file_error( \&cb_file_error ); sub cb_file_error { ...; }
When triggered, callbacks receive the original object and a hashref containing at least the following key/value pairs:
This is a simple description (in English) of the event suitable for display to the user.
This is the kind of event which was triggered. This is useful if you use a single callback coderef for many types of events (by category, etc.).
One of the following:
This will include a lot of debug events that can be used both for debugging Net::BitTorrent itself but also when debugging other clients that are connected to Net::BitTorrent. It will report strange behaviors among the connected peers.
Events that can be considered normal, but still deserve an event. Something like a new piece passing a hash check.
Messages with the warning severity can be a tracker that times out or responds with invalid data. The failing event will likely be retried automatically (in this example, the next tracker in a multitracker sequence will be tried). Warnings do not require user interaction.
Errors which require user interaction or have an important message should never be ignored.
Fatal errors include any error which makes normal execution impossible but do not assume fatal errors lead to total client failure (exit/die/croak) because that's annoying. A full disk is an example of a fatal error.
Other, event-specific arguments are documented below.
Unless mentioned specifically, return values from callbacks do not affect behavior.
This is the current list of callback triggering events and the information passed to them. Note that this list is subject to change.
ip_filter
This alert is generated when an incoming connection is declined or an outgoing connection attempt is aborted because the remote host was banned by our local ipfilter. This is a debugging event.
debug
In addition to the basic arguments, this callback is passed the following attributes:
address
This is the IPv4 or IPv6 address and the remote port number of the banned peer.
protocol
This is either tcp4, tcp6, udp4, or udp6.
tcp4
tcp6
udp4
udp6
rule
This is the Net::BitTorrent::Network::IPFilter::Rule object which caused this peer to result in a banned state.
listen_failure
This alert is generated when none of the ports given in the port range to new[1, 2] can be opened for listening. This is a fatal error.
new
fatal
port
Single integer or a list of integers (depending on what you passed in) attempted.
This is either tcp4, tcp6, udp4, or udp.
udp
listen_success
This alert is generated when one of the ports given in the port range to new[1, 2] was opened for listening. This is a debug event.
This is an integer.
peer_id
When the remote peer sends us their peer_id, this event is triggered. This is a debug event.
peer
This is the related Net::BitTorrent::Peer object.
This is the peer_id.
These may soon show up but I'm lazy. All of the original callbacks will be brought over soon.
peer_handshake_complete
This event indicates we have both sent and received a valid handshake with a remote peer.
peer_disconnect
This callback is triggered when an established connection is lost or terminated.
peer_data_in
This is triggered whenever we receive data from a remote peer.
length
The amount of data, in bytes, read from the peer.
peer_data_out
This is triggered whenever we send data to a remote peer.
The amount of data, in bytes, sent to the peer.
peer_packet_out
Triggered when we queue a packet for sending to a remote peer.
packet
The actual packet.
peer_packet_in
Triggered when we parse a complete packet from data sent to us from a remote peer.
file_error
If the storage fails to read or write files that it needs access to, this alert is generated and the torrent is paused. This is a fatal error.
file
This is the related Net::BitTorrent::File object.
file_open
Whenever a file is opened for read or write, this event is triggered. This is a debug alert.
file_close
Whenever a file is closed, this event is triggered. This is a debug alert.
file_write
Whenever a file written to, this event is triggered. This is a debug alert.
The amount of data (in bytes) written to the file.
file_read
Whenever a file read, this event is triggered. This is a debug alert.
The amount of data (in bytes) read from the file.
tracker_announce
This alert is generated each time a tracker announce is sent (or attempted to be sent). This is an info alert.
info
torrent
This is the related Net::BitTorrent::Torrent object.
tracker_failure
This alert is generated on tracker time outs, premature disconnects, invalid response or a HTTP response other than 200 OK. From the alert you can get the handle to the torrent the tracker belongs to. This alert is generated as severity level warning.
200 OK
warning
times_in_row
This is the number of times in a row this tracker has failed.
status_code
This is the code returned from the HTTP server. 401 means the tracker needs authentication, 404 means not found, etc. If the tracker timed out, the code will be set to 0.
401
404
0
tracker_success
This is an informational alert generated when a tracker announce succeeds.
tracker_warning
This alert is triggered if the tracker reply contains a warning field. Usually this means that the tracker announce was successful but the tracker has a message to the client. It is generated with severity level warning.
url_seed
This alert is generated when a HTTP seed name lookup fails. This alert is generated as severity level warning.
url
This is the url of the HTTP seed that failed.
piece_hash_failed
This alert is generated when a finished piece fails its hash check. You can get the handle to the torrent which got the failed piece and the index of the piece itself from this alert. This alert is generated as severity level info.
index
This is the zero based index for this piece.
peers
A list of peers who were involved with this piece. This value will be an empty list if the callback is triggered by a check on data already on disk.
piece_hash_passed
This alert is generated when a finished piece passes its hash check. You can get the handle to the torrent which got the valid piece and the index of the piece itself from this alert. This alert is generated as severity level info.
peer_ban
This alert is generated when a peer is banned because it has been involved with too many corrupt pieces. It is generated at severity level info.
This is the Net::BitTorrent::Torrent that this peer was a swarm member of.
ip
This is the IPv4 or IPv6 address of the newly banned peer.
peer_error
This alert is generated when a peer sends invalid data over the peer-to-peer protocol. The peer will be disconnected but this alert also contains identification information for future reference. This is a debug level alert.
If we have this peer's peer_id, you'll find it here. If not, this will be an undefined value.
undef
This is the IPv4 or IPv6 address of the newly disconnected peer.
invalid_request
This is a debug alert that is generated by an incoming invalid piece request.
I may or may not keep these callbacks because I'm unsure how useful they are:
tracker_write
tracker_read
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2010 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 notes on the Artistic License 2.0 for clarification.
When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.
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.