| libtorrent

# libtorrent Examples

Author: | Arvid Norberg, arvid@libtorrent.org
Version: | 1.1.0

Table of contents

- examples
  - simple client
  - make_torrent
  - dump_torrent

# examples

Except for the example programs in this manual, there's also a bigger example of a (little bit) more complete client, `client_test`. There are separate instructions for how to use it here if you'd like to try it. Note that building `client_test` also requires boost.regex and boost.program_options library.

## simple client

This is a simple client. It doesn't have much output to keep it simple:

    #include <stdlib.h>
    #include <boost/make_shared.hpp>
    #include "libtorrent/entry.hpp"
    #include "libtorrent/bencode.hpp"
    #include "libtorrent/session.hpp"

    int main(int argc, char* argv[])
    {
      using namespace libtorrent;
      namespace lt = libtorrent;

      if (argc != 2)
      {
        fputs("usage: ./simple_client torrent-file\n"
          "to stop the client, press return.\n", stderr);
        return 1;
      }

      settings_pack sett;
      sett.set_str(settings_pack::listen_interfaces, "0.0.0.0:6881");
      lt::session s(sett);
      error_code ec;
      if (ec)
      {
        fprintf(stderr, "failed to open listen socket: %s\n", ec.message().c_str());
        return 1;
      }
      add_torrent_params p;
      p.save_path = "./";
      p.ti = boost::make_shared<torrent_info>(std::string(argv[1]), boost::ref(ec), 0);
      if (ec)
      {
        fprintf(stderr, "%s\n", ec.message().c_str());
        return 1;
      }
      s.add_torrent(p, ec);
      if (ec)
      {
        fprintf(stderr, "%s\n", ec.message().c_str());
        return 1;
      }

      // wait for the user to end
      char a;
      scanf("%c\n", &a);
      return 0;
    }

## make_torrent

Shows how to create a torrent from a directory tree:

    #include "libtorrent/entry.hpp"
    #include "libtorrent/bencode.hpp"
    #include "libtorrent/torrent_info.hpp"
    #include "libtorrent/file.hpp"
    #include "libtorrent/storage.hpp"
    #include "libtorrent/hasher.hpp"
    #include "libtorrent/create_torrent.hpp"
    #include "libtorrent/file.hpp"
    #include "libtorrent/file_pool.hpp"
    #include "libtorrent/hex.hpp" // for from_hex

    #include <boost/bind.hpp>

    #ifdef TORRENT_WINDOWS
    #include <direct.h> // for _getcwd
    #endif

    using namespace libtorrent;

    int load_file(std::string const& filename, std::vector<char>& v, libtorrent::error_code& ec, int limit = 8000000)
    {
      ec.clear();
      FILE* f = fopen(filename.c_str(), "rb");
      if (f == NULL)
      {
        ec.assign(errno, boost::system::generic_category());
        return -1;
      }

      int r = fseek(f, 0, SEEK_END);
      if (r != 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }
      long s = ftell(f);
      if (s < 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      if (s > limit)
      {
        fclose(f);
        return -2;
      }

      r = fseek(f, 0, SEEK_SET);
      if (r != 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      v.resize(s);
      if (s == 0)
      {
        fclose(f);
        return 0;
      }

      r = fread(&v[0], 1, v.size(), f);
      if (r < 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      fclose(f);

      if (r != s) return -3;

      return 0;
    }

    std::string branch_path(std::string const& f)
    {
      if (f.empty()) return f;

    #ifdef TORRENT_WINDOWS
      if (f == "\\\\") return "";
    #endif
      if (f == "/") return "";

      int len = f.size();
      // if the last character is / or \ ignore it
      if (f[len-1] == '/' || f[len-1] == '\\') --len;
      while (len > 0)
      {
        --len;
        if (f[len] == '/' || f[len] == '\\')
          break;
      }

      if (f[len] == '/' || f[len] == '\\') ++len;
      return std::string(f.c_str(), len);
    }

    // do not include files and folders whose
    // name starts with a .
    bool file_filter(std::string const& f)
    {
      if (f.empty()) return false;

      char const* first = f.c_str();
      char const* sep = strrchr(first, '/');
    #if defined(TORRENT_WINDOWS) || defined(TORRENT_OS2)
      char const* altsep = strrchr(first, '\\');
      if (sep == NULL || altsep > sep) sep = altsep;
    #endif
      // if there is no parent path, just set 'sep'
      // to point to the filename.
      // if there is a parent path, skip the '/' character
      if (sep == NULL) sep = first;
      else ++sep;

      // return false if the first character of the filename is a .
      if (sep[0] == '.') return false;

      fprintf(stderr, "%s\n", f.c_str());
      return true;
    }

    void print_progress(int i, int num)
    {
      fprintf(stderr, "\r%d/%d", i+1, num);
    }

    void print_usage()
    {
      fputs("usage: make_torrent FILE [OPTIONS]\n"
        "\n"
        "Generates a torrent file from the specified file\n"
        "or directory and writes it to standard out\n\n"
        "OPTIONS:\n"
        "-m file       generate a merkle hash tree torrent.\n"
        "              merkle torrents require client support\n"
        "              the resulting full merkle tree is written to\n"
        "              the specified file\n"
        "-w url        adds a web seed to the torrent with\n"
        "              the specified url\n"
        "-t url        adds the specified tracker to the\n"
        "              torrent. For multiple trackers, specify more\n"
        "              -t options\n"
        "-c comment    sets the comment to the specified string\n"
        "-C creator    sets the created-by field to the specified string\n"
        "-p bytes      enables padding files. Files larger\n"
        "              than bytes will be piece-aligned\n"
        "-s bytes      specifies a piece size for the torrent\n"
        "              This has to be a multiple of 16 kiB\n"
        "-l            Don't follow symlinks, instead encode them as\n"
        "              links in the torrent file\n"
        "-o file       specifies the output filename of the torrent file\n"
        "              If this is not specified, the torrent file is\n"
        "              printed to the standard out, except on windows\n"
        "              where the filename defaults to a.torrent\n"
        "-r file       add root certificate to the torrent, to verify\n"
        "              the HTTPS tracker\n"
        "-S info-hash  add a similar torrent by info-hash. The similar\n"
        "              torrent is expected to share some files with this one\n"
        "-L collection add a collection name to this torrent. Other torrents\n"
        "              in the same collection is expected to share files\n"
        "              with this one.\n"
        "-M            make the torrent compatible with mutable torrents\n"
        "              this means aligning large files and pad them in order\n"
        "              for piece hashes to uniquely indentify a file without\n"
        "              overlap\n"
        , stderr);
    }

    int main(int argc, char* argv[])
    {
      using namespace libtorrent;

      std::string creator_str = "libtorrent";
      std::string comment_str;

      if (argc < 2)
      {
        print_usage();
        return 1;
      }

    #ifndef BOOST_NO_EXCEPTIONS
      try
      {
    #endif
        std::vector<std::string> web_seeds;
        std::vector<std::string> trackers;
        std::vector<std::string> collections;
        std::vector<sha1_hash> similar;
        int pad_file_limit = -1;
        int piece_size = 0;
        int flags = 0;
        std::string root_cert;

        std::string outfile;
        std::string merklefile;
    #ifdef TORRENT_WINDOWS
        // don't ever write binary data to the console on windows
        // it will just be interpreted as text and corrupted
        outfile = "a.torrent";
    #endif

        for (int i = 2; i < argc; ++i)
        {
          if (argv[i][0] != '-')
          {
            print_usage();
            return 1;
          }

          switch (argv[i][1])
          {
            case 'w':
              ++i;
              web_seeds.push_back(argv[i]);
              break;
            case 't':
              ++i;
              trackers.push_back(argv[i]);
              break;
            case 'M':
              flags |= create_torrent::mutable_torrent_support;
              pad_file_limit = 0x4000;
              break;
            case 'p':
              ++i;
              pad_file_limit = atoi(argv[i]);
              flags |= create_torrent::optimize;
              break;
            case 's':
              ++i;
              piece_size = atoi(argv[i]);
              break;
            case 'm':
              ++i;
              merklefile = argv[i];
              flags |= create_torrent::merkle;
              break;
            case 'o':
              ++i;
              outfile = argv[i];
              break;
            case 'l':
              flags |= create_torrent::symlinks;
              break;
            case 'C':
              ++i;
              creator_str = argv[i];
              break;
            case 'c':
              ++i;
              comment_str = argv[i];
              break;
            case 'r':
              ++i;
              root_cert = argv[i];
              break;
            case 'S':
              {
              ++i;
              if (strlen(argv[i]) != 40)
              {
                fprintf(stderr, "invalid info-hash for -S. "
                  "Expected 40 hex characters\n");
                print_usage();
                return 1;
              }
              sha1_hash ih;
              if (!from_hex(argv[i], 40, (char*)&ih[0]))
              {
                fprintf(stderr, "invalid info-hash for -S\n");
                print_usage();
                return 1;
              }
              similar.push_back(ih);
              }
              break;
            case 'L':
              ++i;
              collections.push_back(argv[i]);
              break;
            default:
              print_usage();
              return 1;
          }
        }

        file_storage fs;
        std::string full_path = argv[1];
    #ifdef TORRENT_WINDOWS
        if (full_path[1] != ':')
    #else
        if (full_path[0] != '/')
    #endif
        {
          char cwd[TORRENT_MAX_PATH];
    #ifdef TORRENT_WINDOWS
          _getcwd(cwd, sizeof(cwd));
          full_path = cwd + ("\\" + full_path);
    #else
          getcwd(cwd, sizeof(cwd));
          full_path = cwd + ("/" + full_path);
    #endif
        }

        add_files(fs, full_path, file_filter, flags);
        if (fs.num_files() == 0)
        {
          fputs("no files specified.\n", stderr);
          return 1;
        }

        create_torrent t(fs, piece_size, pad_file_limit, flags);
        int tier = 0;
        for (std::vector<std::string>::iterator i = trackers.begin()
          , end(trackers.end()); i != end; ++i, ++tier)
          t.add_tracker(*i, tier);

        for (std::vector<std::string>::iterator i = web_seeds.begin()
          , end(web_seeds.end()); i != end; ++i)
          t.add_url_seed(*i);

        for (std::vector<std::string>::iterator i = collections.begin()
          , end(collections.end()); i != end; ++i)
          t.add_collection(*i);

        for (std::vector<sha1_hash>::iterator i = similar.begin()
          , end(similar.end()); i != end; ++i)
          t.add_similar_torrent(*i);

        error_code ec;
        set_piece_hashes(t, branch_path(full_path)
          , boost::bind(&print_progress, _1, t.num_pieces()), ec);
        if (ec)
        {
          fprintf(stderr, "%s\n", ec.message().c_str());
          return 1;
        }

        fprintf(stderr, "\n");
        t.set_creator(creator_str.c_str());
        if (!comment_str.empty())
          t.set_comment(comment_str.c_str());

        if (!root_cert.empty())
        {
          std::vector<char> pem;
          load_file(root_cert, pem, ec, 10000);
          if (ec)
          {
            fprintf(stderr, "failed to load root certificate for tracker: %s\n", ec.message().c_str());
          }
          else
          {
            t.set_root_cert(std::string(&pem[0], pem.size()));
          }
        }

        // create the torrent and print it to stdout
        std::vector<char> torrent;
        bencode(back_inserter(torrent), t.generate());
        FILE* output = stdout;
        if (!outfile.empty())
          output = fopen(outfile.c_str(), "wb+");
        if (output == NULL)
        {
          fprintf(stderr, "failed to open file \"%s\": (%d) %s\n"
            , outfile.c_str(), errno, strerror(errno));
          return 1;
        }
        fwrite(&torrent[0], 1, torrent.size(), output);

        if (output != stdout)
          fclose(output);

        if (!merklefile.empty())
        {
          output = fopen(merklefile.c_str(), "wb+");
          if (output == NULL)
          {
            fprintf(stderr, "failed to open file \"%s\": (%d) %s\n"
              , merklefile.c_str(), errno, strerror(errno));
            return 1;
          }
          int ret = fwrite(&t.merkle_tree()[0], 20, t.merkle_tree().size(), output);
          if (ret != int(t.merkle_tree().size()))
          {
            fprintf(stderr, "failed to write %s: (%d) %s\n"
              , merklefile.c_str(), errno, strerror(errno));
          }
          fclose(output);
        }

    #ifndef BOOST_NO_EXCEPTIONS
      }
      catch (std::exception& e)
      {
        fprintf(stderr, "%s\n", e.what());
      }
    #endif

      return 0;
    }

## dump_torrent

This is an example of a program that will take a torrent-file as a parameter and print information about it to std out:

    #include "libtorrent/entry.hpp"
    #include "libtorrent/bencode.hpp"
    #include "libtorrent/torrent_info.hpp"
    #include "libtorrent/bdecode.hpp"
    #include "libtorrent/magnet_uri.hpp"

    int load_file(std::string const& filename, std::vector<char>& v
      , libtorrent::error_code& ec, int limit = 8000000)
    {
      ec.clear();
      FILE* f = fopen(filename.c_str(), "rb");
      if (f == NULL)
      {
        ec.assign(errno, boost::system::generic_category());
        return -1;
      }

      int r = fseek(f, 0, SEEK_END);
      if (r != 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }
      long s = ftell(f);
      if (s < 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      if (s > limit)
      {
        fclose(f);
        return -2;
      }

      r = fseek(f, 0, SEEK_SET);
      if (r != 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      v.resize(s);
      if (s == 0)
      {
        fclose(f);
        return 0;
      }

      r = fread(&v[0], 1, v.size(), f);
      if (r < 0)
      {
        ec.assign(errno, boost::system::generic_category());
        fclose(f);
        return -1;
      }

      fclose(f);

      if (r != s) return -3;

      return 0;
    }

    int main(int argc, char* argv[])
    {
      using namespace libtorrent;

      if (argc < 2 || argc > 4)
      {
        fputs("usage: dump_torrent torrent-file [total-items-limit] [recursion-limit]\n", stderr);
        return 1;
      }

      int item_limit = 1000000;
      int depth_limit = 1000;

      if (argc > 2) item_limit = atoi(argv[2]);
      if (argc > 3) depth_limit = atoi(argv[3]);

      std::vector<char> buf;
      error_code ec;
      int ret = load_file(argv[1], buf, ec, 40 * 1000000);
      if (ret == -1)
      {
        fprintf(stderr, "file too big, aborting\n");
        return 1;
      }

      if (ret != 0)
      {
        fprintf(stderr, "failed to load file: %s\n", ec.message().c_str());
        return 1;
      }
      bdecode_node e;
      int pos = -1;
      printf("decoding. recursion limit: %d total item count limit: %d\n"
        , depth_limit, item_limit);
      ret = bdecode(&buf[0], &buf[0] + buf.size(), e, ec, &pos
        , depth_limit, item_limit);

      printf("\n\n----- raw info -----\n\n%s\n", print_entry(e).c_str());

      if (ret != 0)
      {
        fprintf(stderr, "failed to decode: '%s' at character: %d\n", ec.message().c_str(), pos);
        return 1;
      }

      torrent_info t(e, ec);
      if (ec)
      {
        fprintf(stderr, "%s\n", ec.message().c_str());
        return 1;
      }
      e.clear();
      std::vector<char>().swap(buf);

      // print info about torrent
      printf("\n\n----- torrent file info -----\n\n"
        "nodes:\n");

      typedef std::vector<std::pair<std::string, int> > node_vec;
      node_vec const& nodes = t.nodes();
      for (node_vec::const_iterator i = nodes.begin(), end(nodes.end());
        i != end; ++i)
      {
        printf("%s: %d\n", i->first.c_str(), i->second);
      }
      puts("trackers:\n");
      for (std::vector<announce_entry>::const_iterator i = t.trackers().begin();
        i != t.trackers().end(); ++i)
      {
        printf("%2d: %s\n", i->tier, i->url.c_str());
      }

      char ih[41];
      to_hex((char const*)&t.info_hash()[0], 20, ih);
      printf("number of pieces: %d\n"
        "piece length: %d\n"
        "info hash: %s\n"
        "comment: %s\n"
        "created by: %s\n"
        "magnet link: %s\n"
        "name: %s\n"
        "number of files: %d\n"
        "files:\n"
        , t.num_pieces()
        , t.piece_length()
        , ih
        , t.comment().c_str()
        , t.creator().c_str()
        , make_magnet_uri(t).c_str()
        , t.name().c_str()
        , t.num_files());
      file_storage const& st = t.files();
      for (int i = 0; i < st.num_files(); ++i)
      {
        int first = st.map_file(i, 0, 0).piece;
        int last = st.map_file(i, (std::max)(boost::int64_t(st.file_size(i))-1, boost::int64_t(0)), 0).piece;
        int flags = st.file_flags(i);
        printf(" %8" PRIx64 " %11" PRId64 " %c%c%c%c [ %5d, %5d ] %7u %s %s %s%s\n"
          , st.file_offset(i)
          , st.file_size(i)
          , ((flags & file_storage::flag_pad_file)?'p':'-')
          , ((flags & file_storage::flag_executable)?'x':'-')
          , ((flags & file_storage::flag_hidden)?'h':'-')
          , ((flags & file_storage::flag_symlink)?'l':'-')
          , first, last
          , boost::uint32_t(st.mtime(i))
          , st.hash(i) != sha1_hash(0) ? to_hex(st.hash(i).to_string()).c_str() : ""
          , st.file_path(i).c_str()
          , (flags & file_storage::flag_symlink) ? "-> " : ""
          , (flags & file_storage::flag_symlink) ? st.symlink(i).c_str() : "");
      }

      return 0;
    }