Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

libtorrent (3)

Name

libtorrent - a BitTorrent library

Synopsis

Please see following description for synopsis

Description

LIBTORRENT(3)              Library Functions Manual              LIBTORRENT(3)



NAME
       libtorrent - a BitTorrent library


DESCRIPTION
       LibTorrent  is  a  BitTorrent  library  written in C++ for *nix, with a
       focus on high performance and good  code.  The  library  differentiates
       itself  from  other  implementations  by transfering directly from file
       pages to the network stack. On high-bandwidth connections it is able to
       seed at 3 times the speed of the official client.

       Torrent State

           o      Closed

                  This  is  the initial state of a download. When switching to
                  this mode, all tracker requests are closed and the  bitfield
                  of  completed  chunks  is  cleared.  File  paths can only be
                  changed in this state.  Functions for getting information on
                  bitfields, chunk count and various others will return size 0
                  in this state.

                  torrent::Download::is_open() == false;
                  torrent::Download::is_active() == false;
                  torrent::Download::is_tracker_busy() == false;

           o      Open

                  This is the state after a successfull call to torrent::Down-
                  load::open().   This   function  throws torrent::local_error
                  if the download could not be opened. All files in the  down-
                  load have been created  and are open. The initial hash check
                  must be done to get a valid bitfield of completed chunks.

                  torrent::Download::is_open() == true;
                  torrent::Download::is_active() == false;

           o      Active

                  A  download  is  active   after    calling    torrent::Down-
                  load::start().  Only downloads that are in an open state and
                  has a valid bitfield of completed chunks can be activated.

                  torrent::Download::is_open() == true;
                  torrent::Download::is_active() == true;
                  torrent::Download::is_hash_checked() == true;

                  A  tracker  request  will  be   made   when   torrent::Down-
                  load::stop()   is  called   on an active download. It is not
                  required to wait  for  the  tracker   request   to    finish
                  before   calling   torrent::Down load::close(),  but  it  is
                  recommened so the tracker knows this client  is  not  avail-
                  able.File


       Paths

              The  paths  of files in a  Download  consists  of two parts, the
              root directory and the paths of each file. The  file  paths  are
              read  from the torrent file and  the files usually reside in the
              root directory. The root directory is by default "./" for single
              file torrents and  "./[torrent_name]/" for multifile torrents.

              // Get and set the root directory.
              std::string    torrent::Download::get_root_dir();
              void           torrent::Download::set_root_dir(const std::string& dir);

              // Get the torrent::Entry class for each file in the download.
              torrent::Entry torrent::Download::get_entry(uint32_t index);
              uint32_t       torrent::Download::get_entry_size();

              typedef std::list<std::string> torrent::Entry::Path;

              // Get and set the file path.
              std::string    torrent::Entry::get_path();
              const Path&    torrent::Entry::get_path_list();
              void           torrent::Entry::set_path_list(const Path& l);

              The   modifications  can  only  be done while the download is in
              a closed state. Modifying the file paths  will  not  change  the
              "info  hash"  part  of  the bencoded torrent associated with the
              download.


       Http handler Introduction

              LibTorrent depends on the client to handle http downloads,  thus
              the   library  does   not have a dependency on any specific http
              library.  The library provides a base class named  torrent::Http
              with  virtual member  functions  that the client must implement,
              and a sigc++ slot which must be set to create  an  instance   of
              the  derived  tor rent::Http  class  when  called.

              The  torrent::Http  class and the factory slot related functions
              can be found in the  header  "torrent/http.h".  The http handler
              should  have  reasonable connection timeouts, be nonblocking and
              not do reconnects on  failed  downloads.


       Factory Slot

              The client registers the desired factory slot  with  the  static
              torrent::Http::set_factory  member  function.  Using  sigc++ the
              client may bind values to the arguments of their  func  tion  to
              avoid  depending  on  globals.  The  factory slot must  return a
              pointer to a new instance with the base type torrent::Http,  and
              the  caller  takes  responsibility  of  deleting   the   object.
              (Note: consider  making  the cleanup a slot)


       Output Stream

              The data downloaded  by the http handler is  to  be  written  to
              torrent::Http::m_stream  which is a pointer to an std::iostream.
              The http handler must not change any of the flags on the stream.

              StartHttp::start is called by the library when it wishes to ini-
              tiate  a  http  download. Your Http derived class must implement
              this  func tion. It must be  nonblocking  and  threadsafe.  This
              means  that if a seperate thread is used for downloading then it
              must  not  emit any  signal  while  the  main  thread is  inside
              the library.

              closeHttp::close  is  used  by  the  library to stop and close a
              download.  No signals may be  emited  after  this.  Http::m_data
              should  not  be  cleared. The library may clear the Http::m_data
              pointer after this.


       Signals

              There  are  two mutually exclusive signals that are called  when
              the  download  has stopped. The signal tor rent::Http::m_signal-
              Done  is  called  if  the  download  was  successful  and   tor-
              rent::Http::m_stream contains the complete data. Or if the down-
              load   was   unsuccessful   for   some    reason,    then    tor
              rent::Http::m_signalFailed is called with an error message.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------+
       |ATTRIBUTE TYPE |  ATTRIBUTE VALUE   |
       +---------------+--------------------+
       |Availability   | library/libtorrent |
       +---------------+--------------------+
       |Stability      | Uncommitted        |
       +---------------+--------------------+
SEE ALSO
       rtorrent(1)



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source   was   downloaded  from   http://rtorrent.net/downloads/libtor-
       rent-0.13.6.tar.gz

       Further information about this software can be found on the open source
       community website at https://rakshasa.github.io/rtorrent/.



Solaris 11.4                      03 Jun 2009                    LIBTORRENT(3)