=pod

=head1 NAME

Net::BitTorrent::Callbacks - Callback API documentation

=head1 Description

Note: If kept up to date, this file will list and describe all callbacks
supported by the L<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 C<< $obj->on_[event]( &coderef ) >>.
For example:

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

=head2 Arguments Passed to Callbacks

When triggered, callbacks receive the original object and a hashref containing
at least the following key/value pairs: X<basic_arguments>

=over

=item B<message> => string

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

=item B<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.).

=item B<severity> => string

One of the following:

=over

=item debug

This will include a lot of debug events that can be used both for debugging
L<Net::BitTorrent> itself but also when debugging other clients that are
connected to L<Net::BitTorrent>. It will report strange behaviors among the
connected peers.

=item info

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

=item 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.

=item critical

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

=item 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.

=back

=back

Other, event-specific arguments are L<documented below|/"The Callbacks">.

=head2 Callback Return Values

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

=head1 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.

=head2 C<ip_filter>

This alert is generated when an incoming connection is declined or an outgoing
connection attempt is aborted because the remote host was
L<banned|Net::BitTorrent::Network::IPFilter/"is_banned"> by our local
L<ipfilter|Net::BitTorrent::Network::IPFilter>. This is a C<debug>ging event.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<address>

This is the IPv4 or IPv6 address and the remote port number of the banned
peer.

=item C<protocol>

This is either C<tcp4>, C<tcp6>, C<udp4>, or C<udp6>.

=item C<rule>

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

=back

=head2 C<listen_failure>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<port>

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

=item C<protocol>

This is either C<tcp4>, C<tcp6>, C<udp4>, or C<udp>.

=back

=head2 C<listen_success>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<port>

This is an integer.

=item C<protocol>

This is either C<tcp4>, C<tcp6>, C<udp4>, or C<udp>.

=back

=head2 C<peer_id>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=item C<peer_id>

This is the peer_id.

=back

=head1 TODO

These may soon show up but I'm lazy. All of the original callbacks will be
brought over soon.

=head2  C<peer_handshake_complete>

This event indicates we have both sent and received a valid handshake with a
remote peer.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=back

=head2  C<peer_disconnect>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=back

=head2 C<peer_data_in>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=item C<length>

The amount of data, in bytes, read from the peer.

=back

=head2 C<peer_data_out>

This is triggered whenever we send data to a remote peer.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=item C<length>

The amount of data, in bytes, sent to the peer.

=back

=head2 C<peer_packet_out>

Triggered when we queue a packet for sending to a remote peer.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=item C<packet>

The actual packet.

=back

=head2 C<peer_packet_in>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer>

This is the related L<Net::BitTorrent::Peer> object.

=item C<packet>

The actual packet.

=back

=head2  C<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 C<fatal> error.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<file>

This is the related L<Net::BitTorrent::File> object.

=back

=head2  C<file_open>

Whenever a file is opened for read or write, this event is triggered. This is
a C<debug> alert.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<file>

This is the related L<Net::BitTorrent::File> object.

=back

=head2  C<file_close>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<file>

This is the related L<Net::BitTorrent::File> object.

=back

=head2  C<file_write>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<file>

This is the related L<Net::BitTorrent::File> object.

=item C<length>

The amount of data (in bytes) written to the file.

=back

=head2  C<file_read>

Whenever a file read, this event is triggered. This is a C<debug> alert.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<file>

This is the related L<Net::BitTorrent::File> object.

=item C<length>

The amount of data (in bytes) read from the file.

=back

=head2 C<tracker_announce>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=back

=head2 C<tracker_failure>

This alert is generated on tracker time outs, premature disconnects, invalid
response or a HTTP response other than C<200 OK>. From the alert you can get
the handle to the torrent the tracker belongs to. This alert is generated as
severity level C<warning>.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=item C<times_in_row>

This is the number of times in a row this tracker has failed.

=item C<status_code>

This is the code returned from the HTTP server. C<401> means the tracker needs
authentication, C<404> means not found, etc. If the tracker timed out, the
code will be set to C<0>.

=back

=head2 C<tracker_success>

This is an C<info>rmational alert generated when a tracker announce succeeds.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=back

=head2 C<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 C<warning>.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=back

=head2 C<url_seed>

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

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<url>

This is the url of the HTTP seed that failed.

=back

=head2 C<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
C<info>.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=item C<index>

This is the zero based index for this piece.

=item C<peers>

A list of L<peer|Net::BitTorrent::Peer>s 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.

=back

=head2 C<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
C<info>.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the related L<Net::BitTorrent::Torrent> object.

=item C<index>

This is the zero based index for this piece.

=item C<peers>

A list of L<peer|Net::BitTorrent::Peer>s 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.

=back

=head2 C<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 C<info>.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the L<Net::BitTorrent::Torrent> that this peer was a swarm member of.

=item C<ip>

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

=back

=head2 C<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 C<debug> level
alert.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<peer_id>

If we have this peer's peer_id, you'll find it here. If not, this will be an
C<undef>ined value.

=item C<ip>

This is the IPv4 or IPv6 address of the newly disconnected peer.

=back

=head2 C<invalid_request>

This is a C<debug> alert that is generated by an incoming invalid piece
request.

In addition to the L<basic arguments|/basic_arguments>, this callback is
passed the following attributes:

=over

=item C<torrent>

This is the L<Net::BitTorrent::Torrent> that this peer was a swarm member of.

=item C<ip>

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

=back

=head1 Plotting

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

=over

=item C<tracker_write>

=item C<tracker_read>

=back

=head1 Author

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

CPAN ID: SANKO

=head1 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
L<The Artistic License 2.0|http://www.perlfoundation.org/artistic_license_2_0>.
See the F<LICENSE> file included with this distribution or
L<notes on the Artistic License 2.0|http://www.perlfoundation.org/artistic_2_0_notes>
for clarification.

When separated from the distribution, all original POD documentation is
covered by the
L<Creative Commons Attribution-Share Alike 3.0 License|http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>.
See the
L<clarification of the CCA-SA3.0|http://creativecommons.org/licenses/by-sa/3.0/us/>.

Neither this module nor the L<Author|/Author> is affiliated with BitTorrent,
Inc.

=for rcs $Id: Callbacks.pod 81f8292 2010-07-15 15:10:02Z sanko@cpan.org $

=cut
