Net::BitTorrent::Torrent - Class Representing a Single .torrent File
use Net::BitTorrent::Torrent; my $torrent = Net::BitTorrent::Torrent->new({Path => q[a.legal.torrent]}) or die q[Cannot load .torrent]; $torrent->on_event( q[piece_hash_pass], sub { printf qq[%s is % 3.2f%% complete\r], $torrent->name, (scalar grep {$_} split q[], unpack q[b*], $torrent->bitfield) / $torrent->piece_count * 100; } ); $torrent->hashcheck; # Verify any existing data
Net::BitTorrent::Torrent objects are typically created by the Net::BitTorrent class.
Net::BitTorrent::Torrent
Net::BitTorrent
Standalone Net::BitTorrent::Torrent objects can be made for informational use. See new ( ) and queue ( ).
new ( { [ARGS] } )
Creates a Net::BitTorrent::Torrent object. This constructor is called by Net::BitTorrent->add_torrent( ).
new( ) accepts arguments as a hash, using key-value pairs:
new( )
BaseDir
The root directory used to store the files related to this torrent. This directory is created if not preexisting.
This is an optional parameter.
Default: ./ (Current working directory)
./
Client
The Net::BitTorrent object this torrent will eventually be served from.
No default. Without a defined parent client, his object is very limited in capability. Basic information and hash checking only. Orphan objects are obviously not queued automatically and must be added to a client manually.
Path
Filename of the .torrent file to load.
This is the only required parameter.
Resume
The filename used to gather and store resume data.
No default. Without a defined resume file, resume data will not be written on calls to save_resume_data ( ) without a PATH parameter.
PATH
Status
Initial status of the torrent. This parameter is ORed with the loaded and queued (if applicable) values.
For example, you could set the torrent to automatically start after hashcheck with { [...] Status => START_AFTER_CHECK, [...] }.
{ [...] Status => START_AFTER_CHECK, [...] }
To import all supported statuses into your namespace, use the status keyword.
status
Default: 1 (started)
See also: status ( )
Note: This is alpha code and may not work correctly.
bitfield ( )
Returns a bitfield representing the pieces that have been successfully downloaded.
comment ( )
Returns the (optional) comment the original creator included in the .torrent metadata.
created_by ( )
Returns the (optional) "created by" string included in the .torrent metadata. This is usually a software version.
creation_date ( )
Returns the (optional) creation time of the torrent, in standard UNIX epoch format.
downloaded ( )
Returns the total amount downloaded from remote peers since the client started transferring data related to this .torrent.
See also: uploaded ( )
error ( )
Returns the most recent error that caused the software to set the error status. Torrents with active errors are automatically stopped and must be started.
See also: status ( ), start ( )
files ( )
Returns a list of Net::BitTorrent::Torrent::File objects representing all files contained in the related .torrent file.
hashcheck ( )
Verifies the integrity of all files associated with this torrent.
This is a blocking method; all processing will stop until this function returns.
See also: bitfield ( ), status ( )
infohash ( )
Returns the 20 byte SHA1 hash used to identify this torrent internally, with trackers, and with remote peers.
is_complete ( )
Returns a bool value based on download progress. Returns true when we have completed every file with a priority above 0. Otherwise, returns false.
true
0
false
See also: Net::BitTorrent::Torrent::File->priority()
name ( )
Returns the advisory name used when creating the related files on disk.
In a single file torrent, this is used as the filename by default. In a multiple file torrent, this is used as the containing directory for related files.
on_event ( TYPE, CODEREF )
Net::BitTorrent::Torrent provides per-torrent callbacks. For example, to catch all attempts to read from a file, use $torrent->on_event( 'file_read', \&on_read ). These per- torrent callbacks are especially useful for standalone torrents.
$torrent->on_event( 'file_read', \&on_read )
See the Events section for more.
path ( )
Returns the filename of the torrent this object represents.
pause ( )
Pauses an active torrent without closing related sockets.
See also: status ( ), stop ( ), start ( )
peers ( )
Returns a list of remote peers related to this torrent.
piece_count ( )
The number of pieces this torrent's data is broken into.
private ( )
Returns bool value dependent on whether the private flag is set in the .torrent metadata. Private torrents disallow information sharing via DHT and PEX.
queue ( CLIENT )
Adds a standalone (or orphan) torrent object to the particular CLIENT object's queue.
See also: remove_torrent ( )
raw_data ( [ RAW ] )
Returns the bencoded metadata found in the .torrent file. This method returns the original metadata in either bencoded form or as a raw hash (if you have other plans for the data) depending on the boolean value of the optional RAW parameter.
RAW
resume_path ( )
Returns the default path used to store resume data. This value is set in the Resume parameter to new.
save_resume_data ( [ PATH ] )
One end of Net::BitTorrent's resume system. This method writes the data to the file specified in the call to new( ) or (if defined) to the PATH parameter.
See also: Resume API and How do I quick Resume a .torrent Session Between Client Sessions? in Net::BitTorrent::Notes
size ( )
Returns the total size of all files listed in the .torrent file.
status ( )
Returns the internal status of this Net::BitTorrent::Torrent object. States are bitwise AND values of...
AND
For example, a status of 201 implies the torrent is QUEUED | LOADED | CHECKED | STARTED.
201
QUEUED | LOADED | CHECKED | STARTED
When torrents have the a status that indicates an error, they must be restarted (if possible). The reason for the error may be returned by error ( ).
Import the :status tag and you'll get the various status keywords in your namespace.
:status
Note: This is alpha and may not work as advertised. Yet.
start ( )
Starts a paused or stopped torrent.
See also: status ( ), stop ( ), pause ( )
stop ( )
Stops an active or paused torrent. All related sockets (peers) are disconnected and all files are closed.
See also: status ( ), start ( ), pause ( )
trackers
Returns a list of all Net::BitTorrent::Torrent::Tracker objects related to the torrent.
uploaded ( )
Returns the total amount uploaded to remote peers since the client started transferring data related to this .torrent.
See also: downloaded ( )
as_string ( [ VERBOSE ] )
Returns a 'ready to print' dump of the object's data structure. If called in void context, the structure is printed to STDERR. VERBOSE is a boolean value.
STDERR
VERBOSE
When triggered, per-torrent callbacks receive two arguments: the Net::BitTorrent::Torrent object and a hashref containing pertinent information. Per-torrent callbacks also trigger client-wide callbacks when the current torrent is queued.
Per-torrent callbacks are limited to tracker-, piece-, and file-related events. See Net::BitTorrent for client-wide callbacks.
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2009 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 http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.
When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.
Neither this module nor the Author is affiliated with BitTorrent, Inc.
To install Net::BitTorrent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::BitTorrent
CPAN shell
perl -MCPAN -e shell install Net::BitTorrent
For more information on module installation, please visit the detailed CPAN module installation guide.