view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

[![Build Status](https://travis-ci.org/sanko/anyevent-bittorrent.svg?branch=master)](https://travis-ci.org/sanko/anyevent-bittorrent)
# NAME

AnyEvent::BitTorrent - Yet Another BitTorrent Client Module

# Synopsis

        use AnyEvent::BitTorrent;
        my $client = AnyEvent::BitTorrent->new( path => 'some.torrent' );
        AE::cv->recv;

# Description

This is a painfully simple BitTorrent client written on a whim that implements
the absolute basics. For a full list of what's currently supported, what you
will likely find in a future version, and what you'll never get from this, see
the section entitled "[This Module is Lame!](#this-module-is-lame)"

# Methods

The API, much like the module itself, is simple.

Anything you find by skimming the source is likely not ready for public use
and will be subject to change before `v1.0.0`. Here's the public interface as
of this version:

## `new( ... )`

        my $c = AnyEvent::BitTorrent->new(
                path         => 'some/legal.torrent',
                basedir      => './storage/',
                port         => 6881,
                on_hash_pass => sub { ... },
                on_hash_fail => sub { ... },
                state        => 'stopped',
                piece_cache  => $quick_restore
        );

This constructor understands the following arguments:

- `path`

    This is the only required parameter. It's the path to a valid .torrent file.

- `basedir`

    This is the base directory all data will be stored in and/or read from.
    Multifile torrents will create another directory below this to store all
    files.

    By default, this is the current working directory when
    [`new( ... )`](#new) is called.

- `port`

    This is the preferred port local host binds and expects incoming peers to
    connect to.

    By default, this is a zero; the system will pick a port number randomly.

- `on_hash_fail`

    This is a subroutine called whenever a piece fails to pass
    [hashcheck](#hashcheck). The callback is handed the piece's index.

- `on_hash_pass`

    This is a subroutine called whenever a piece passes its
    [hashcheck](#hashcheck). The callback is handed the piece's index.

- `state`

    This must be one of the following:

    - `started`

        This is the default. The client will attempt to create new connections, make
        and fill requests, etc. This is normal client behavior.

    - `paused`

        In this state, connections will be made and accepted but no piece requests
        will be made or filled. To resume full, normal behavior, you must call
        [`start( )`](#start).

    - `stopped`

        Everything is put on hold. No new outgoing connections are attempted and
        incoming connections are rejected. To resume full, normal behavior, you must
        call [`start( )`](#start).

- `piece_cache`

    This is the index list returned by [`piece_cache( )`](#piece_cache) in a
    previous instance. Using this should make a complete resume system a trivial
    task.

## `hashcheck( [...] )`

This method expects...

- ...a list of integers. You could use this to check a range of pieces (a
single file, for example).

            $client->hashcheck( 1 .. 5, 34 .. 56 );

- ...a single integer. Only that specific piece is checked.

            $client->hashcheck( 17 );

- ...nothing. All data related to this torrent will be checked.

            $client->hashcheck( );

As pieces pass or fail, your `on_hash_pass` and `on_hash_fail` callbacks are
triggered.