Sanko Robinson > Net-BitTorrent-0.074000_012 > Net::BitTorrent::Callbacks

Download:
Net-BitTorrent-0.074000_012.tar.gz

Annotate this POD

Website

View/Report Bugs
Source  

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 the original object and a hashref containing at least the following key/value pairs:

message => string

This is a 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 => string

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 be ignored.

fatal

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.

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.

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.

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.

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.

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

port

Single integer or a list of integers (depending on what you passed in) attempted.

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, 2] was opened for listening. This is a debug event.

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

port

This is an integer.

protocol

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

peer_id

When the remote peer sends us their peer_id, this event is triggered. This is a debug event.

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

peer

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

peer_id

This is the peer_id.

TODO ^

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.

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

peer

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

peer_disconnect

This callback is triggered when an established connection is lost or terminated.

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

peer

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

peer_data_in

This is triggered whenever we receive data from a remote peer.

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

peer

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

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.

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

peer

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

length

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.

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

peer

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

packet

The actual packet.

peer_packet_in

Triggered when we parse a complete packet from data sent to us from a remote peer.

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

peer

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

packet

The actual packet.

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 arguments, this callback is passed the following attributes:

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.

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

file

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

file_close

Whenever a file is closed, this event is triggered. This is a debug alert.

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

file

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

file_write

Whenever a file written to, this event is triggered. This is a debug alert.

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

file

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

length

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.

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

file

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

length

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.

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

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.

In addition to the basic arguments, 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_success

This is an informational alert generated when a tracker announce succeeds.

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

torrent

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

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 arguments, 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 arguments, this callback is passed the following attributes:

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.

In addition to the basic arguments, 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.

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.

In addition to the basic arguments, 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.

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.

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 arguments, 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

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 arguments, 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 arguments, 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.

Plotting ^

I may or may not keep these callbacks because I'm unsure how useful they are:

tracker_write
tracker_read

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.

syntax highlighting: