NAME

Synopsis

  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

Description

Standalone "Net::BitTorrent::Torrent" objects can be made for informational use. See new ( ) and queue ( ).

Constructor

"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:

Methods

"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".

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.

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.

"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...

For example, a status of 201 implies the torrent is "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.

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.

Events

Per-torrent callbacks are limited to tracker-, piece-, and file-related events. See Net::BitTorrent for client-wide callbacks.

Author

CPAN ID: SANKO

License and Legal

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.