Net::BitTorrent::Session - Class Representing a Single .torrent File


new ( { [ARGS] } )

Creates a Net::BitTorrent::Session object. This constructor is called by Net::BitTorrent::add_session() and should not be used directly. new( ) accepts arguments as a hash, using key-value pairs:


Filename of the .torrent file to load.

This is the only required parameter.


Base directory used to store the files related to this session. This directory is created if not preexisting.

Default: ./ (Current working directory)


Length of blocks we request from peers of this session. This should not be changed as it can greatly affect performance.

Default: 32768 (2**15)


Unless stated, all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will result in undef or an empty list.

add_tracker ( URLS )

Add a new Net::BitTorrent::Session::Tracker tier to the session. Accepts a list of URLs.

See also: get_trackers ( )


Returns the base directory used by the files contained in this session.

get_path ( )

Returns the filename of the torrent this object represents.

append_nodes ( STRING )

Adds a string of compacted nodes to the list of potential peers.

This method may be renamed in a future version.

See also: compact_nodes ( ), nodes ( ), Net::BitTorrent::Util::compact( )

as_string ( [ VERBOSE ] )

Returns a 'ready to print' dump of the Net::BitTorrent::Session object's data structure. If called in void context, the structure is printed to STDERR.

See also: Net::BitTorrent

get_bitfield ( )

Returns a bitfield representing the pieces that have been successfully downloaded.

get_block_size ( )

Get the size used when requesting data from peers.

See also: set_block_size ( )

set_block_size ( NEWVAL )

Set the size used when requesting data from peers. Use with care.

See also: Net::BitTorrent::set_max_buffer_per_conn( ), (, discussion (

get_client ( )

Returns the Net::BitTorrent object related to this session.

close_files ( )

Forces the closure of all related Net::BitTorrent::Session::File objects with open file handles.

Under normal circumstances, this should not be called in clients.

get_compact_nodes ( )

Returns a list of potential peers as a compacted string.

See also: nodes ( ), Net::BitTorrent::Util::compact( ) Net::BitTorrent::Util::uncompact( )

get_complete ( )

Returns a boolean value indicating whether or not we have finished downloading all pieces we want.

See also: Net::BitTorrent::Session::Piece

get_downloaded ( )

Returns the total amount of data downloaded during the current session.

See also: get_uploaded ( )

get_files ( )

Returns a list of Net::BitTorrent::Session::File objects representing all files contained in the related .torrent file.

hash_check ( )

Verifies the integrity of all files associated with this session.

This is a blocking method; all processing will stop until this function returns.

See also: Net::BitTorrent::Session::Piece

get_infohash ( )

Returns the 20 byte SHA1 hash used to identify this session internally, with trackers, and with remote peers.

get_name ( )

For multi-file .torrents, returns the filename of the directory in which to store all the files according to the .torrent's metadata. For single file .torrents, returns the filename of the file according to the .torrent's metadata.

get_nodes ( )

Returns a list of potential peers.

To receive a compacted list of nodes (to use in a quick resume system, for example), see compact_nodes( ).

get_peers ( )

Returns a list of all related Net::BitTorrent::Session::Peer objects.

get_piece_count ( )

Returns the number of Net::BitTorrent::Session::Piece objects related to this session.

get_piece_size ( )

Returns the piece size defined in the .torrent file.

get_pieces ( )

Returns a list of Net::BitTorrent::Session::Piece objects.

get_private ( )

Returns a bool value indicating whether or not this session is allowed to use DHT and other Peer Exchange protocols.

get_total_size ( )

Returns the total size of all files listed in the .torrent file.

get_trackers ( )

Returns a list of all Net::BitTorrent::Session::Tracker objects related to the session.

See also: add_tracker ( )

get_uploaded ( )

Returns the total amount of data uploaded during the current session.

See also: get_downloaded ( )


Sanko Robinson <> -


License and Legal

Copyright 2008 by Sanko Robinson <>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10 (or higher). See or the LICENSE file included with this distribution.

All POD documentation is covered by the Creative Commons Attribution- Noncommercial-Share Alike 3.0 License (

Neither this module nor the Author is affiliated with BitTorrent, Inc.