/ 
Net-BitTorrent-0.074000_006
River stage zero No dependents
/ Net::BitTorrent::Callbacks

NAME

Net::BitTorrent::Callbacks - Callback API documentation

Description

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:

$client->on_file_error( \&cb_file_error );
sub cb_file_error {
    ...;
}

Arguments Passed to Callbacks

When triggered, callbacks receive a hashref containing at least the following key/value pairs:

message => string

This is a (often simple) description (in English) of the event suitable for display to the user.

event => string

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

severity => debug|info|warning|critical|fatal

This is an enum value which may be one of the following:

debug

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.

info

Events that can be considered normal, but still deserve an event. Something like a new piece passing a hash check.

warning

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.

critical

Errors which require user interaction or have an important message should never ignored.

fatal

Examples of fatal errors can be disk full or something else that will make it impossible to continue normal execution. Do not assume fatal errors lead to total client failure (exit/die/croak) because that's annoying.

Note that the object is not returned

Other, event-specific arguments are documented below.

Callback Return Values

Unless mentioned specifically, return values from callbacks do not affect behavior.

The Callbacks

This is the current list of callback triggering events and the information passed to them. Note that this list is subject to change.

listen_failure

This alert is generated when none of the ports given in the port range to new[<1|Net::BitTorrent/"new">, 2] can be opened for listening. This is a fatal error.

In addition to the basic attributes, this callback is passed the following attributes:

protocol

This is either tcp4, tcp6, udp4, or udp.

listen_success

This alert is generated when one of the ports given in the port range to new[<1|Net::BitTorrent/"new">, 2] was opened for listening. This is a debug event.

In addition to the basic attributes, this callback is passed the following attributes:

port

This is an integer.

protocol

This is either tcp4, tcp6, udp4, or udp.

ip_filter

This alert is generated when a connection is declined because the remote host was banned by our local ipfilter. This is a debugging event.

In addition to the basic attributes, this callback is passed the following attributes:

ip

This is the IPv4 or IPv6 address of the banned peer.

port

This is an integer.

protocol

This is either tcp4, tcp6, udp4, or udp.

rule

This is the Net::BitTorrent::Network::IPFilter::Rule object which caused this peer to result in a banned state.

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

tracker_announce

This alert is generated each time a tracker announce is sent (or attempted to be sent). This is an info alert.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

tracker_error

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

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.

tracker_reply

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

url_seed

This alert is generated when a HTTP seed name lookup fails. This alert is generated as severity level warning.

In addition to the basic attributes, this callback is passed the following attributes:

url

This is the url of the HTTP seed that failed.

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

index

This is the zero based index for this 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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

This is the related Net::BitTorrent::Torrent object.

index

This is the zero based index for this piece.

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

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_alert

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.

In addition to the basic attributes, this callback is passed the following attributes:

peer_id

If we have this peer's peer_id, you'll find it here. If not, this will be an undefined value.

ip

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.

In addition to the basic attributes, this callback is passed the following attributes:

torrent

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.

Author

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

CPAN ID: SANKO

License and Legal

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.