3. MQTT Adapter API

Figure 3.1 MQTT Adapter UML Diagram

group RtiMqtt_API

3.1. Compiler Defines

group RtiMqtt_Compiler

3.1.1. User Defines

group RtiMqtt_Compiler_User

Defines

RTI_MQTT_PLATFORM

The current target build platform.

This macro can be specified by users to select the target build platform,

If not explicitly set, the value will be automatically detected based on available compiler features, or an error will be thrown by the preprocessor.

RTI_MQTT_ENABLE_SSL

Compiler flag that enables SSL/TLS support.

Users should define this flag is they want to establish SSL/TLS connections with MQTT Brokers.

Flag RTI_MQTT_USE_SSL will be automatically enabled if this flag is set.

See also

RTI_MQTT_USE_SSL

RTI_MQTT_STATIC_TYPES

Compiler flag that enable internal use of static DDS types instead of DDS_DynamicData.

Users should define this flag is they prefer the MQTT Adapter to use static DDS types RTI_MQTT_Message, and RTI_MQTT_KeyedMessage, instead of DDS_DynamicData.

If static types are used internally, an additional copy will be performed when data is passed to RTI Routing Service (which requires samples to be represented as DDS_DynamicData).

Flag RTI_MQTT_USE_STATIC_TYPES will be automatically enabled if this flag is set.

See also

RTI_MQTT_USE_STATIC_TYPES

RTI_MQTT_ENABLE_LOG

Compiler flag that enables the logging module.

The MQTT Adapter includes a static logging module that can be enabled or disabled at compile-time.

When enabled, the logging module can optionally produce more verbose output by enabling trace-level logging.

By default, the logging module will be automatically enabled if NDEBUG and RTI_MQTT_DISABLE_LOG are not defined.

See also

RTI_MQTT_USE_LOG RTI_MQTT_DISABLE_LOG

RTI_MQTT_DISABLE_LOG

Compiler flag that disables the logging module.

Flag RTI_MQTT_ENABLE_LOG takes precedence if explicitly set.

This flag should be used to disable automatic enabling of the logging module if NDEBUG is not defined (i.e. for debug builds).

See also

RTI_MQTT_USE_LOG RTI_MQTT_ENABLE_LOG

RTI_MQTT_ENABLE_TRACE

Compiler flag that enables trace-level output from the logging module.

See also

RTI_MQTT_USE_TRACE RTI_MQTT_ENABLE_LOG

MQTT_CLIENT_API: A macro which can be used to guard code based on the MQTT Client Library in use.

3.1.2. Automatic Defines

group RtiMqtt_Compiler_Auto

Defines

RTI_MQTT_USE_SSL

Flag that can be used to guard code related to SSL/TLS functionality.

This flag is automatically defined based on the presence (or absence) of RTI_MQTT_ENABLE_SSL. It should not be defined manually by user.

See also

RTI_MQTT_ENABLE_SSL

RTI_MQTT_USE_STATIC_TYPES: Flag that can be used to enable use of static types instead of DDS_DynamicData in the library interfaces.

RTI_MQTT_USE_LOG: Flag that can be used to guard code related to logging.

RTI_MQTT_USE_TRACE: Flag used to guard code generating trace-level logging output.

RTI_MQTT_DYNAMIC_TYPES: Flag that controls the default configuration of RTI_MQTT_Publication and RTI_MQTT_Subscription with respect to the internal use of DDS_DynamicData samples or statically typed data.

3.1.3. Platform Defines

group RtiMqtt_Compiler_Platform

The MQTT Adapter exposes some macros which allow users to more easily write platform-specific code.

Code can be guarded on different values of RTI_MQTT_PLATFORM to selectively compile it only on specific target platforms.

Defines

RTI_MQTT_PLATFORM_UNKNOWN

Identifier for an unknown platform.

This value is defined only as a default when automatic platform detection fails. It should not be used to guard code.

RTI_MQTT_PLATFORM_POSIX: Identifier for POSIX compliant platforms.

RTI_MQTT_PLATFORM_WINDOWS: Identifier for Windows platforms.

3.1.4. MQTT Library Defines

group RtiMqtt_Client_Library

The MQTT Adapter relies on an external MQTT Client Library to provide the basic MQTT functionalities required to connect to an MQTT Broker, and to exchange data with it.

By default, the Paho Asynchronous C API will be used.

Currently no other MQTT Client Library is supported, but the Mosquitto Client API might be supported soon.

Defines

MQTT_CLIENT_API_PAHO_C: Macro constant identifying the “Paho Asynchronous C API”.

MQTT_CLIENT_API_MOSQUITTO: Macro constant identifying the “Mosquitto Client API”.

MQTT_CLIENT_API_DEFAULT: Macro constant defining the default MQTT Client Library.

3.2. MQTT Client API

group RtiMqtt_Client: The MQTT Adapter implements a simple MQTT Client API which wraps an external MQTT client library to expose an interface whose operations more closely match the behavior of a RTI::RoutingService::MessageWriter or RTI::RoutingService::MessageReader.

3.2.1. MQTT Configuration

group RtiMqtt_Client_Configuration

3.2.1.1. MQTT Client Configuration

group RtiMqtt_Client_Configuration_Client

Defines

RTI_MQTT_ClientConfig_INITIALIZER: Default initializer for static values of RTI_MQTT_ClientConfig.

Functions

DDS_ReturnCode_t RTI_MQTT_ClientConfig_default(RTI_MQTT_ClientConfig **config_out)

Allocate or initialize an RTI_MQTT_ClientConfig with default configuration properties.

Parameters: config_out – If a value is passed, the RTI_MQTT_ClientConfig will be initialized. Otherwise, config_out will be used to return the new instance of RTI_MQTT_ClientConfig allocated by this function.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_ClientConfig was successfully initialized with default properties (and possibly allocated), DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_ClientConfig_new(DDS_Boolean allocate_optional, RTI_MQTT_ClientConfig **config_out)

Allocate and initialize a new RTI_MQTT_ClientConfig.

Each attribute will be initialize to the default value of its data type.

See also

RTI_MQTT_ClientConfig_delete

Parameters

allocate_optional – A flag controlling whether optional fiels of RTI_MQTT_ClientConfig should also be allocated with a default value.
config_out – The newly created RTI_MQTT_ClientConfig will be returned through this paramter.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_ClientConfig was successfully created, DDS_RETCODE_ERROR otherwise.

void RTI_MQTT_ClientConfig_delete(RTI_MQTT_ClientConfig *self)

Delete an RTI_MQTT_ClientConfig.

See also

RTI_MQTT_ClientConfig_new

Parameters: self – The RTI_MQTT_ClientConfig to delete.

Variables

const RTI_MQTT_ClientConfig RTI_MQTT_ClientConfig_DEFAULT: The default configuration of an RTI_MQTT_Client if no other configuration property is specified.

3.2.1.2. MQTT Subscription Configuration

group RtiMqtt_Client_Configuration_Subscription

Configuration

Defines

RTI_MQTT_SubscriptionConfig_INITIALIZER: Default initializer for static values of RTI_MQTT_SubscriptionConfig.

Functions

DDS_ReturnCode_t RTI_MQTT_SubscriptionConfig_default(RTI_MQTT_SubscriptionConfig **config_out)

Allocate or initialize an RTI_MQTT_SubscriptionConfig with default configuration properties.

Parameters: config_out – If a value is passed, the RTI_MQTT_SubscriptionConfig will be initialized. Otherwise, config_out will be used to return the new instance of RTI_MQTT_SubscriptionConfig allocated by this function.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_SubscriptionConfig was successfully initialized with default properties (and possibly allocated), DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_SubscriptionConfig_new(DDS_Boolean allocate_optional, RTI_MQTT_SubscriptionConfig **config_out)

Allocate and initialize a new RTI_MQTT_SubscriptionConfig.

Each attribute will be initialize to the default value of its data type.

See also

RTI_MQTT_SubscriptionConfig_delete

Parameters

allocate_optional – A flag controlling whether optional fiels of RTI_MQTT_SubscriptionConfig should also be allocated with a default value.
config_out – The newly created RTI_MQTT_SubscriptionConfig will be returned through this paramter.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_SubscriptionConfig was successfully created, DDS_RETCODE_ERROR otherwise.

void RTI_MQTT_SubscriptionConfig_delete(RTI_MQTT_SubscriptionConfig *self)

Delete an RTI_MQTT_SubscriptionConfig.

See also

RTI_MQTT_SubscriptionConfig_new

Parameters: self – The RTI_MQTT_SubscriptionConfig to delete.

Variables

const RTI_MQTT_SubscriptionConfig RTI_MQTT_SubscriptionConfig_DEFAULT: The default configuration of an RTI_MQTT_Subscription if no other configuration property is specified.

3.2.1.3. MQTT Publication Configuration

group RtiMqtt_Client_Configuration_Publication

Configuration

Defines

RTI_MQTT_PublicationConfig_INITIALIZER: Default initializer for static values of RTI_MQTT_PublicationConfig.

RTI_MQTT_WriteParams_INITIALIZER: Default initializer for static values of RTI_MQTT_WriteParams.

Functions

DDS_ReturnCode_t RTI_MQTT_PublicationConfig_default(RTI_MQTT_PublicationConfig **config_out)

Allocate or initialize an RTI_MQTT_PublicationConfig with default configuration properties.

Parameters: config_out – If a value is passed, the RTI_MQTT_PublicationConfig will be initialized. Otherwise, config_out will be used to return the new instance of RTI_MQTT_PublicationConfig allocated by this function.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_PublicationConfig was successfully initialized with default properties (and possibly allocated), DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_PublicationConfig_new(DDS_Boolean allocate_optional, RTI_MQTT_PublicationConfig **config_out)

Allocate and initialize a new RTI_MQTT_PublicationConfig.

Each attribute will be initialize to the default value of its data type.

See also

RTI_MQTT_PublicationConfig_delete

Parameters

allocate_optional – A flag controlling whether optional fiels of RTI_MQTT_PublicationConfig should also be allocated with a default value.
config_out – The newly created RTI_MQTT_PublicationConfig will be returned through this paramter.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_PublicationConfig was successfully created, DDS_RETCODE_ERROR otherwise.

void RTI_MQTT_PublicationConfig_delete(RTI_MQTT_PublicationConfig *self)

Delete an RTI_MQTT_PublicationConfig.

See also

RTI_MQTT_PublicationConfig_new

Parameters: self – The RTI_MQTT_PublicationConfig to delete.

Variables

const RTI_MQTT_PublicationConfig RTI_MQTT_PublicationConfig_DEFAULT: The default configuration of an RTI_MQTT_Publication if no other configuration property is specified.

3.2.1.4. Configuration Infrastructure

group RtiMqtt_Client_Configuration_Infrastructure

Infrastructure

Defines

RTI_MQTT_Time_INITIALIZER(sec_, nsec_): A macro that can be used to initialize static values of RTI_MQTT_Time with a certain seconds and nanoseconds components.

Variables

const RTI_MQTT_Time RTI_MQTT_Time_ZERO: An RTI_MQTT_Time instance representing a zero duration or instant in time.

const RTI_MQTT_Time RTI_MQTT_Time_INFINITE: An RTI_MQTT_Time instance representing an infinite duration or an infinitely distant moment in time.

3.2.2. MQTT Client

group RtiMqtt_Client_Client

Functions

DDS_ReturnCode_t RTI_MQTT_Client_new(RTI_MQTT_ClientConfig *config, struct RTI_MQTT_Client **client_out)

Allocate and initialize a new RTI_MQTT_Client from the specified configuration.

The new client will be created in DISCONNECTED state.

See also

RTI_MQTT_Client_delete

Parameters

config – the configuration for the new RTI_MQTT_Client.
client_out – The new RTI_MQTT_Client upon success, or NULL on failure.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_Client was successfully allocated and initialized, DDS_RETCODE_ERROR if an error occurred.

void RTI_MQTT_Client_delete(struct RTI_MQTT_Client *self)

Delete and existing RTI_MQTT_Client.

The client will be destroyed without disconnecting from the Broker.

See also

RTI_MQTT_Client_new

Parameters: self – the RTI_MQTT_Client to delete.

DDS_ReturnCode_t RTI_MQTT_Client_connect(struct RTI_MQTT_Client *self)

Establish a connection between an RTI_MQTT_Client and one of its MQTT Brokers.

The RTI_MQTT_Client will transition into CONNECTING state, and it will try to establish a connection with the first Broker in the list stored by its configuration.

If a connection cannot be established within the configured maximum timeout, this function will fail, and the RTI_MQTT_Client will transition to DISCONNECTED state.

Once a connection has been successfully established, the RTI_MQTT_Client will transition to CONNECTED state.

See also

RTI_MQTT_Client_disconnect

Parameters: self – the RTI_MQTT_Client to connect
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if a connection was successfully established, or DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Client_disconnect(struct RTI_MQTT_Client *self)

Terminate the connection between an RTI_MQTT_Client and its MQTT Broker.

If the client is in CONNECTED state, this operation will send a disconnection request to the associated MQTT Broker, and wait for a reply to guarantee a clean disconnection.

If requested by configuration, all subscriptions currently owned by the RTI_MQTT_Client will be deleted on the MQTT Broker before disconnection.

If the client is not in CONNECTED state, this operation will do nothing.

See also

RTI_MQTT_Client_connect

Parameters: self – the RTI_MQTT_Client to disconnect.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the connection was successfully terminated, or DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Client_subscribe(struct RTI_MQTT_Client *self, RTI_MQTT_SubscriptionConfig *config, struct RTI_MQTT_Subscription **sub_out)

Create a new subscription to MQTT data.

This operation will create a new RTI_MQTT_Subscription owned by the RTI_MQTT_Client, to represent one or more subscriptions on the associated MQTT Broker.

The RTI_MQTT_Client will request the creation of new subscription of the MQTT Broker based on the specified configuration.

This operation will fail if the RTI_MQTT_Client is not in CONNECTED state.

See also

RTI_MQTT_Client_unsubscribe

Parameters

self – the RTI_MQTT_Client for which a subscription is to be created.
config – the configuration of the new RTI_MQTT_Subscription
sub_out – the new RTI_MQTT_Subscription upon success, or NULL upon failure.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the new subscription was successfully created, both locally and on the MQTT Broker, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Client_unsubscribe(struct RTI_MQTT_Client *self, struct RTI_MQTT_Subscription *sub)

Delete an existing subscription to MQTT data.

This operation will delete an existing RTI_MQTT_Subscription owned by the RTI_MQTT_Client.

The RTI_MQTT_Client will delete all subscriptions on the MQTT Broker that match the topic filters of the RTI_MQTT_Subscription.

This operation will fail if the RTI_MQTT_Client is not in CONNECTED state.

See also

RTI_MQTT_Client_subscribe

Parameters

self – the RTI_MQTT_Client that created the subscription
sub – the RTI_MQTT_Subscription to delete.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the subscription was successfully deleted, both locally and on the MQTT Broker, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Client_publish(struct RTI_MQTT_Client *self, RTI_MQTT_PublicationConfig *config, struct RTI_MQTT_Publication **pub_out)

Create a new output stream of MQTT data.

This operation will create a new RTI_MQTT_Publication owned by the RTI_MQTT_Client, which represents a stream of MQTT messages related either logically, or by means of common “topic”, “qos”, and “retained” configuration.

The creation of an RTI_MQTT_Publication is a local operation which doesn’t require any communication with the MQTT Broker.

Nonetheless, for symmetry with the creation of RTI_MQTT_Subscription objects, this operation will fail if the RTI_MQTT_Client is not in CONNECTED state.

See also

RTI_MQTT_Client_unpublish

Parameters

self – the RTI_MQTT_Client for which a publication is to be created.
config – the configuration of the new publication.
pub_out – the new RTI_MQTT_Publication upon success, or NULL upon failure.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the new RTI_MQTT_Publication was successfully created, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Client_unpublish(struct RTI_MQTT_Client *self, struct RTI_MQTT_Publication *pub)

Delete an existing output stream of MQTT data.

This operation will delete an existing RTI_MQTT_Publication owned by the RTI_MQTT_Client.

The deletion of an RTI_MQTT_Publication is a local operation which doesn’t require any communication with the MQTT Broker.

Nonetheless, for symmetry with the deletion of RTI_MQTT_Subscription objects, this operation will fail if the RTI_MQTT_Client is not in CONNECTED state.

See also

RTI_MQTT_Client_publish

Parameters

self – the RTI_MQTT_Client that created the publication.
pub – the RTI_MQTT_Publication to delete.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the RTI_MQTT_Publication was successfully deleted, DDS_RETCODE_ERROR otherwise.

const char *RTI_MQTT_Client_get_id(struct RTI_MQTT_Client *self)

Access the MQTT identifier of an RTI_MQTT_Client.

This value comes from the associated configuration object.

Parameters: self – an RTI_MQTT_Client
Returns: const char* the MQTT identifier used by the RTI_MQTT_Client when connecting to an MQTT Broker.

3.2.3. MQTT Subscription

group RtiMqtt_Client_Subscription

Defines

RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED: A constant that can be used to read all available messages from an RTI_MQTT_Subscription.

Typedefs

typedef void (*RTI_MQTT_Subscription_DataAvailableCallback)(void *listener_data, struct RTI_MQTT_Subscription *sub)

Prototype of callback to receive notification of new data received on an RTI_MQTT_Subscription.

Param listener_data: A “state object” that was specified when the callback was registered on the RTI_MQTT_Subscription.
Param sub: The RTI_MQTT_Subscription with new data available.

Functions

DDS_ReturnCode_t RTI_MQTT_Subscription_set_data_available_listener(struct RTI_MQTT_Subscription *self, RTI_MQTT_Subscription_DataAvailableCallback listener, void *listener_data)

Set the listener callback that will be notified by the RTI_MQTT_Subscription when it has new data available.

Parameters

self – the RTI_MQTT_Subscription on which to set the lister
listener – a callback that will be called every time the RTI_MQTT_Subscription has new data available.
listener_data – An optional “state object” that will be passed to the listener callback every time it is invoked.

Returns

DDS_ReturnCode_t DDs_RETCODE_OK if the listener was successfully set, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Subscription_read(struct RTI_MQTT_Subscription *self, DDS_UnsignedLong max_messages, struct DDS_DynamicDataSeq *messages)

Read available messages as DDS_DynamicData samples.

If RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED is used (and a buffer is loaned by the RTI_MQTT_Subscription), no other read may be performed until RTI_MQTT_Subscription_return_loan is called.

Parameters

self – The RTI_MQTT_Subscription from which to read messages.
max_messages – Maximum number of new messages to read. RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED may be used to read all available messages.
messages – A sequence of size max_messages where new messages will be read. If RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED is used, then the sequence must not have a buffer allocated, as it will be loaned one by the RTI_MQTT_Subscription.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if new messages were read successfully, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Subscription_return_loan(struct RTI_MQTT_Subscription *self, struct DDS_DynamicDataSeq *messages)

Return DDS_DynamicData samples read from an RTI_MQTT_Subscription.

This function must be called after calling RTI_MQTT_Subscription_read with RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED

See also

RTI_MQTT_Subscription_read

Parameters

self – the RTI_MQTT_Subscription from which the messages were read.
messages – The messages to return.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the messages were successfully return, DDS_RETCODE_ERROR otherwise.

3.2.4. MQTT Publication

group RtiMqtt_Client_Publication

Functions

DDS_ReturnCode_t RTI_MQTT_Publication_write(struct RTI_MQTT_Publication *self, DDS_DynamicData *message)

Write an MQTT message from a DDS_DynamicData sample.

The payload of the specified message will be published to MQTT.

The “publication settings” (e.g. topic, qos, retained flag…) will be either determined from the RTI_MQTT_Publication’s configuration, of from message’s info field, if use_message_info is enabled. In this case, the operatio will fail if message.info is empty.

Parameters

self – the RTI_MQTT_Publication used to write the MQTT message.
message – The message to write.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the message was successfully published to the associated MQTT Broker, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Publication_write_w_params(struct RTI_MQTT_Publication *self, const char *buffer, DDS_UnsignedLong buffer_len, const char *topic, RTI_MQTT_WriteParams *params)

Write an MQTT message from a raw buffer, using custom write parameters.

This operation will bypass the RTI_MQTT_Publication’s configuration and publish the specified buffer

to MQTT using the provided “publication

settings”.

Parameters

self – the RTI_MQTT_Publication used to write the MQTT message.
buffer – The buffer to write.
buffer_len – Size of buffer.
topic – MQTT topic to which the message will be published.
params – Publication settings for writing the message to MQTT.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the message was successfully published to the associated MQTT Broker, DDS_RETCODE_ERROR otherwise.

3.2.5. MQTT Message

group RtiMqtt_Client_Message

Functions

DDS_ReturnCode_t RTI_MQTT_Message_to_dynamic_data(RTI_MQTT_Message *self, DDS_DynamicData *sample)

Convert an RTI_MQTT_Message sample into a DDS_DynamicData sample.

Parameters

self – The RTI_MQTT_Message to convert.
sample – The DDS_DynamicData sample that will be set.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the sample was successfully converted, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Message_from_dynamic_data(RTI_MQTT_Message *self, DDS_DynamicData *sample)

Convert a DDS_DynamicData sample into an RTI_MQTT_Message sample.

Parameters

self – The RTI_MQTT_Message that will be set.
sample – The DDS_DynamicData to convert.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the sample was successfully converted, DDS_RETCODE_ERROR otherwise.

3.2.6. Platform Support

group RtiMqtt_Client_Platform

Defines

RTI_MQTT_MUTEX_POSIX: Native type to represent a mutex on POSIX platforms.

RTI_MQTT_MUTEX_INITIALIZER_POSIX

RTI_MQTT_MUTEX_WINDOWS: Native type to represent a mutex on Windows platforms.

RTI_MQTT_MUTEX_INITIALIZER_WINDOWS

RTI_MQTT_MUTEX_NATIVE: Native type to represent a mutex on current build platform.

RTI_MQTT_MUTEX_INITIALIZER_NATIVE

RTI_MQTT_Mutex_INITIALIZER

RTI_MQTT_Mutex_assert(m_): A macro to call RTI_MQTT_Mutex_take and abort the process if the operation fails.

RTI_MQTT_Mutex_release(m_): A macro to call RTI_MQTT_Mutex_give and abort the process if the operation fails.

RTI_MQTT_Mutex_assert_w_state(m_, l_): A macro to call RTI_MQTT_Mutex_take, abort the process if the operation fails, and store the current state (locked or not locked) in a local variable.

RTI_MQTT_Mutex_release_w_state(m_, l_): A macro to call RTI_MQTT_Mutex_give, abort the process if the operation fails, and store the current state (locked or not locked) in a local variable.

RTI_MQTT_Mutex_release_from_state(m_, l_): A macro to call RTI_MQTT_Mutex_release if the specified state variable is true.

Typedefs

typedef void *(*RTI_MQTT_ThreadFn)(void *arg): Prototype of a thread function for RTI_MQTT_Thread_spawn.

typedef RTI_MQTT_MUTEX_NATIVE RTI_MQTT_Mutex: Mutex type for current build platform.

Functions

DDS_ReturnCode_t RTI_MQTT_Thread_spawn(RTI_MQTT_ThreadFn thread, void *arg, void **handle_out)

A portable abstraction for spawing user threads.

Parameters

thread – function to be executed by the thread
arg – optional argument that will be passed to the thread function
handle_out – If specified, a handle for the new thread will be returned via this parameter.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the thread was created and started successfully, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Thread_join(void *handle, void **result_out)

Join a thread and wait for its completion.

Parameters

handle – A handle for the thread to join.
result_out – The result value returned by the thread function.

Returns

DDS_ReturnCode_t DDS_RETCODE_OK if the thread joined successfully, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Mutex_initialize(RTI_MQTT_Mutex *self)

Initialize a new mutex.

Parameters: self – The mutex to initialize
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the mutex was successfully initialized, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Mutex_finalize(RTI_MQTT_Mutex *self)

Finalize an existing mutex.

Parameters: self – The mutex to finalize
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the mutex was successfully finalized, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Mutex_take(RTI_MQTT_Mutex *self)

Acquire ownership of a mutex.

Parameters: self – The mutex to acquire.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the mutex was successfully acquired, DDS_RETCODE_ERROR otherwise.

DDS_ReturnCode_t RTI_MQTT_Mutex_give(RTI_MQTT_Mutex *self)

Release ownership of a mutex.

Parameters: self – The mutex to relese.
Returns: DDS_ReturnCode_t DDS_RETCODE_OK if the mutex was successfully released, DDS_RETCODE_ERROR otherwise.

3.2.7. IDL Types

group RtiMqtt_Client_IDL

3.2.7.1. MQTT Configuration

group RtiMqtt_Client_IDL_Config

Enums

enum MqttProtocolVersion

todo

Values:

enumerator MQTT_DEFAULT: todo

enumerator MQTT_3_1: todo

enumerator MQTT_3_1_1: todo

enumerator MQTT_5: todo

enum SslTlsProtocolVersion

todo

Values:

enumerator TLS_DEFAULT: todo

enumerator TLS_1_0: todo

enumerator TLS_1_1: todo

enumerator TLS_1_2: todo

enum PersistenceLevel

todo

Values:

enumerator NONE: todo

enumerator DURABLE: todo

struct Time

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

int32 seconds: todo

uint32 nanoseconds: todo

struct SslTlsConfig

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

string ca: todo

string identity: todo

string private_key: todo

string private_key_password: todo

SslTlsProtocolVersion protocol_version: todo

boolean verify_server_certificate: todo

string cypher_suites: todo

struct ClientConfig

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Types

typedef sequence<string> server_uris: todo

typedef sequence<octet> password: todo

Public Members

string id: todo

MqttProtocolVersion protocol_version: todo

Time connect_timeout: todo

uint32 max_connection_retries: todo

Time keep_alive_period: todo

boolean clean_session: todo

boolean unsubscribe_on_disconnect: todo

Time max_reply_timeout: todo

boolean reconnect: todo

uint32 max_unack_messages: todo

PersistenceLevel persistence_level: todo

string persistence_storage: todo

string username: todo

SslTlsConfig ssl_tls_config: todo

struct SubscriptionConfig

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Types

typedef sequence<string> topic_filters: todo

Public Members

QosLevel max_qos: todo

uint32 message_queue_size: todo

struct PublicationConfig

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

string topic: todo

QosLevel qos: todo

boolean retained: todo

boolean use_message_info: todo

Time max_wait_time: todo

3.2.7.2. MQTT Message

group RtiMqtt_Client_IDL_Message

Enums

enum QosLevel

An enum to model the “Quality of Service levels” offered by the MQTT Protocol for publication and subscription of messages.

Values:

enumerator UNKNOWN: Constant used to represent an invalid Qos value.

enumerator ZERO: MQTT Qos level 0.

enumerator ONE: MQTT Qos level 1.

enumerator TWO: MQTT Qos level 2.

struct MessageInfo

#include <rtiadapt_mqtt_types_message.idl>

A data type to model the metadata associated with any MQTT message.

Public Members

int32 id: Id of the MQTT message.

QosLevel qos_level: Qos level used to publish the MQTT message.

boolean retained: Retained flag of the MQTT message.

boolean duplicate: Duplicate flag of the MQTT message.

struct MessagePayload

#include <rtiadapt_mqtt_types_message.idl>

A data type to model the payload of an MQTT message as an “opaque” buffer of bytes.

Public Types

typedef sequence<octet> data: Contents of the MQTT message.

struct Message

#include <rtiadapt_mqtt_types_message.idl>

A data type to model the data and metadata associated with an MQTT message.

Public Members

string topic: Topic where the MQTT message was published.

MessageInfo info: Metadata associated with the MQTT message.

MessagePayload payload: Contents of the MQTT message.

struct KeyedMessage

#include <rtiadapt_mqtt_types_message.idl>

A data type to model the data and metadata associated with an MQTT message, with the MQTT topic used as key.

Public Members

key string topic

Topic where the MQTT message was published.

This field will be used as @key of a DDS_Topic created with type RTI::MQTT::KeyedMessage.

MessageInfo info: Metadata associated with the MQTT message.

MessagePayload payload: Contents of the MQTT message.

3.2.7.3. MQTT Client

group RtiMqtt_Client_IDL_Client

Enums

enum ClientStateKind

todo

Values:

enumerator DISCONNECTED: todo

enumerator DISCONNECTING: todo

enumerator CONNECTING: todo

enumerator CONNECTED: todo

enumerator ERROR: todo

struct ClientStatus

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Types

typedef sequence<SubscriptionStatus> subscriptions: todo

typedef sequence<PublicationStatus> publications: todo

Public Members

ClientStateKind state: todo

ClientConfig config: todo

3.2.7.4. MQTT Subscription

group RtiMqtt_Client_IDL_Subscription

Enums

enum SubscriptionStateKind

todo

Values:

enumerator CREATED: todo

enumerator SUBSCRIBED: todo

enumerator ERROR: todo

struct SubscriptionMessageStatus

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

uint32 received_count: todo

uint32 unread_count: todo

uint32 read_count: todo

uint32 lost_count: todo

struct SubscriptionStatus

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

SubscriptionConfig config: todo

SubscriptionMessageStatus message_status: todo

struct SubscriptionParams

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

string topic: todo

QosLevel max_qos: todo

3.2.7.5. MQTT Publication

group RtiMqtt_Client_IDL_Publication

struct PublicationMessageStatus

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

uint32 sent_count: todo

uint32 pending_count: todo

uint32 ok_count: todo

uint32 error_count: todo

struct PublicationStatus

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

PublicationConfig config: todo

PublicationMessageStatus message_status: todo

struct WriteParams

#include <rtiadapt_mqtt_types_client.idl>

todo

Public Members

QosLevel qos_level: todo

boolean retained: todo

3.3. RTI Routing Service Adapter Plugin

group RtiMqtt_Adapter

The MQTT Adapter implements the Routing Service Adapter API to allow the creation of RTI::RoutingService::Connection, RTI::RoutingService::MessageReader, and RTI::RoutingService::MessageWriter objects, and access to the MQTT “data domain”.

Defines

RTI_RS_MQTT_ADAPTER_VERSION_MAJOR: Major part of the MQTT Adapter version identifier.

RTI_RS_MQTT_ADAPTER_VERSION_MINOR: Minor part of the MQTT Adapter version identifier.

RTI_RS_MQTT_ADAPTER_VERSION_RELEASE: Release part of the MQTT Adapter version identifier.

RTI_RS_MQTT_ADAPTER_VERSION_REVISION: Revision part of the MQTT Adapter version identifier.

Functions

struct RTI_RoutingServiceAdapterPlugin *RTI_RS_MQTT_AdapterPlugin_create(const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env): Constructor function used to load the MQTT Adapter on RTI Routing Service.

Variables

const struct RTI_RoutingServiceVersion RTI_RS_MQTT_AdapterPlugin_VERSION: A constant containing the version identifier of the MQTT Adapter library.

3.4. Configuration Properties

group RtiMqtt_Properties

The MQTT Adapter’s behavior can be configured with (key,value) properties.

Accepted configuration keys are exposed as macro string literals.

3.4.1. MQTT Client Configuration

group RtiMqtt_Properties_Client

Defines

RTI_MQTT_PROPERTY_PREFIX_CLIENT: Common prefix for all configuration properties accepted by RTI_MQTT_Client.

RTI_MQTT_PROPERTY_PREFIX_CLIENT_SSL: Common prefix for all configuration properties accepted by RTI_MQTT_Client to control supported SSL/TLS functions.

RTI_MQTT_PROPERTY_CLIENT_ID: Configuration property to specify the “client id” sent by an RTI_MQTT_Client to an MQTT Broker during connection.

RTI_MQTT_PROPERTY_CLIENT_PROTOCOL_VERSION

Configuration property to select the MQTT protocol version used by an RTI_MQTT_Client.

Accepted values:

default
3.1
3.1.1
5

RTI_MQTT_PROPERTY_CLIENT_SERVERS

Configuration property to specify a list of MQTT Broker URIs to which an RTI_MQTT_Client will try to connect.

The value of this property must be a list of semicolon separated URIs.

Broker URIs take the form:

TCP Connection: tcp://<address>:<port>
SSL/TLS Connection:ssl://<address>:<port>

RTI_MQTT_PROPERTY_CLIENT_CONNECTION_TIMEOUT: Common prefix for configuration properties that control the maximum timeout for establishing a connection between an RTI_MQTT_Client, and an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_CONNECTION_TIMEOUT_SECONDS: Configuration property to specify the seconds component of the maximum timeout for establishing a connection between an RTI_MQTT_Client, and an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_CONNECTION_TIMEOUT_NANOSECONDS: Configuration property to specify the nanoseconds component of the maximum timeout for establishing a connection between an RTI_MQTT_Client, and an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_MAX_CONNECTION_RETRIES: Configuration property to specify the maximum number of attempts that an RTI_MQTT_Client will perform to establish a connection to an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_KEEP_ALIVE_PERIOD: Common prefix for configuration properties controlling the “keep alive period” between an RTI_MQTT_Client and its MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_KEEP_ALIVE_PERIOD_SECONDS: Configuration property to specity the seconds component of the “keep alive period” between an RTI_MQTT_Client and its MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_KEEP_ALIVE_PERIOD_NANOSECONDS: Configuration property to specity the nanoseconds component of the “keep alive period” between an RTI_MQTT_Client and its MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_CLEAN_SESSION: Configuration property to select whether an RTI_MQTT_Client should set the “clean session” flag when establishing a connection to an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_UNSUBSCRIBE_ON_DISCONNECT: Configuration property controlling whether an RTI_MQTT_Client should delete all the subscriptions it created before disconnecting from an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_MAX_REPLY_TIMEOUT: Common prefix for configuration properties which control the maximum time for which an RTI_MQTT_Client will wait to receive a reply from an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_MAX_REPLY_TIMEOUT_SECONDS: Configuration property to specify the seconds component of the maximum time for which an RTI_MQTT_Client will wait to receive a reply from an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_MAX_REPLY_TIMEOUT_NANOSECONDS: Configuration property to specify the nanoseconds component of the maximum time for which an RTI_MQTT_Client will wait to receive a reply from an MQTT Broker.

RTI_MQTT_PROPERTY_CLIENT_RECONNECT: Configuration property controlling whether an RTI_MQTT_Client will try to re-establish a connection to an MQTT Broker when an existing one is lost.

RTI_MQTT_PROPERTY_CLIENT_MAX_UNACK_MESSAGES: Configuration property to specity the maximum number of unacknowledged messages at MQTT Qos 1 or 2, that an RTI_MQTT_Client is allowed to have at any time.

RTI_MQTT_PROPERTY_CLIENT_PERSISTENCE

Configuration property to select the type of storage use by an RTI_MQTT_Client to persist MQTT session data.

Accepted values:

none
durable

RTI_MQTT_PROPERTY_CLIENT_PERSISTENCE_STORAGE: Configuration property specifying the path where an RTI_MQTT_Client will store persistent MQTT session data.

RTI_MQTT_PROPERTY_CLIENT_USERNAME: Configuration property to select the “username” that an RTI_MQTT_Client will send to an MQTT Broker during connection.

RTI_MQTT_PROPERTY_CLIENT_PASSWORD: Configuration property to select the “password” that an RTI_MQTT_Client will send to an MQTT Broker during connection.

3.4.2. MQTT Subscription Configuration

group RtiMqtt_Properties_Subscription

Defines

RTI_MQTT_PROPERTY_PREFIX_SUBSCRIPTION: Common prefix for all configuration properties accepted by RTI_MQTT_Subscription.

RTI_MQTT_PROPERTY_SUBSCRIPTION_TOPICS: Configuration property to specify the list of topic filters used by an RTI_MQTT_Subscription to subscribe to data on an MQTT Broker.

RTI_MQTT_PROPERTY_SUBSCRIPTION_MAX_QOS: Configuration property controlling the maximum MQTT Qos level used to deliver MQTT data to an RTI_MQTT_Subscription.

RTI_MQTT_PROPERTY_SUBSCRIPTION_QUEUE_SIZE: Configuration property to control the size of the message queue in an RTI_MQTT_Subscription.

3.4.3. MQTT Publication Configuration

group RtiMqtt_Properties_Publication

Defines

RTI_MQTT_PROPERTY_PREFIX_PUBLICATION: Common prefix for all configuration properties accepted by RTI_MQTT_Publication.

RTI_MQTT_PROPERTY_PUBLICATION_TOPIC: Configuration property to specify the MQTT topic to which all messages written by an RTI_MQTT_Publication will be published.

RTI_MQTT_PROPERTY_PUBLICATION_QOS: Configuration property to specify the MQTT Qos level used to publish all messages written by an RTI_MQTT_Publication.

RTI_MQTT_PROPERTY_PUBLICATION_RETAINED: Configuration property to control whether messages written by an RTI_MQTT_Publication should be “retained” by the MQTT Broker.

RTI_MQTT_PROPERTY_PUBLICATION_USE_MESSAGE_INFO: Configuration property to control whether an RTI_MQTT_Publication should determine “topic”, “qos”, and “retained” information for each written message from the message’s “info” attribute, or from the RTI_MQTT_Publication’s other properties.

RTI_MQTT_PROPERTY_PUBLICATION_MAX_WAIT_TIME: Common prefix for configuration properties controlling the maximum time for which an RTI_MQTT_Publication will wait to receive an acknowledgement to a message published with MQTT Qos 1 or 2.

RTI_MQTT_PROPERTY_PUBLICATION_MAX_WAIT_TIME_SECONDS: Configuration property to specify the seconds components of the maximum time for which an RTI_MQTT_Publication will wait to receive an acknowledgement to a message published with MQTT Qos 1 or 2.

RTI_MQTT_PROPERTY_PUBLICATION_MAX_WAIT_TIME_NANOSECONDS: Configuration property to specify the nanoseconds components of the maximum time for which an RTI_MQTT_Publication will wait to receive an acknowledgement to a message published with MQTT Qos 1 or 2.