NAME

Protocol::BitTorrent::Metainfo - support for metainfo as found in .torrent files

VERSION

version 0.004

SYNOPSIS

 use Protocol::BitTorrent::Metainfo;
 print Protocol::BitTorrent::Metainfo->new->parse_info(...)->announce_url;

DESCRIPTION

See Protocol::BitTorrent for top-level documentation.

METHODS

new

Instantiate a new metainfo object.

Takes the following named parameters:

announce - tracker URL for announcing peers
comment - optional comment for this torrent
encoding - encoding for the torrent, typically UTF8

parse_info

Parse the given metainfo structure to populate a new object. Used when reading an existing torrent file:

 my $data = File::Slurp::read_file($filename, { binmode => ':raw' });
 $data = Protocol::BitTorrent::Metainfo->bdecode($data);
 my $torrent = Protocol::BitTorrent::Metainfo->new->parse_info($data);

infohash

Returns the infohash for this torrent. Defined as the 20-character SHA1 hash of the info data.

file_info

Returns or updates the info data (referred to as an 'info dictionary' in the spec).

peer_id

Returns the current peer ID. This is a 20-character string used to differentiate peers connecting to a torrent.

Will generate a new peer ID if one has not already been assigned.

generate_peer_id_azureus

Generate a new peer ID using the Azureus style:

 -BT0001-980123456789

Takes the following parameters:

$type - the 2-character type, defaults to PB (for "Protocol::BitTorrent").
$version - the 4-character version code, should be numeric although this is not enforced. Defaults to current package version with . characters stripped.
$suffix - trailing string data to append to the peer ID, defaults to random decimal digits.

Example invocation:

 $torrent->generate_peer_id_azureus('XX', '0100', '0123148')

generate_peer_id

Generates a peer ID using the default method (currently Azureus which is the only defined method, see "generate_peer_id_azureus").

files

Returns a list of the files in this torrent, or replaces the current list if given an arrayref.

announce

Get/set tracker announce URL.

piece_length

Get/set current piece length. Recommended values seem to be between 256KB and 1MB.

total_length

Returns the total length for all files in this torrent.

total_pieces

Returns the total number of pieces in this torrent, equivalent to the total length of all files divided by the piece size (and rounded up to include the last partial piece as required).

pieces

Returns the combined hash string representing the pieces in this torrent. Will be a byte string of length "total_pieces" * 20.

is_private

Returns 1 if this is a private torrent, 0 otherwise.

has_private_flag

Returns true if this torrent has the optional private flag.

encoding

Get/set current encoding for metainfo strings.

trackers

Get/set trackers. Takes an arrayref when setting, returns a list.

comment

Get/set metainfo comment.

created

Get/set creation time of this torrent, as epoch value (seconds since 1st Jan 1970).

created_iso8601

Returns the "created" value as a string in ISO8601 format.

Example:

 2011-04-01T18:04:00

created_by

Get/set 'created by' field, indicating who created this torrent.

as_metainfo

Returns the object formatted as a metainfo hashref, suitable for bencoding into a .torrent file.

add_file

Adds the given file to this torrent. If the torrent already has a file and is in single mode, will switch to multi mode.

hash_for_file

Returns the SHA1 hash for the pieces in the given file.

announce_url

Returns the tracker announce URL