Client API

eProsima Micro XRCE-DDS provides the user with a C API to create eProsima Micro XRCE-DDS Clients applications. All functions needed to set up the Client can be found in the client.h header. That is the only header the user needs to include.

In this section, we provide the full API for the Micro XRCE-DDS Client. As a nomenclature, this API uses the uxr_ prefix in all of its public functions and the uxr prefix in the types. In constants values, the UXR_ prefix is used. The functions belonging to the public interface of the library are only those with the tag UXRDDLAPI in their declarations.

The functions are grouped as follows:

Session

These functions are available even if no profile has been enabled. The declaration of these functions can be found in uxr/client/core/session/session.h.

void uxr_init_session(uxrSession* session, uxrCommunication* comm, uint32_t key);

Initializes a session structure. Once this function is called, a create_session call can be performed.

session

Session structure where to manage the session data.

comm

Communication used for connecting to the Agent. All different transports have a common attribute uxrCommunication. This parameter can not be shared between active sessions.

key

The key identifier of the Client. All Clients connected to an Agent must have a different key.

void uxr_set_status_callback(uxrSession* session, uxrOnStatusFunc on_status_func, void* args);

Assigns the callback for the Agent status messages.

session

Session structure previously initialized.

on_status_func

Function callback that is called when a valid status message comes from the Agent.

args

User pointer data. The args are provided to the on_status_func function.

The function signature for the on_status_func callback is:

typedef void (*uxrOnStatusFunc) (struct uxrSession* session, uxrObjectId object_id, uint16_t request_id,
                                 uint8_t status, void* args);
session

Session structure related to the status.

object_id

The identifier of the entity related to the status.

request_id

Status request id.

status

Status value.

args

User pointer data.

void uxr_set_topic_callback(uxrSession* session, uxrOnTopicFunc on_topic_func, void* args);

Assigns the callback for topics. The topics are received only if a request_data function has been called.

session

Session structure previously initialized.

on_status_func

Function callback that is called when a valid data message comes from the Agent.

args

User pointer data. The args are provided to the on_topic_func function.

The function signature for the on_topic_func callback is:

typedef void (*uxrOnTopicFunc) (struct uxrSession* session, uxrObjectId object_id, uint16_t request_id, uxrStreamId stream_id,
                                struct ucdrBuffer* ub, uint16_t length, void* args);
session

Session structure related to the topic.

object_id

The identifier of the entity related to the topic.

request_id

Request id of the``request_data`` transaction.

stream_id

Id of the stream used for the communication.

ub

Serialized topic data.

length

Length of the serialized data.

args

User pointer data.

void uxr_set_time_callback(uxrSession* session, uxrOnTimeFunc on_time_func, void* args);

Assigns the time callback, to let the user perform custom time calculations based on client and agent timestamps.

session

Session structure previously initialized.

on_time_func

Function callback that is called .. ?

args

User pointer data. The args are provided to the on_time_func function.

The function signature for the on_time_func callback is:

typedef void (*uxrOnTimeFunc) (struct uxrSession* session, int64_t current_timestamp, int64_t transmit_timestamp,
                               int64_t received_timestamp, int64_t originate_timestamp, void* args);
session

Session structure related to the topic.

current_timestamp

Client’s timestamp of the response packet reception.

transmit_timestamp

Client’s timestamp of the request packet transmission.

received_timestamp

Agent’s timestamp of the request packet reception.

originate_timestamp

Agent’s timestamp of the response packet transmission.

args

User pointer data.

void uxr_set_request_callback(uxrSession* session, uxrOnRequestFunc on_request_func, void* args);

Sets the request callback, which is called when the Agent sends a READ_DATA submessage associated with a Requester.

session

Session structure previously initialized.

on_request_func

Function callback that is called when the Agent sends a READ_DATA submessage associated with a Requester.

args

User pointer data. The args are provided to the on_request_func function.

The function signature for the on_request_func callback is:

typedef void (*uxrOnRequestFunc) (struct uxrSession* session, uxrObjectId object_id, uint16_t request_id,
                                  SampleIdentity* sample_id, struct ucdrBuffer* ub, uint16_t length, void* args);
session

Session structure related to the topic.

object_id

The identifier of the entity related to the request.

request_id

Request id of the``request_data`` transaction.

sample_id

Identifier of the request.

ub

Serialized request data.

length

Length of the serialized data.

args

User pointer data.

void uxr_set_reply_callback(uxrSession* session, uxrOnReplyFunc on_reply_func, void* args);

Sets the reply callback, which is called when the Agent sends a READ_DATA submessage associated with a Replier.

session

Session structure previously initialized.

on_reply_func

Function callback that is called when the Agent sends a READ_DATA submessage associated with a Replier

args

User pointer data. The args are provided to on_reply_func function.

typedef void (*uxrOnReplyFunc) (struct uxrSession* session, uxrObjectId object_id, uint16_t request_id, uint16_t reply_id,
                                struct ucdrBuffer* ub, uint16_t length, void* args);
session

Session structure related to the topic.

object_id

The identifier of the entity related to the request.

request_id

Request id of the``request_data`` transaction.

reply_id

Identifier of the reply.

ub

Serialized request data.

length

Length of the serialized data.

args

User pointer data.

bool uxr_create_session(uxrSession* session);

Creates a new session on the Agent. This function logs in a session, enabling any other XRCE communication with the Agent.

session

Session structure previously initialized.

void uxr_create_session_retries(uxrSession* session, size_t retries);

Attempts to establish a new session on the Agent retries times. This function logs in a session, enabling any other XRCE communication with the Agent.

session

Session structure previously initialized.

retries

Number of attempts for creating a session.

bool uxr_delete_session(uxrSession* session);

Deletes a session previously created. All XRCE entities created with the session are removed. This function logs out a session, disabling any other XRCE communication with the Agent.

session

Session structure previously initialized and created.

bool uxr_delete_session_retries(uxrSession* session, size_t retries);

Attempts to delete a previously created session retries times. All XRCE entities created with the session are removed. This function logs out a session, disabling any other XRCE communication with the Agent.

session

Session structure previously initialized and created.

retries

Number of attempts for deleting a session.

uxrStreamId uxr_create_output_best_effort_stream(uxrSession* session, uint8_t* buffer, size_t size);

Creates and initializes an output best-effort stream for writing. The uxrStreamId returned represents the new stream and can be used to manage it. The number of available calls to this function must be less or equal than CONFIG_MAX_OUTPUT_BEST_EFFORT_STREAMS CMake argument.

session

Session structure previously initialized and created.

buffer

Memory block where the messages are written.

size

Buffer size.

uxrStreamId uxr_create_output_reliable_stream(uxrSession* session, uint8_t* buffer, size_t size, size_t history);

Creates and initializes an output reliable stream for writing. The uxrStreamId returned represents the new stream and can be used to manage it. The number of available calls to this function must be less or equal than CONFIG_MAX_OUTPUT_RELIABLE_STREAMS CMake argument.

session

Session structure previously initialized and created.

buffer

Memory block where the messages are written.

size

Buffer size.

history

History used for reliable connection. The buffer size is split into a history number of smaller buffers. The history must be a divisor of the buffer size and a power of two.

uxrStreamId uxr_create_input_best_effort_stream(uxrSession* session);

Creates and initializes an input best-effort stream for receiving messages. The uxrStreamId returned represents the new stream and can be used to manage it. The number of available calls to this function must be less or equal than CONFIG_MAX_INPUT_BEST_EFFORT_STREAMS CMake argument.

session

Session structure previously initialized and created.

uxrStreamId uxr_create_input_reliable_stream(uxrSession* session, uint8_t* buffer, size_t size, size_t history);

Creates and initializes an input reliable stream for receiving messages. The returned uxrStreamId represents the new stream and can be used to manage it. The number of available calls to this function must be less or equal than CONFIG_MAX_INPUT_RELIABLE_STREAMS CMake argument.

session

Session structure previously initialized and created.

buffer

Memory block where the messages are stored.

size

Buffer size.

history

History used for reliable connection. The buffer size is split into a history number of smaller buffers. The history must be a divisor of the buffer size and a power of two.

void uxr_flash_output_streams(uxrSession* session);

Flashes all output streams sending the data through the transport.

session

Session structure previously initialized and created.

void uxr_run_session_time(uxrSession* session, int timeout_ms);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The time suffix function version perform these actions and listens to messages for a timeout_ms duration, which is refreshed each time a new message is received, that is, the counter restarts for another timeout_ms period. Only when the wait time for a message overcomes the timeout_ms duration, the function finishes. The function returns true if the sending data have been confirmed, false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Time for waiting for each new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

void uxr_run_session_timeout(uxrSession* session, int timeout_ms);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The timeout suffix function version performs these actions and listens to messages for a total timeout_ms duration. Each time a new message is received, the counter retakes from where it left, that is, for a period equal to timeout_ms minus the time spent waiting for the previous message(s). When the total wait time overcomes the timeout_ms duration, the function finishes. The function returns true if the sending data have been confirmed, false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Total time for waiting for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

void uxr_run_session_until_timeout(uxrSession* session, int timeout_ms);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The until_timeout suffix function version performs these actions until receiving one message, for a timeout_ms time duration. Once a message has been received or the timeout has been reached, the function finishes. The function returns true if it has received a message, false if the timeout has been reached.

session

Session structure previously initialized and created.

timeout_ms

Maximum time for waiting for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

bool uxr_run_session_until_confirm_delivery(uxrSession* session, int timeout_ms);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The until_confirm_delivery suffix function version performs these actions during timeout_ms or until the output reliable streams confirm that the sent messages have been received by the Agent. The function returns true if the sent data have been confirmed, false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Maximum waiting time for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

bool uxr_run_session_until_all_status(uxrSession* session, int timeout_ms, const uint16_t* request_list,
                                      uint8_t* status_list, size_t list_size);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The until_all_status suffix function version performs these actions during a timeout_ms duration or until all requested statuses have been received. The function returns true if all statuses have been received and all of them have the value UXR_STATUS_OK or UXR_STATUS_OK_MATCHED, false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Maximum waiting time for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

request_list

An array of requests to confirm with a status.

status_list

An uninitialized array with the same size as request_list where the status values are written. The position of each status in the status_list matches the corresponding request position in the request_list.

list_size

The size of the request_list and status_list arrays.

bool uxr_run_session_until_one_status(uxrSession* session, int timeout_ms, const uint16_t* request_list,
                                      uint8_t* status_list, size_t list_size);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it performs the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The until_one_status suffix function version performs these actions during a timeout_ms duration or until one requested status has been received. The function returns true if one status has been received and has the value UXR_STATUS_OK or UXR_STATUS_OK_MATCHED, false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Maximum waiting time for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

request_list

An array of requests to confirm with a status.

status_list

An uninitialized array with the same size as request_list where the status values are written. The position of each status in the status_list matches the corresponding request position in the request_list.

list_size

The size of the request_list and status_list arrays.

bool uxr_run_session_until_data(uxrSession* session, int timeout_ms);

This function processes the internal functionality of a session. It implies:

  1. Flushing all output streams sending the data through the transport.

  2. If there is any reliable stream, it operates according to the associated reliable behaviour to ensure communication.

  3. Listening to messages from the Agent and calling the associated callback if it exists (which can be a status/topic/time/request or reply callback)

The until_data suffix function version performs these actions during a timeout_ms duration or until a subscription data, request or reply is received. The function returns true if a subscription data, request or reply is received, and false otherwise.

session

Session structure previously initialized and created.

timeout_ms

Maximum waiting time for a new message, in milliseconds. For waiting without timeout, set the value to UXR_TIMEOUT_INF

bool uxr_sync_session(uxrSession* session, int time);

This function synchronizes the session time with the Agent using the NTP protocol by default.

session

Session structure previously initialized and created.

time

The waiting time in milliseconds.

int64_t uxr_epoch_millis(uxrSession* session);

This function returns the epoch time in milliseconds, taking into account the offset computed during the time synchronization.

session

Session structure previously initialized.

int64_t uxr_epoch_nanos(uxrSession* session);

This function returns the epoch time in nanoseconds taking into account the offset computed during the time synchronization.

session

Session structure previously initialized and created.

Create entities by XML

The declaration of these functions can be found in uxr/client/profile/session/create_entities_xml.h.

uint16_t uxr_buffer_create_participant_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                           uint16_t domain_id, const char* xml, uint8_t mode);

Creates a participant entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_PARTICIPANT_ID.

domain_id

The DDS domain identifier.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_topic_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                     uxrObjectId participant_id, const char* xml, uint8_t mode);

Creates a topic entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_TOPIC_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_publisher_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                         uxrObjectId participant_id, const char* xml, uint8_t mode);

Creates a publisher entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_PUBLISHER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_subscriber_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                          uxrObjectId participant_id, const char* xml, uint8_t mode);

Creates a subscriber entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_SUBSCRIBER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datawriter_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                          uxrObjectId publisher_id, const char* xml, uint8_t mode);

Creates a datawriter entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAWRITER_ID.

publisher_id

The identifier of the associated publisher. The type must be UXR_PUBLISHER_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datareader_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                          uxrObjectId subscriber_id, const char* xml, uint8_t mode);

Creates a datareader entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAREADER_ID.

subscriber_id

The identifier of the associated subscriber. The type must be UXR_SUBSCRIBER_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_requester_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                         uxrObjectId participant_id, const char* xml, uint8_t mode);

Creates a requester entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REQUESTER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_replier_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                       uxrObjectId participant_id, const char* xml, uint8_t mode);

Creates a replier entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REPLIER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

xml

An XML representation of the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

Create entities by reference

The declaration of these functions can be found in uxr/client/profile/session/create_entities_ref.h.

uint16_t uxr_buffer_create_participant_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                           uint16_t domain_id, const char* ref, uint8_t mode);

Creates a participant entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_PARTICIPANT_ID

domain_id

DDS Domain ID for the participant.

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_topic_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                     uxrObjectId participant_id, const char* ref, uint8_t mode);

Creates a topic entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_TOPIC_ID

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datawriter_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                          uxrObjectId publisher_id, const char* ref, uint8_t mode);

Creates a datawriter entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAWRITER_ID

publisher_id

The identifier of the associated publisher. The type must be UXR_PUBLISHER_ID

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datareader_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                          uxrObjectId subscriber_id, const char* ref, uint8_t mode);

Creates a datareader entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAREADER_ID.

subscriber_id

The identifier of the associated subscriber. The type must be UXR_SUBSCRIBER_ID.

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_requester_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                         uxrObjectId participant_id, const char* ref, uint8_t mode);

Creates a requester entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REQUESTER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_replier_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
                                       uxrObjectId participant_id, const char* ref, uint8_t mode);

Creates a replier entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REPLIER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

ref

A reference to the new entity.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

Create entities by binary

The declaration of these functions can be found in uxr/client/profile/session/create_entities_ref.h.

uint16_t uxr_buffer_create_participant_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uint16_t domain_id, const char* participant_name, uint8_t mode);

Creates a participant entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_PARTICIPANT_ID

domain_id

DDS Domain ID for the participant.

participant_name

Participant name.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_topic_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId participant_id, const char* topic_name, const char* type_name, uint8_t mode);

Creates a topic entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_TOPIC_ID

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID

topic_name

Topic name.

type_name

Type name.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uint16_t uxr_buffer_create_publisher_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId participant_id, uint8_t mode);

Creates a publisher entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_PUBLISHER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uint16_t uxr_buffer_create_subscriber_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId participant_id, uint8_t mode);

Creates a subscriber entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_SUBSCRIBER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datawriter_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId publisher_id, uxrObjectId topic_id, uxrQoS_t qos, uint8_t mode);

Creates a datawriter entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAWRITER_ID

publisher_id

The identifier of the associated publisher. The type must be UXR_PUBLISHER_ID

topic_id

The identifier of the associated topic. The type must be UXR_TOPIC_ID

qos

uxrQoS_t struct describing QoS.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_datareader_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId subscriber_id, uxrObjectId topic_id, uxrQoS_t qos, uint8_t mode);

Creates a datareader entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_DATAREADER_ID.

subscriber_id

The identifier of the associated subscriber. The type must be UXR_SUBSCRIBER_ID.

topic_id

The identifier of the associated topic. The type must be UXR_TOPIC_ID

qos

uxrQoS_t struct describing QoS.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_requester_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId participant_id, const char* service_name, const char* request_type, const char* reply_type,
    const char* request_topic_name, const char* reply_topic_name, uxrQoS_t qos, uint8_t mode);

Creates a requester entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REQUESTER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

service_name

Service name.

request_type

Request type name.

reply_type

Reply type name.

request_topic_name

Request topic name.

reply_topic_name

Reply topic name.

qos

uxrQoS_t struct describing QoS.

mode

Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

uint16_t uxr_buffer_create_replier_bin(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id,
    uxrObjectId participant_id, const char* service_name, const char* request_type, const char* reply_type,
    const char* request_topic_name, const char* reply_topic_name, uxrQoS_t qos, uint8_t mode);

Creates a replier entity in the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the new entity. Later, the entity can be referenced with this id. The type must be UXR_REPLIER_ID.

participant_id

The identifier of the associated participant. The type must be UXR_PARTICIPANT_ID.

service_name

Service name.

request_type

Request type name.

reply_type

Reply type name.

request_topic_name

Request topic name.

reply_topic_name

Reply topic name.

qos

uxrQoS_t struct describing QoS.:mode: Determines the creation entity mode. The Creation Policy Table describes the entities’ creation behaviour according to the UXR_REUSE and UXR_REPLACE flags (see Creation Policy Table).

Create entities common profile

These functions are enabled when either PROFILE_CREATE_ENTITIES_XML or PROFILE_CREATE_ENTITIES_REF are activated as CMake arguments. The declaration of these functions can be found in uxr/client/profile/session/common_create_entities.h.

uint16_t uxr_buffer_delete_entity(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id);

Removes an entity. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

object_id

The identifier of the object which is deleted.

Read access

The Read Access is used by the Client to handle the read operation on the Agent. The declaration of these functions can be found in uxr/client/profile/session/read_access.h.

uint16_t uxr_buffer_request_data(uxrSession* session, uxrStreamId stream_id, uxrObjectId datareader_id,
                                 uxrStreamId data_stream_id, const uxrDeliveryControl* const control);

This function requests a datareader previously created on the Agent to perform a read operation that fetches data from the middleware. The returned value is an identifier of the request. All received topics have the same request identifier. The topics are received on the callback topic through the run_session function. If there is no error with the request data, a status callback with the value UXR_STATUS_OK is generated along with the topics retrieval. If there is an error, a status error is sent by the Agent. The message is written into the stream buffer. To send the message, it is necessary to call either the uxr_flash_output_streams or the uxr_run_session function.

session

Session structure previously initialized and created.

stream_id

The output stream ID used to send messages to the Agent.

datareader_id

The ID of the datareader that reads the topics from the middleware.

data_stream_id

The input stream ID where the data is received.

control

Optional information allowing the Client to configure the data delivery from the Agent. Details on the configurable parameters can be found in the Read Access Delivery Control of the eProsima Micro XRCE-DDS Client page. A NULL value is accepted, in which case only one topic is received.

uint16_t uxr_buffer_cancel_data(uxrSession* session, uxrStreamId stream_id, uxrObjectId datareader_id);

This function requests a datareader, requester or replier previously created on the Agent to cancel the data received from the middleware. It does so by resetting the delivery_control parameters and the input stream ID used to receive the data. The returned value is an identifier of the request.

session

Session structure previously initialized and created.

stream_id

The output stream ID used to send messages to the Agent.

datareader_id

The ID of the datareader that reads the topics from the middleware.

Write access profile

The Write Access is used by the Client to handle the write operation on the Agent. The declaration of these functions can be found in uxr/client/profile/session/write_access.h.

uint16_t uxr_prepare_output_stream(uxrSession* session, uxrStreamId stream_id, uxrObjectId entity_id,
                               ucdrBuffer* ub, uint32_t data_size);

This function requests a datawriter, requester or replier previously created on the Agent to perform a write operation into a specific output stream. It initializes a ucdrBuffer struct where a data of data_size size must be serialized. If there is sufficient space for writing data_size bytes into the stream, the returned value is the XRCE request ID, otherwise it is 0. The topic is sent in the following run_session function. If UCLIENT_PROFILE_MULTITHREAD is enabled, user should unlock the stream lock after serializing the requested amount of data using UXR_UNLOCK_STREAM_ID(session, stream_id);

Note

All data_size bytes requested are sent to the Agent after a run_session call, no matter if the ucdrBuffer has been used or not.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

entity_id

The ID of the datawriter, requester or replier that writes data into the middleware.

ub

The ucdrBuffer struct used to serialize the data. This struct points to the requested memory slot in the stream.

data_size

The slot, in bytes, that is reserved in the stream.

bool uxr_buffer_request(uxrSession* session, uxrStreamId stream_id, uxrObjectId requester_id, uint8_t* buffer, size_t len);

This function buffers a request into a specific output stream. The request is sent in the following run_session function call.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

requester_id

The ID of the requester that forwards the request to the middleware.

buffer

The raw buffer that contains the serialized request.

len

The size of the serialized request.

bool uxr_buffer_reply(uxrSession* session, uxrStreamId stream_id, uxrObjectId replier_id, uint8_t* buffer, size_t len);

This function buffers a reply into a specific output stream. The request is sent in the following run_session function call.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

replier_id

The ID of the replier that writes the reply to the middleware.

buffer

The raw buffer that contains the serialized reply.

len

The size of the serialized reply.

bool uxr_buffer_topic(uxrSession* session, uxrStreamId stream_id, uxrObjectId datawriter_id, uint8_t* buffer, size_t len);

This function buffers a topic into a specific output stream. The request is sent in the following run_session function call.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

datawriter_id

The ID of the datawriter that writes the reply to the middleware.

buffer

The raw buffer that contains the serialized topic.

len

The size of the serialized topic.

uint16_t uxr_prepare_output_stream_fragmented(uxrSession* session, uxrStreamId stream_id, uxrObjectId entity_id,
                                          struct ucdrBuffer* ub, size_t data_size, uxrOnBuffersFull flush_callback);

This function requests a datawriter, requester or replier previously created on the Agent to allocate an output stream of data_size bytes for a write operation. This function initializes an ucdrBuffer struct where a topic of data_size size is serialized. If there is sufficient space for writing data_size bytes into the stream, the returned value is the XRCE request ID, otherwise it is 0. The topic is sent in the following run_session function. If, during the serialization process, the buffer gets overfilled, the flush_callback function is called and the user has to run a session for flushing the stream. If UCLIENT_PROFILE_MULTITHREAD is enabled, user should unlock the stream lock after serializing the requested amount of data using UXR_UNLOCK_STREAM_ID(session, stream_id);

Note

This approach is not valid for best-effort streams.

session

Session structure previously initialized and created.

stream_id

The output stream ID where the messages are written.

entity_id

The ID of the datawriter, requester or replier that writes data into the middleware.

ub

The ucdrBuffer struct used to serialize the topic. This struct points to the requested memory slot in the stream.

data_size

The slot, in bytes, that is reserved in the stream.

flush_callback

Callback for flushing the output buffers.

The function signature for the flush_callback callback is:

typedef bool (*uxrOnBuffersFull) (struct uxrSession* session);
session

Session structure related to the buffer to be flushed.

Discovery profile

The discovery profile allows discovering Agents in the network by UDP. The reachable Agents respond to the discovery call by sending information about themselves, as their IP and port. There are two modes: unicast and multicast. The discovery phase precedes the call to the uxr_create_session function, as it serves to determine the Agent to connect with. These functions are enabled when PROFILE_DISCOVERY is activated as a CMake argument. The declaration of these functions can be found in uxr/client/profile/discovery/discovery.h.

Note

This feature is only available on Linux.

bool uxr_discovery_agents_default(uint32_t attempts, int period, uxrOnAgentFound on_agent_func, void* args);

This function looks for Agents in the network using UDP/IP multicast with address “239.255.0.2” and port 7400 (which is the default used by the Agent).

attempts

The times a discovery message is sent across the network.

period

The wait time between two successive discovery calls.

on_agent_func

The callback function that is called when an Agent is discovered. It returns a boolean value. A true means that the discovery routine has finished. A false implies that the discovery routine must continue searching Agents.

args

User arguments passed to the callback function.

The function signature for the on_agent_func callback is:

typedef bool (*uxrOnAgentFound) (const TransportLocator* locator, void* args);
locator

Transport locator of a discovered agent.

args

User pointer data.

bool uxr_discovery_agents(uint32_t attempts, int period, uxrOnAgentFound on_agent_func, void* args,
                          const TransportLocator* agent_list, size_t agent_list_size);

This function looks for Agents in the network using UDP/IP unicast, using a list of unicast directions with the addresses and ports set by the user.

attempts

The times a discovery message is sent across the network.

period

The wait time between two successive discovery calls.

on_agent_func

The callback function that is called when an Agent is discovered. It returns a boolean value. A true means that the discovery routine has finished. A false implies that the discovery routine must continue searching Agents.

args

User arguments passed to the callback function.

agent_list

The list of addresses used for discovering Agents.

agent_list_size

The size of the agent_list.

The function signature for the on_time_func callback is the same as above.

Topic serialization

Functions to serialize and deserialize topics. These functions are generated automatically by the eProsima Micro XRCE-DDS Gen utility fed with an IDL file with a topic TOPICTYPE. The declaration of these functions can be found in the generated file TOPICTYPE.h.

bool TOPICTYPE_serialize_topic(struct ucdrBuffer* writer, const TOPICTYPE* topic);

This function serializes a topic into an ucdrBuffer. The returned value indicates if the serialization was successful.

writer

The ucdrBuffer representing the buffer for the serialization.

topic

Struct to serialize.

bool TOPICTYPE_deserialize_topic(struct ucdrBuffer* reader, TOPICTYPE* topic);

This function deserializes a topic from an ucdrBuffer. The returned value indicates if the deserialization was successful.

reader

An ucdrBuffer representing the buffer for the deserialization.

topic

Struct to deserialize.

uint32_t TOPICTYPE_size_of_topic(const TOPICTYPE* topic, uint32_t size);

This function counts the number of bytes that the topic needs in an ucdrBuffer.

topic

Struct to count the size.

size

Number of bytes already written into the ucdrBuffer. Typically, its value is 0 if the purpose is to use in uxr_prepare_output_stream function.

General utilities

Utility functions. The declaration of these functions can be found in uxr/client/core/session/stream_id.h and uxr/client/core/session/object_id.h.

uxrStreamId uxr_stream_id(uint8_t index, uxrStreamType type, uxrStreamDirection direction);

This function creates a stream identifier. This function does not create a new stream, it only creates its identifier to be used in the Client API.

index

Identifier of the stream. Its value corresponds to the creation order of the stream, different for each type.

type

The type of the stream, it can be UXR_BEST_EFFORT_STREAM or UXR_RELIABLE_STREAM.

direction

Represents the direction (input or output) of the stream. It can be UXR_INPUT_STREAM or UXR_OUTPUT_STREAM.

uxrStreamId uxr_stream_id_from_raw(uint8_t stream_id_raw, uxrStreamDirection direction);

This function creates a stream identifier. This function does not create a new stream, it only creates its identifier to be used in the Client API.

stream_id_raw

Identifier of the stream. It goes from 0 to 255. 0 is for internal library use. 1 to 127 are for best effort. 128 to 255 are for reliable.

direction

Represents the direction (input or output) of the stream. It can be UXR_INPUT_STREAM or MT_OUTPUT_STREAM.

uxrObjectId uxr_object_id(uint16_t id, uint8_t type);

This function creates an identifier to reference an entity.

id

Identifier of the object, different for each type. There can be several objects with the same ID, provided they have different types.

type

The type of the entity. It can be: UXR_PARTICIPANT_ID, UXR_TOPIC_ID, UXR_PUBLISHER_ID, UXR_SUBSCRIBER_ID, UXR_DATAWRITER_ID, UXR_DATAREADER_ID, UXR_REQUESTER_ID, or UXR_REPLIER_ID.

bool uxr_ping_agent_session(struct uxrSession* session, const int timeout_ms, const uint8_t attempts);

This function pings a Micro XRCE-DDS Agent to check if it is already up and running.

This method does require an XRCE session to be established beforehand. Internally it spins the session until ping answer is received or it timeouts.

It returns true if a response was received from the Agent, false otherwise.

session

A pointer to a properly initialized XRCE-DDS session, used to send the ping request.

timeout_ms

The maximum time that the Client will wait to receive the answer (pong) message, before returning.

attempts

Maximum amount of times that the Client will try to ping the Agent and receive a response back.

bool uxr_ping_agent(const uxrCommunication* comm, const int timeout_ms);

This function pings a Micro XRCE-DDS Agent to check if it is already up and running.

This method does not require an XRCE session to be established beforehand. It acts directly over the transport layer so if a session is running simultaneouly, data can be loss.

It returns true if a response was received from the Agent, false otherwise.

comm

A pointer to a properly initialized XRCE-DDS communication structure, used to send the ping request.

timeout_ms

The maximum time that the Client will wait to receive the answer (pong) message, before returning.

bool uxr_ping_agent_attempts(const uxrCommunication* comm, const int timeout_ms, const uint8_t attempts);

This function provides the same functionality as the method described in uxr_ping_agent, but allows to specify the number of ping attempts before returning a value.

comm

A pointer to a properly initialized XRCE-DDS communication structure, used to send the ping request.

timeout_ms

The maximum time per attempt that the Client will wait to receive the answer (pong) message, before returning.

attempts

Maximum amount of times that the Client will try to ping the Agent and receive a response back.

Transport

These functions are platform-dependent. The declaration of these functions can be found in the uxr/client/profile/transport/ folder. The common init transport functions follow the nomenclature below.

bool uxr_init_udp_transport(uxrUDPTransport* transport, uxrIpProtocol ip_protocol, const char* ip, const char* port);

This function initializes a UDP connection.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection.

ip_protocol

IPv4 or IPv6.

ip

Agent IP.

port

Agent port.

bool uxr_init_tcp_transport(uxrTCPTransport* transport, uxrIpProtocol ip_protocol, const char* ip, const char* port);

This function initializes a TCP connection. In the case of TCP, the behaviour of best-effort streams is similar to that of reliable streams in UDP.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection.

ip_protocol

IPv4 or IPv6.

ip

Agent IP.

port

Agent port.

bool uxr_init_serial_transport(uxrSerialTransport* transport, const int fd, uint8_t remote_addr, uint8_t local_addr);

This function initializes a Serial connection using a file descriptor.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection.

fd

File descriptor of the serial connection. Usually, the fd comes from the open OS function.

remote_addr

Identifier of the Agent in the connection. By default, the Agent identifier in a seria connection is 0.

local_addr

Identifier of the Client in the serial connection.

bool uxr_init_can_transport(uxrCANTransport* transport, const char* dev, uint32_t can_id);

This function initializes a CAN FD connection using a network interface.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection.

dev

Interface name of the CAN FD bus.

can_id

Can identifier of this Client.

Note

The used interface must support CAN FD frames with a maximum payload of 64 bytes. The can identifier will be used on the CAN frames and should be unique for each client.

bool uxr_init_custom_transport(uxrCustomTransport* transport, void * args);

This function initializes a Custom connection using user-defined arguments.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection. args is accesible as transport->args.

bool uxr_close_PROTOCOL_transport(PROTOCOLTransport* transport);

This function closes a transport previously opened. PROTOCOL can be udp, tcp, serial, can or custom.

transport

The structure used for managing the transport that must be closed.

void uxr_set_custom_transport_callbacks(uxrCustomTransport* transport, bool framing, open_custom_func open,
                           close_custom_func close, write_custom_func write, read_custom_func read);

This function assigns the callback for custom transport.

transport

The uninitialized structure used for managing the transport. This structure must be accessible during the connection.

framing

Enables or disables Stream Framing Protocol for a custom transport.

open

Callback for opening a custom transport.

close

Callback for closing a custom transport.

write

Callback for writing to a custom transport.

read

Callback for reading from a custom transport.

The function signatures for the above callbacks are:

typedef bool (*open_custom_func) (struct uxrCustomTransport* transport);
transport

Custom transport structure. Has the args passed through bool uxr_init_custom_transport(uxrCustomTransport* transport, void * args);.

typedef bool (*close_custom_func) (struct uxrCustomTransport* transport);
transport

Custom transport structure. Has the args passed through bool uxr_init_custom_transport(uxrCustomTransport* transport, void * args);.

typedef size_t (*write_custom_func) (struct uxrCustomTransport* transport, const uint8_t* buffer, size_t length, uint8_t* error_code);
transport

Custom transport structure. Has the args passed through bool uxr_init_custom_transport(uxrCustomTransport* transport, void * args);.

buffer

Buffer to be sent.

length

Length of buffer.

error_code

Error code that should be set in case the write process experiences some error.

This function should return the number of successfully sent bytes.

typedef size_t (*read_custom_func) (struct uxrCustomTransport* transport, uint8_t* buffer, size_t length, int timeout, uint8_t* error_code);
transport

Custom transport structure. Has the args passed through bool uxr_init_custom_transport(uxrCustomTransport* transport, void * args);.

buffer

Buffer to write.

length

Maximum length of buffer.

timeout

Maximum timeout of the read operation.

error_code

Error code that should be set in case the write process experiences some error.

This function should return the number of successfully received bytes.