:orphan: .. index:: pair: group; TAPI to manage ctorrent (tapi_ctorrent) .. _doxid-group__tapi__ctorrent: TAPI to manage ctorrent (tapi_ctorrent) ======================================= .. toctree:: :hidden: group_tapi_bttrack.rst struct_tapi_ctorrent_opt.rst Overview ~~~~~~~~ TAPI to manage ctorrent - a BitTorrent client. :ref:`More...` | :ref:`TAPI to manage bttrack torrent tracker (tapi_bttrack)` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`tapi_ctorrent_app` :ref:`tapi_ctorrent_app`; typedef struct :ref:`tapi_ctorrent_opt` :ref:`tapi_ctorrent_opt`; // structs struct :ref:`tapi_ctorrent_opt`; // global variables const :ref:`tapi_ctorrent_opt` :ref:`tapi_ctorrent_default_opt`; // global functions :ref:`te_errno` :ref:`tapi_ctorrent_create_metainfo_file`(:ref:`tapi_job_factory_t`* factory, :ref:`tapi_bttrack_app`* tracker, const char* metainfo_file, const char* target, int timeout_ms); :ref:`te_errno` :ref:`tapi_ctorrent_create_app`(:ref:`tapi_job_factory_t`* factory, :ref:`tapi_ctorrent_opt`* opt, :ref:`tapi_ctorrent_app`** app); :ref:`te_errno` :ref:`tapi_ctorrent_start`(:ref:`tapi_ctorrent_app`* app); :ref:`te_errno` :ref:`tapi_ctorrent_kill`(:ref:`tapi_ctorrent_app`* app, int signum); :ref:`te_errno` :ref:`tapi_ctorrent_stop`(:ref:`tapi_ctorrent_app`* app, int timeout_ms); :ref:`te_errno` :ref:`tapi_ctorrent_destroy`(:ref:`tapi_ctorrent_app`* app, int timeout_ms); :ref:`te_errno` :ref:`tapi_ctorrent_check_completion`(:ref:`tapi_ctorrent_app`* app, int receive_timeout_ms, bool* completed); :ref:`te_errno` :ref:`tapi_ctorrent_wait_completion`(:ref:`tapi_ctorrent_app`* app, int receive_timeout_ms); .. _details-group__tapi__ctorrent: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ TAPI to manage ctorrent - a BitTorrent client. Copyright (C) 2021-2022 OKTET Labs Ltd. All rights reserved. Typedefs -------- .. index:: pair: typedef; tapi_ctorrent_app .. _doxid-group__tapi__ctorrent_1ga29a9c7f2e6ebf8d47dda9e2a2acfa289: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_ctorrent_app` tapi_ctorrent_app ctorrent instance handle .. index:: pair: typedef; tapi_ctorrent_opt .. _doxid-group__tapi__ctorrent_1gad6f73b2bb51dcc9c880aa0778f3f68e8: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_ctorrent_opt` tapi_ctorrent_opt ctorrent specific options Global Variables ---------------- .. index:: pair: variable; tapi_ctorrent_default_opt .. _doxid-group__tapi__ctorrent_1gaa34a7aa4235a3e3b59413c262690f615: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`tapi_ctorrent_opt` tapi_ctorrent_default_opt Default ctorrent's options initializer Global Functions ---------------- .. index:: pair: function; tapi_ctorrent_create_metainfo_file .. _doxid-group__tapi__ctorrent_1ga724a43417cc9da7ad73208c04b731c10: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_create_metainfo_file(:ref:`tapi_job_factory_t`* factory, :ref:`tapi_bttrack_app`* tracker, const char* metainfo_file, const char* target, int timeout_ms) Create metainfo (.torrent) file. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - factory - Job factory. * - tracker - Torrent tracker handle. * - metainfo_file - Name (or pathname) of a file that will be created. The file will contain all necessary information to share data stored in target. * - target - Name (or pathname) of a file or a directory that will be shared. * - timeout_ms - Timeout to wait for creation to complete. Note that the bigger file is, the bigger amount of time is required. Use a negative number for a default timeout. * - TE_EEXIST - *metainfo_file* already exists on TA. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_create_app .. _doxid-group__tapi__ctorrent_1gaae7513b967ab7e5ac356533b177d93c7: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_create_app(:ref:`tapi_job_factory_t`* factory, :ref:`tapi_ctorrent_opt`* opt, :ref:`tapi_ctorrent_app`** app) Create ctorrent app. It is always better to specify :ref:`tapi_ctorrent_opt::save_to_file ` option even when creating an app for an original seeder. Otherwise, it won't find a file to seed if it is not in the current directory. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - factory - Job factory. * - opt - ctorrent options. * - app - ctorrent app handle. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_start .. _doxid-group__tapi__ctorrent_1ga8a884dad556ebe0e21d2be3f2029e07f: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_start(:ref:`tapi_ctorrent_app`* app) Start ctorrent. All required data will be downloaded, seeding will be initiated (i.e. the host will become a peer). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_kill .. _doxid-group__tapi__ctorrent_1gad52ecb71ed46284ff5bcd192068f1a08: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_kill(:ref:`tapi_ctorrent_app`* app, int signum) Send a signal to ctorrent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. * - signum - Signal to send. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_stop .. _doxid-group__tapi__ctorrent_1ga1da6c45e1f77e97b875b33fb15b21dfb: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_stop(:ref:`tapi_ctorrent_app`* app, int timeout_ms) Stop ctorrent. It can be started over with :ref:`tapi_ctorrent_start() `. Before termination, ctorrent app will try to send its last report to a tracker, it might require some time. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. * - timeout_ms - Timeout of graceful termination. After the timeout expiration the job will be killed with ``SIGKILL``. Negative means a default timeout. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_destroy .. _doxid-group__tapi__ctorrent_1ga26fe7ac975ad9ea02ffd7233e4a550db: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_destroy(:ref:`tapi_ctorrent_app`* app, int timeout_ms) Destroy ctorrent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. * - timeout_ms - Timeout of graceful termination. After the timeout expiration the job will be killed with ``SIGKILL``. Negative means a default timeout. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_check_completion .. _doxid-group__tapi__ctorrent_1ga91f1448415a90e06f7f38d730a917600: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_check_completion(:ref:`tapi_ctorrent_app`* app, int receive_timeout_ms, bool* completed) Check if the download is completed. The download is considered completed if the file specified by :ref:`tapi_ctorrent_opt::save_to_file ` contains all required pieces, so for original seeder the download is always completed. Sometimes ctorrent may check its pieces integrity and do not display its status line for some time. The bigger torrent is, the more time is required to check the integrity, so be sure to set big enough timeout (or use a negative value for a default timeout). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. * - receive_timeout_ms - Timeout to receive status data from ctorrent. * - completed - ``true`` if the download is completed. * - TE_ETIMEDOUT - ctorrent has not displayed its status line for too long. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_ctorrent_wait_completion .. _doxid-group__tapi__ctorrent_1ga41fdf5a4c5ee17b264a264e7269bcfd6: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_ctorrent_wait_completion(:ref:`tapi_ctorrent_app`* app, int receive_timeout_ms) Wait for the download to complete. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - app - ctorrent app handle. * - receive_timeout_ms - Timeout to receive status data from ctorrent. * - TE_ETIMEDOUT - ctorrent has not displayed its status line for too long. .. rubric:: Returns: Status code. .. rubric:: See also: :ref:`tapi_ctorrent_check_completion() `