dfx_message_api_t Struct Reference

Host-provided API for interrogating message handles. More...

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

Public Attributes
dfx_message_handle_t	handle
	The borrowed handle to the message being interrogated.
dfx_port_kind_t(*	get_kind )(dfx_message_handle_t handle)
	Query the kind of the message.
int(*	get_uuid )(dfx_message_handle_t handle, uint8_t out_uuid[16])
	Gets the unique identifier (UUID) of the message.
int(*	get_parent_uuid )(dfx_message_handle_t handle, uint8_t out_uuid[16])
	Gets the UUID of the message's parent (for lineage tracking).
size_t(*	get_mime_type )(dfx_message_handle_t handle, char *out_buf, size_t buf_size)
	Copies the MIME type string into a plugin-provided buffer.
int(*	get_timestamp )(dfx_message_handle_t handle, struct timespec *tp)
	Gets the wall-clock timestamp of when the message was created.
size_t(*	get_path_count )(dfx_message_handle_t handle)
	Get the number of endpoints this message has traversed.
size_t(*	get_path_step )(dfx_message_handle_t handle, size_t index, char *out_buf, size_t buf_size)
	Copies a specific step in the message's traversal path.
int(*	get_data )(dfx_message_handle_t handle, uint8_t const **out_data, size_t *out_size)
	Provides a direct view into the raw data payload.
size_t(*	get_ctrl_cmd )(dfx_message_handle_t handle, char *out_buf, size_t buf_size)
	Copies the dfx::Core::ControlMessage command string.
size_t(*	get_ctrl_params )(dfx_message_handle_t handle, char *out_buf, size_t buf_size)
	Provides a direct view into the dfx::Core::ControlMessage parameters (JSON).
int(*	get_ctrl_version )(dfx_message_handle_t handle)
	Provides the version used for this dfx::Core::ControlMessage.

Detailed Description

Host-provided API for interrogating message handles.

This structure is provided to the plugin during the on_message callback. It allows the plugin to inspect message metadata and payloads.

Note

Lifetime Warning: Any pointers returned via "view" functions (e.g., get_data) are only valid for the duration of the current callback. If the plugin needs to persist this data, it must perform its own copy.

Member Data Documentation

get_ctrl_cmd

size_t(* dfx_message_api_t::get_ctrl_cmd) (dfx_message_handle_t handle, char *out_buf, size_t buf_size)

Copies the dfx::Core::ControlMessage command string.

If out_buf is NULL or buf_size is 0 then no data is copied and the length of the command string is still returned.

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_buf	Buffer to receive the command.
[in]	buf_size	Size of the supplied buffer.

Returns

The length of the command string. Will return DFX_INVALID_SIZE on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.
• ENOTSUP: handle is not a DFX_KIND_CONTROL.

get_ctrl_params

size_t(* dfx_message_api_t::get_ctrl_params) (dfx_message_handle_t handle, char *out_buf, size_t buf_size)

Provides a direct view into the dfx::Core::ControlMessage parameters (JSON).

If out_buf is NULL or buf_size is 0 then no data is copied and the length of the parameters string is still returned.

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_buf	Buffer to receive the parameters.
[in]	buf_size	Size of the supplied buffer.

Returns

The length of the parameter string. Will return DFX_INVALID_SIZE on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.
• ENOTSUP: handle is not a DFX_KIND_CONTROL.

get_ctrl_version

int(* dfx_message_api_t::get_ctrl_version) (dfx_message_handle_t handle)

Provides the version used for this dfx::Core::ControlMessage.

Parameters

[in]

handle

The handle provided in this struct.

Returns

The protocol version associated with this dfx::Core::ControlMessage or DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.
• ENOTSUP: handle is not a DFX_KIND_CONTROL.

get_data

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

Provides a direct view into the raw data payload.

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_data	Pointer to the internal host memory.
[out]	out_size	The size of the payload in bytes.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle, out_data, or out_size is NULL.
• ENOTSUP: handle is not a DFX_KIND_DATA.

Warning

Do not store out_data; the memory may be freed after the callback returns.

get_kind

dfx_port_kind_t(* dfx_message_api_t::get_kind) (dfx_message_handle_t handle)

Query the kind of the message.

Parameters

[in]

handle

The handle provided in this struct.

Returns

The kind of message (DFX_KIND_DATA or DFX_KIND_CONTROL). Will return DFX_KIND_INVALID on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.

get_mime_type

size_t(* dfx_message_api_t::get_mime_type) (dfx_message_handle_t handle, char *out_buf, size_t buf_size)

Copies the MIME type string into a plugin-provided buffer.

If out_buf is NULL or buf_size is 0 then no data is copied and the length of the mime_type is still returned.

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_buf	Buffer to receive the string. If NULL, only the size is returned.
[in]	buf_size	Size of the destination buffer.

Returns

The actual length of the string (excluding null terminator). Will return DFX_INVALID_SIZE on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.

get_parent_uuid

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

Gets the UUID of the message's parent (for lineage tracking).

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_uuid	A plugin supplied buffer where the UUID will be copied to.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.

get_path_count

size_t(* dfx_message_api_t::get_path_count) (dfx_message_handle_t handle)

Get the number of endpoints this message has traversed.

Parameters

[in]

handle

The handle provided in this struct.

Returns

The number of nodes/ports this message has traversed. Will return DFX_INVALID_SIZE on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.

get_path_step

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

Copies a specific step in the message's traversal path.

If out_buf is NULL or buf_size is 0 then no data is copied and the length of the path is still returned.

Parameters

[in]	handle	The handle provided in this struct.
[in]	index	The step index (0 to count-1).
[out]	out_buf	Buffer to receive the "node.port" string.
[in]	buf_size	Size of the supplied buffer.

Returns

The actual length of the string (excluding null terminator). Will return DFX_INVALID_SIZE on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.
• ERANGE: index is out of bounds.

get_timestamp

int(* dfx_message_api_t::get_timestamp) (dfx_message_handle_t handle, struct timespec *tp)

Gets the wall-clock timestamp of when the message was created.

Parameters

[in]	handle	The handle provided in this struct.
[out]	tp	The timespec structure that will be filled.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle or tp is NULL.

get_uuid

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

Gets the unique identifier (UUID) of the message.

Parameters

[in]	handle	The handle provided in this struct.
[out]	out_uuid	A plugin supplied buffer where the UUID will be copied to.

Returns

DFX_OK on success, DFX_ERROR on error.

Errors

On failure, errno is set to:

• EINVAL: handle is NULL.

handle

dfx_message_handle_t dfx_message_api_t::handle

The borrowed handle to the message being interrogated.

---

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

• lib/dfx-plugins-interface/PluginInterface.h