Skip to content

Events API ​

Falcon's current public event interface centers on IEventListener, TaskStatus, ProgressInfo, and FileInfo.

IEventListener ​

cpp
class IEventListener {
public:
    virtual ~IEventListener() = default;

    virtual void on_status_changed(
        TaskId task_id,
        TaskStatus old_status,
        TaskStatus new_status) {}

    virtual void on_progress(const ProgressInfo& info) {}

    virtual void on_error(
        TaskId task_id,
        const std::string& error_message) {}

    virtual void on_completed(
        TaskId task_id,
        const std::string& output_path) {}

    virtual void on_file_info(
        TaskId task_id,
        const FileInfo& info) {}
};

Unlike older design drafts, the current public event interface does not define separate event structs such as ProgressEvent or CompleteEvent.

TaskStatus ​

cpp
enum class TaskStatus {
    Pending,
    Preparing,
    Downloading,
    Paused,
    Completed,
    Failed,
    Cancelled
};

Use falcon::to_string(status) to convert a status to a string.

ProgressInfo ​

cpp
struct ProgressInfo {
    TaskId task_id = INVALID_TASK_ID;
    Bytes downloaded_bytes = 0;
    Bytes total_bytes = 0;
    Speed speed = 0;
    float progress = 0.0f;
    Duration elapsed{};
    Duration estimated_remaining{};
};

FileInfo ​

cpp
struct FileInfo {
    std::string url;
    std::string filename;
    std::string content_type;
    Bytes total_size = 0;
    bool supports_resume = false;
    TimePoint last_modified{};
};

Listener example ​

cpp
#include <falcon/falcon.hpp>
#include <iomanip>
#include <iostream>
#include <sstream>

class ConsoleListener : public falcon::IEventListener {
public:
    void on_status_changed(
        falcon::TaskId task_id,
        falcon::TaskStatus old_status,
        falcon::TaskStatus new_status) override {
        std::cout << "\n[task " << task_id << "] "
                  << falcon::to_string(old_status)
                  << " -> "
                  << falcon::to_string(new_status)
                  << '\n';
    }

    void on_progress(const falcon::ProgressInfo& info) override {
        std::cout << "\r"
                  << std::fixed << std::setprecision(1)
                  << info.progress * 100.0f << "%";
        std::cout.flush();
    }

    void on_error(
        falcon::TaskId task_id,
        const std::string& error_message) override {
        std::cerr << "\n[task " << task_id << "] " << error_message << '\n';
    }

    void on_completed(
        falcon::TaskId task_id,
        const std::string& output_path) override {
        std::cout << "\n[task " << task_id << "] completed: "
                  << output_path << '\n';
    }
};

Integrating with the engine ​

cpp
falcon::DownloadEngine engine;
ConsoleListener listener;

engine.add_listener(&listener);

auto task = engine.add_task("https://example.com/file.zip");
if (task) {
    engine.start_task(task->id());
    task->wait();
}

engine.remove_listener(&listener);

Released under the Apache 2.0 License