aria2-core 0.3.13

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
#ifndef ARIA2_RUST_H
#define ARIA2_RUST_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct Aria2RustSession Aria2RustSession;

typedef int32_t (*Aria2RustDownloadEventCallback)(Aria2RustSession *session,
                                                  uint32_t event,
                                                  uint64_t gid,
                                                  void *user_data);

typedef struct Aria2RustKeyValue {
  const char *name;
  const char *value;
} Aria2RustKeyValue;

enum {
  ARIA2_RUST_DOWNLOAD_ACTIVE = 0,
  ARIA2_RUST_DOWNLOAD_WAITING = 1,
  ARIA2_RUST_DOWNLOAD_PAUSED = 2,
  ARIA2_RUST_DOWNLOAD_COMPLETE = 3,
  ARIA2_RUST_DOWNLOAD_ERROR = 4,
  ARIA2_RUST_DOWNLOAD_REMOVED = 5
};

enum {
  ARIA2_RUST_POSITION_SET = 0,
  ARIA2_RUST_POSITION_CUR = 1,
  ARIA2_RUST_POSITION_END = 2
};

enum {
  ARIA2_RUST_EVENT_DOWNLOAD_START = 1,
  ARIA2_RUST_EVENT_DOWNLOAD_PAUSE = 2,
  ARIA2_RUST_EVENT_DOWNLOAD_STOP = 3,
  ARIA2_RUST_EVENT_DOWNLOAD_COMPLETE = 4,
  ARIA2_RUST_EVENT_DOWNLOAD_ERROR = 5,
  ARIA2_RUST_EVENT_BT_DOWNLOAD_COMPLETE = 6
};

#define ARIA2_RUST_INVALID_ARGUMENT (-1)
#define ARIA2_RUST_INTERNAL_ERROR (-2)
#define ARIA2_RUST_BUFFER_TOO_SMALL (-3)
#define ARIA2_RUST_TIMEOUT (-4)

typedef struct Aria2RustDownloadInfo {
  uint32_t status;
  uint64_t total_length;
  uint64_t completed_length;
  uint64_t upload_length;
  uint64_t download_speed;
  uint64_t upload_speed;
  uint32_t error_code;
} Aria2RustDownloadInfo;

typedef struct Aria2RustFileInfo {
  uint64_t length;
  uint64_t completed_length;
  uint8_t selected;
} Aria2RustFileInfo;

typedef struct Aria2RustGlobalStat {
  uint64_t download_speed;
  uint64_t upload_speed;
  uint64_t num_active;
  uint64_t num_waiting;
  uint64_t num_stopped;
} Aria2RustGlobalStat;

int32_t aria2_rust_library_init(void);
int32_t aria2_rust_library_deinit(void);

/* Unknown options are ignored. Invalid known values return NULL.
 * user_data is reserved here; use the callback-enabled constructor to receive
 * it with lifecycle events. */
Aria2RustSession *aria2_rust_session_new(const Aria2RustKeyValue *options,
                                          size_t option_count,
                                          void *user_data);
/* The callback runs synchronously on the engine event thread, must return
 * promptly, must not unwind, and must not call the same session's C API.
 * user_data is borrowed until session_final returns. Callback return values
 * are ignored. Event values use the aria2 numbering above. */
Aria2RustSession *aria2_rust_session_new_with_download_event_callback(
    const Aria2RustKeyValue *options, size_t option_count,
    Aria2RustDownloadEventCallback callback, void *user_data);
int32_t aria2_rust_session_final(Aria2RustSession *session);

/* mode 0 waits for all current downloads; mode 1 runs one event turn. */
int32_t aria2_rust_run(Aria2RustSession *session, uint32_t mode);
/* timeout_ms == 0 waits indefinitely; timeout only stops this call. */
int32_t aria2_rust_wait_download(Aria2RustSession *session, uint64_t gid,
                                  uint64_t timeout_ms,
                                  Aria2RustDownloadInfo *output);

int32_t aria2_rust_add_uri(Aria2RustSession *session, const char *const *uris,
                            size_t uri_count,
                            const Aria2RustKeyValue *options,
                            size_t option_count, uint64_t *gid_out);
int32_t aria2_rust_add_torrent(
    Aria2RustSession *session, const uint8_t *torrent_data,
    size_t torrent_length, const char *const *web_seed_uris,
    size_t web_seed_uri_count, const Aria2RustKeyValue *options,
    size_t option_count, uint64_t *gid_out);
int32_t aria2_rust_add_metalink(
    Aria2RustSession *session, const uint8_t *metalink_data,
    size_t data_length, const Aria2RustKeyValue *options,
    size_t option_count, uint64_t *gids_out, size_t gid_capacity,
    size_t *gid_count_out);
int32_t aria2_rust_remove(Aria2RustSession *session, uint64_t gid,
                          uint8_t force);
int32_t aria2_rust_pause(Aria2RustSession *session, uint64_t gid,
                         uint8_t force);
int32_t aria2_rust_unpause(Aria2RustSession *session, uint64_t gid);
int32_t aria2_rust_pause_all(Aria2RustSession *session, uint8_t force);
int32_t aria2_rust_unpause_all(Aria2RustSession *session);
int32_t aria2_rust_change_position(Aria2RustSession *session, uint64_t gid,
                                   int32_t position, uint32_t mode,
                                   size_t *position_out);
int32_t aria2_rust_change_option(Aria2RustSession *session, uint64_t gid,
                                 const Aria2RustKeyValue *options,
                                 size_t option_count);
int32_t aria2_rust_change_global_option(Aria2RustSession *session,
                                        const Aria2RustKeyValue *options,
                                        size_t option_count);

int32_t aria2_rust_get_download_info(Aria2RustSession *session, uint64_t gid,
                                     Aria2RustDownloadInfo *output);
/* File indexes are 1-based, matching aria2.getFiles and libaria2. */
size_t aria2_rust_get_file_count(Aria2RustSession *session, uint64_t gid);
int32_t aria2_rust_get_file_info(Aria2RustSession *session, uint64_t gid,
                                 size_t file_index,
                                 Aria2RustFileInfo *output);
/* Returns required bytes including NUL; returns 0 when the file is absent. */
size_t aria2_rust_get_file_path(Aria2RustSession *session, uint64_t gid,
                                size_t file_index, char *output,
                                size_t capacity);
int32_t aria2_rust_get_global_stat(Aria2RustSession *session,
                                   Aria2RustGlobalStat *output);
/* Returns the required number of entries. Pass NULL/0 to query the size. */
size_t aria2_rust_get_active_downloads(Aria2RustSession *session,
                                       uint64_t *output, size_t capacity);

/* Returns required bytes including NUL; no write occurs on a short buffer. */
size_t aria2_rust_gid_to_hex(uint64_t gid, char *output, size_t capacity);
uint64_t aria2_rust_hex_to_gid(const char *input);
uint8_t aria2_rust_is_null_gid(uint64_t gid);
size_t aria2_rust_last_error(Aria2RustSession *session, char *output,
                             size_t capacity);

#ifdef __cplusplus
}
#endif

#endif /* ARIA2_RUST_H */