Host-provided services for a node instance. More...

#include <dfx-plugins-interface/PluginInterface.h>

Public Attributes
dfx_node_api_handle_t	handle
	Opaque handle representing the host-side node context (CNode instance).
int(*	notify_stopped )(dfx_node_api_handle_t handle)
	Notifies the host that the node has finished its internal cleanup.
int(*	assign_task_executor )(dfx_node_api_handle_t handle, dfx_task_executor_interface_t const *executor, size_t executor_size)
	Assigns a custom task executor to this node.
int(*	revoke_task_executor )(dfx_node_api_handle_t handle)
	Revokes the current custom task executor.
uint32_t(*	register_input_port )(dfx_node_api_handle_t handle, char const name, char const *mimes, size_t mimes_count)
	Registers a data-plane input port.
uint32_t(*	register_output_port )(dfx_node_api_handle_t handle, char const name, char const mime_type)
	Registers a data-plane output port.
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)
	Produces and sends a dfx::Core::DataMessage.
uint32_t(*	register_control_input_port )(dfx_node_api_handle_t handle, char const *name)
	Registers a control-plane input port.
uint32_t(*	register_control_output_port )(dfx_node_api_handle_t handle, char const *name)
	Registers a control-plane output port.
int(*	send_control )(dfx_node_api_handle_t handle, uint32_t port_id, char const cmd, char const params_json, int version)
	Produces and sends a ControlMessage.

Detailed Description

Host-provided services for a node instance.

This structure contains function pointers provided by the dfx core. The plugin uses this API to register ports and emit messages. The handle member must be passed as the first argument to every function in this struct.

Member Data Documentation

◆ assign_task_executor

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

Assigns a custom task executor to this node.

Once assigned, all future tasks for this node (FD events, callbacks) will be routed through the provided executor instead of the global host thread pool.

Parameters

[in]	handle	The node API handle provided in this struct.
[in]	executor	The plugin-side executor implementation.
[in]	executor_size	Size of the dfx_task_executor_interface_t.

Returns: DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

EINVAL: handle or executor is NULL.
ENOTSUP: The executor version is incompatible.

◆ handle

dfx_node_api_handle_t dfx_node_api_t::handle

Opaque handle representing the host-side node context (CNode instance).

◆ notify_stopped

int(* dfx_node_api_t::notify_stopped) (dfx_node_api_handle_t handle)

Notifies the host that the node has finished its internal cleanup.

Must be called after the node has stopped all background processing. The node is informed that it needs to stop through the dfx_node_interface_t::stop function

Parameters

[in] handle The handle provided in this struct.

Returns: DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.

◆ register_control_input_port

uint32_t(* dfx_node_api_t::register_control_input_port) (dfx_node_api_handle_t handle, char const *name)

Registers a control-plane input port.

Parameters

[in]	handle	The handle provided in this struct.
[in]	name	Name of the port. Must be unique for this node.

Returns: The unique ID assigned to the port for use in send_control. Will return DFX_INVALID_PORT_ID on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.
EEXIST: name is already used by another port.

◆ register_control_output_port

uint32_t(* dfx_node_api_t::register_control_output_port) (dfx_node_api_handle_t handle, char const *name)

Registers a control-plane output port.

Parameters

[in]	handle	The handle provided in this struct.
[in]	name	Name of the port. Must be unique for this node.

Returns: The unique ID assigned to the port for use in send_control. Will return DFX_INVALID_PORT_ID on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.
EEXIST: name is already used by another port.

◆ register_input_port

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

Registers a data-plane input port.

Parameters

[in]	handle	The handle provided in this struct.
[in]	name	Name of the port. Must be unique for this node.
[in]	mimes	Array of supported MIME type strings. Can be NULL if and only if `mimes_count` is 0.
[in]	mimes_count	Number of elements in the mimes array (0 for "Any").

Returns: The unique ID assigned to the port for use in on_message. Will return DFX_INVALID_PORT_ID on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.
EEXIST: name is already used by another port.

◆ register_output_port

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

Registers a data-plane output port.

Parameters

[in]	handle	The handle provided in this struct.
[in]	name	Name of the port. Must be unique for this node.
[in]	mime_type	The specific MIME type this port produces (NULL for "Any").

Returns: The unique ID assigned to the port for use in send_data. Will return DFX_INVALID_PORT_ID on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.
EEXIST: name is already used by another port.

◆ revoke_task_executor

int(* dfx_node_api_t::revoke_task_executor) (dfx_node_api_handle_t handle)

Revokes the current custom task executor.

After this call, the node reverts to using the host's default task execution logic.

Parameters

[in] handle The node API handle provided in this struct.

Returns: DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

EINVAL: handle or executor is NULL.

◆ send_control

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

Produces and sends a ControlMessage.

Parameters

[in]	handle	The handle provided in this struct.
[in]	port_id	The ID returned by register_control_output_port.
[in]	cmd	The command string.
[in]	params_json	JSON string of parameters.
[in]	version	Protocol version. Current version is 1.

Returns: DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL or params_json is not a valid JSON.
ENOENT: port_id output port doesn't exists for this node.
ENOTSUP: port_id is not a DFX_KIND_CONTROL port.

◆ send_data

int(* dfx_node_api_t::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)

Produces and sends a dfx::Core::DataMessage.

The provided data is copied into the message so the data pointer only needs to remain valid for the duration of this call only.

Parameters

[in]	handle	The handle provided in this struct.
[in]	port_id	The ID returned by register_output_port.
[in]	data	Pointer to the payload bytes.
[in]	size	Size of the payload.
[in]	mime_type	Optional MIME type override. If NULL, the port's default is used.
[in]	parent	Optional parent for the new message. If `mime_type` is NULL and `parent` is not, then its mime-type will be used for the new message. UUID of the parent will also be set as parent UUID for the new message.

Returns: DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

EINVAL: handle is NULL.
ENOENT: port_id output port doesn't exists for this node.
ENOTSUP: port_id is not a DFX_KIND_DATA port.

The documentation for this struct was generated from the following file:

lib/dfx-plugins-interface/PluginInterface.h

Public Attributes

Detailed Description

Member Data Documentation

◆ assign_task_executor

◆ handle

◆ notify_stopped

◆ register_control_input_port

◆ register_control_output_port

◆ register_input_port

◆ register_output_port

◆ revoke_task_executor

◆ send_control

◆ send_data