TAPI to manage ctorrent (tapi_ctorrent)

Overview

TAPI to manage ctorrent - a BitTorrent client. More…

TAPI to manage bttrack torrent tracker (tapi_bttrack)

// typedefs

typedef struct tapi_ctorrent_app tapi_ctorrent_app;
typedef struct tapi_ctorrent_opt tapi_ctorrent_opt;

// structs

struct tapi_ctorrent_opt;

// global variables

const tapi_ctorrent_opt tapi_ctorrent_default_opt;

// global functions

te_errno tapi_ctorrent_create_metainfo_file(tapi_job_factory_t* factory, tapi_bttrack_app* tracker, const char* metainfo_file, const char* target, int timeout_ms);
te_errno tapi_ctorrent_create_app(tapi_job_factory_t* factory, tapi_ctorrent_opt* opt, tapi_ctorrent_app** app);
te_errno tapi_ctorrent_start(tapi_ctorrent_app* app);
te_errno tapi_ctorrent_kill(tapi_ctorrent_app* app, int signum);
te_errno tapi_ctorrent_stop(tapi_ctorrent_app* app, int timeout_ms);
te_errno tapi_ctorrent_destroy(tapi_ctorrent_app* app, int timeout_ms);
te_errno tapi_ctorrent_check_completion(tapi_ctorrent_app* app, int receive_timeout_ms, bool* completed);
te_errno tapi_ctorrent_wait_completion(tapi_ctorrent_app* app, int receive_timeout_ms);

Detailed Documentation

TAPI to manage ctorrent - a BitTorrent client.

Typedefs

typedef struct tapi_ctorrent_app tapi_ctorrent_app

ctorrent instance handle

typedef struct tapi_ctorrent_opt tapi_ctorrent_opt

ctorrent specific options

Global Variables

const tapi_ctorrent_opt tapi_ctorrent_default_opt

Default ctorrent’s options initializer

Global Functions

te_errno tapi_ctorrent_create_metainfo_file(tapi_job_factory_t* factory, tapi_bttrack_app* tracker, const char* metainfo_file, const char* target, int timeout_ms)

Create metainfo (.torrent) file.

Parameters:

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.

Returns:

Status code.

te_errno tapi_ctorrent_create_app(tapi_job_factory_t* factory, tapi_ctorrent_opt* opt, tapi_ctorrent_app** app)

Create ctorrent app.

It is always better to specify 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.

Parameters:

factory	Job factory.
opt	ctorrent options.
app	ctorrent app handle.

Returns:

Status code.

te_errno tapi_ctorrent_start(tapi_ctorrent_app* app)

Start ctorrent. All required data will be downloaded, seeding will be initiated (i.e. the host will become a peer).

Parameters:

app	ctorrent app handle.

Returns:

Status code.

te_errno tapi_ctorrent_kill(tapi_ctorrent_app* app, int signum)

Send a signal to ctorrent.

Parameters:

app	ctorrent app handle.
signum	Signal to send.

Returns:

Status code.

te_errno tapi_ctorrent_stop(tapi_ctorrent_app* app, int timeout_ms)

Stop ctorrent. It can be started over with tapi_ctorrent_start(). Before termination, ctorrent app will try to send its last report to a tracker, it might require some time.

Parameters:

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.

Returns:

Status code.

te_errno tapi_ctorrent_destroy(tapi_ctorrent_app* app, int timeout_ms)

Destroy ctorrent.

Parameters:

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.

Returns:

Status code.

te_errno tapi_ctorrent_check_completion(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 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).

Parameters:

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.

Returns:

Status code.

te_errno tapi_ctorrent_wait_completion(tapi_ctorrent_app* app, int receive_timeout_ms)

Wait for the download to complete.

Parameters:

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.

Returns:

Status code.