PluginInterface.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Vincent Leroy
// SPDX-License-Identifier: MIT
//
// This file is part of dfx.
//
// Licensed under the MIT License. See the LICENSE file in the project root
// for full license information.
 
#pragma once

 
#ifdef __cplusplus
extern "C"
{
#endif
 
// Standard includes
#include <stdint.h>
#include <stddef.h>


#define DFX_LOG_LEVEL_TRACE    0
#define DFX_LOG_LEVEL_DEBUG    1
#define DFX_LOG_LEVEL_INFO     2
#define DFX_LOG_LEVEL_WARN     3
#define DFX_LOG_LEVEL_ERROR    4
#define DFX_LOG_LEVEL_CRITICAL 5



typedef void * dfx_transport_handle_t;

typedef void * dfx_node_handle_t;

typedef void * dfx_node_api_handle_t;

typedef void * dfx_env_handle_t;

typedef void * dfx_poller_handle_t;

typedef void * dfx_message_handle_t;

typedef void * dfx_registration_handle_t;

typedef void * dfx_task_handle_t;

typedef void * dfx_task_executor_handle_t;



typedef uint32_t dfx_event_interest_t;

#define DFX_EVENT_READ       0x01u
#define DFX_EVENT_WRITE      0x02u
#define DFX_EVENT_READ_CLOSE 0x04u

#define DFX_EVENT_MASK (DFX_EVENT_READ | DFX_EVENT_WRITE | DFX_EVENT_READ_CLOSE)



typedef uint32_t dfx_event_trigger_t;

#define DFX_EVENT_READABLE    0x01u
#define DFX_EVENT_WRITABLE    0x02u
#define DFX_EVENT_PEER_CLOSED 0x04u
#define DFX_EVENT_HANGUP      0x08u
#define DFX_EVENT_ERROR       0x10u



typedef uint32_t dfx_port_kind_t;

#define DFX_KIND_INVALID UINT32_MAX
#define DFX_KIND_DATA    0u
#define DFX_KIND_CONTROL 1u


#define DFX_OK    0
#define DFX_ERROR -1
#define DFX_INVALID_PORT_ID UINT32_MAX
#define DFX_INVALID_SIZE SIZE_MAX

typedef void (*dfx_fd_callback_t)(int fd, dfx_event_trigger_t events, void * user_data);

typedef void (*dfx_callback_t)(void * user_data);

typedef int (*dfx_on_message_received_t)(uint8_t const * message, size_t size, void * host_ctx);

typedef struct
{
    dfx_env_handle_t handle; 

    void (*log)(dfx_env_handle_t handle, int level, char const * msg);

    char const * (*get_plugin_dir)(dfx_env_handle_t handle);
} dfx_env_api_t;

typedef struct
{
    dfx_poller_handle_t handle; 

    int (*register_fd)(dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests, dfx_fd_callback_t cb, void * user_data);

    int (*update_fd)(dfx_poller_handle_t handle, int fd, dfx_event_interest_t interests);

    void (*deregister_fd)(dfx_poller_handle_t handle, int fd);

    int (*defer_call)(dfx_poller_handle_t handle, dfx_callback_t cb, void * user_data);
} dfx_poller_api_t;

typedef struct
{
    dfx_task_handle_t handle;

    int (*get_priority)(dfx_task_handle_t handle);

    int (*run)(dfx_task_handle_t handle);
} dfx_task_api_t;

typedef struct
{
    dfx_task_executor_handle_t (*build)(void);

    void (*destroy)(dfx_task_executor_handle_t handle);

    int (*push_task)(dfx_task_executor_handle_t handle, dfx_task_api_t const * task_api, size_t task_api_size);
} dfx_task_executor_interface_t;

typedef struct
{
    dfx_message_handle_t handle;

    dfx_port_kind_t (*get_kind)(dfx_message_handle_t handle);

    int (*get_uuid)(dfx_message_handle_t handle, uint8_t out_uuid[16]);

    int (*get_parent_uuid)(dfx_message_handle_t handle, uint8_t out_uuid[16]);

    size_t (*get_mime_type)(dfx_message_handle_t handle, char * out_buf, size_t buf_size);

    int (*get_timestamp)(dfx_message_handle_t handle, struct timespec * tp);

    size_t (*get_path_count)(dfx_message_handle_t handle);

    size_t (*get_path_step)(dfx_message_handle_t handle, size_t index, char * out_buf, size_t buf_size);

    int (*get_data)(dfx_message_handle_t handle, uint8_t const ** out_data, size_t * out_size);

    size_t (*get_ctrl_cmd)(dfx_message_handle_t handle, char * out_buf, size_t buf_size);

    size_t (*get_ctrl_params)(dfx_message_handle_t handle, char * out_buf, size_t buf_size);

    int (*get_ctrl_version)(dfx_message_handle_t handle);
} dfx_message_api_t;

typedef struct
{
    dfx_node_api_handle_t handle;

    int (*notify_stopped)(dfx_node_api_handle_t handle);

    int (*assign_task_executor)(dfx_node_api_handle_t handle, dfx_task_executor_interface_t const * executor, size_t executor_size);

    int (*revoke_task_executor)(dfx_node_api_handle_t handle);

    uint32_t (*register_input_port)(dfx_node_api_handle_t handle, char const * name,
                                    char const ** mimes, size_t mimes_count);

    uint32_t (*register_output_port)(dfx_node_api_handle_t handle, char const * name,
                                     char const * mime_type);

    int (*send_data)(dfx_node_api_handle_t handle, uint32_t port_id,
                     uint8_t const * data, size_t size, char const * mime_type,
                     dfx_message_handle_t parent);

    uint32_t (*register_control_input_port)(dfx_node_api_handle_t handle, char const * name);

    uint32_t (*register_control_output_port)(dfx_node_api_handle_t handle, char const * name);

    int (*send_control)(dfx_node_api_handle_t handle, uint32_t port_id,
                        char const * cmd, char const * params_json, int version);
} dfx_node_api_t;

typedef struct
{
    dfx_node_handle_t (*build)(char const * type, uint32_t id, char const * name, char const * config,
                               dfx_node_api_t const * node_api, size_t node_api_size);

    void (*destroy)(dfx_node_handle_t node);

    int (*start)(dfx_node_handle_t node, dfx_poller_api_t const * poller, size_t poller_size);

    void (*stop)(dfx_node_handle_t node);

    int (*on_message)(dfx_node_handle_t node, uint32_t port_id,
                      dfx_message_api_t const * msg_api, size_t msg_api_size);
} dfx_node_interface_t;

typedef struct
{

    dfx_transport_handle_t (*build_source)(char const * scheme, char const * address,
                                           char const * node, char const * port, char const * config,
                                           dfx_on_message_received_t on_message_received, void * host_ctx);

    dfx_transport_handle_t (*build_destination)(char const * scheme, char const * address,
                                                char const * node, char const * port, char const * config);


    void (*destroy)(dfx_transport_handle_t handle);


    int (*start)(dfx_transport_handle_t handle, dfx_poller_api_t const * poller, size_t poller_size);

    void (*stop)(dfx_transport_handle_t handle);



    int (*transmit_message)(dfx_transport_handle_t handle, uint8_t const * message, size_t length);

    int64_t (*pending_message_count)(dfx_transport_handle_t handle);

} dfx_transport_interface_t;

typedef struct
{
    dfx_registration_handle_t handle;

    int (*register_transport)(dfx_registration_handle_t handle, char const * scheme,
                              dfx_transport_interface_t const * transport_interface, size_t transport_interface_size);

    int (*register_node)(dfx_registration_handle_t handle, char const * type,
                         char const * node_metadata, char const * config_schema,
                         dfx_node_interface_t const * node_interface, size_t node_interface_size);
} dfx_registration_api_t;

#define DFX_PLUGIN_VISIBLE_ATTR __attribute__((visibility("default")))

#define DFX_PLUGIN_METADATA(json_str) __attribute__((section(".dfx_metadata"), used)) \
    char const _dfx_metadata_blob[] = json_str


DFX_PLUGIN_VISIBLE_ATTR int dfx_init_plugin(dfx_env_api_t const * env, size_t env_size,
                                            dfx_registration_api_t const * reg, size_t reg_size,
                                            char const * plugin_config, char const * base_path);

DFX_PLUGIN_VISIBLE_ATTR void dfx_deinit_plugin(dfx_env_api_t const * env, size_t env_size);

 
#ifdef __cplusplus
} // !extern "C"
#endif