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_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
, andRTI_MQTT_KeyedMessage
, instead ofDDS_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_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_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_ENABLE_TRACE
Compiler flag that enables trace-level output from the logging module.
See also
-
MQTT_CLIENT_API
A macro which can be used to guard code based on the MQTT Client Library in use.
-
RTI_MQTT_PLATFORM
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_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
andRTI_MQTT_Subscription
with respect to the internal use ofDDS_DynamicData
samples or statically typed data.
-
RTI_MQTT_USE_SSL
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.
-
RTI_MQTT_PLATFORM_UNKNOWN
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.
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
orRTI::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 ofRTI_MQTT_ClientConfig
allocated by this function.- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if theRTI_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
- 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 theRTI_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
- 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.
-
RTI_MQTT_ClientConfig_INITIALIZER
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 ofRTI_MQTT_SubscriptionConfig
allocated by this function.- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if theRTI_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
- 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 theRTI_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
- 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.
-
RTI_MQTT_SubscriptionConfig_INITIALIZER
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 ofRTI_MQTT_PublicationConfig
allocated by this function.- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if theRTI_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
- 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 theRTI_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
- 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.
-
RTI_MQTT_PublicationConfig_INITIALIZER
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.
-
RTI_MQTT_Time_INITIALIZER(sec_, nsec_)
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
- Parameters
config – the configuration for the new
RTI_MQTT_Client
.client_out – The new
RTI_MQTT_Client
upon success, orNULL
on failure.
- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if theRTI_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
- 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 intoCONNECTING
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 toDISCONNECTED
state.Once a connection has been successfully established, the
RTI_MQTT_Client
will transition toCONNECTED
state.See also
- Parameters
self – the
RTI_MQTT_Client
to connect- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if a connection was successfully established, orDDS_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
- Parameters
self – the
RTI_MQTT_Client
to disconnect.- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if the connection was successfully terminated, orDDS_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 theRTI_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 inCONNECTED
state.See also
- 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, orNULL
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 theRTI_MQTT_Client
.The
RTI_MQTT_Client
will delete all subscriptions on the MQTT Broker that match the topic filters of theRTI_MQTT_Subscription
.This operation will fail if the
RTI_MQTT_Client
is not inCONNECTED
state.See also
- Parameters
self – the
RTI_MQTT_Client
that created the subscriptionsub – 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 theRTI_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 theRTI_MQTT_Client
is not inCONNECTED
state.See also
- 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, orNULL
upon failure.
- Returns
DDS_ReturnCode_t
DDS_RETCODE_OK
if the newRTI_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 theRTI_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 theRTI_MQTT_Client
is not inCONNECTED
state.See also
- 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 theRTI_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.
-
DDS_ReturnCode_t RTI_MQTT_Client_new(RTI_MQTT_ClientConfig *config, struct RTI_MQTT_Client **client_out)
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 listerlistener – 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.See also
RTI_MQTT_Subscription_return_loan RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED RTI_MQTT_Subscription_read
- 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 theRTI_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 anRTI_MQTT_Subscription
.This function must be called after calling RTI_MQTT_Subscription_read with RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED
See also
- 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.
-
RTI_MQTT_SUBSCRIPTION_READ_LENGTH_UNLIMITED
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 frommessage
’sinfo
field, ifuse_message_info
is enabled. In this case, the operatio will fail ifmessage.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 specifiedbuffer
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.
-
DDS_ReturnCode_t RTI_MQTT_Publication_write(struct RTI_MQTT_Publication *self, DDS_DynamicData *message)
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 aDDS_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 anRTI_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.
-
DDS_ReturnCode_t RTI_MQTT_Message_to_dynamic_data(RTI_MQTT_Message *self, DDS_DynamicData *sample)
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.
-
RTI_MQTT_MUTEX_POSIX
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
-
enumerator MQTT_DEFAULT
-
struct Time
- #include <rtiadapt_mqtt_types_client.idl>
todo
-
struct SslTlsConfig
- #include <rtiadapt_mqtt_types_client.idl>
todo
-
struct ClientConfig
- #include <rtiadapt_mqtt_types_client.idl>
todo
Public Members
-
string id
todo
-
MqttProtocolVersion protocol_version
todo
-
uint32 max_connection_retries
todo
-
boolean clean_session
todo
-
boolean unsubscribe_on_disconnect
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
-
string id
-
struct SubscriptionConfig
- #include <rtiadapt_mqtt_types_client.idl>
todo
Public Types
-
typedef sequence<string> topic_filters
todo
-
typedef sequence<string> topic_filters
-
struct PublicationConfig
- #include <rtiadapt_mqtt_types_client.idl>
todo
-
enum MqttProtocolVersion
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.
-
enumerator UNKNOWN
-
struct MessageInfo
- #include <rtiadapt_mqtt_types_message.idl>
A data type to model the metadata associated with any 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.
-
typedef sequence<octet> data
-
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.
-
string topic
-
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 aDDS_Topic
created with type RTI::MQTT::KeyedMessage.
-
MessageInfo info
Metadata associated with the MQTT message.
-
MessagePayload payload
Contents of the MQTT message.
-
enum QosLevel
3.2.7.3. MQTT Client
- group RtiMqtt_Client_IDL_Client
Enums
-
struct ClientStatus
- #include <rtiadapt_mqtt_types_client.idl>
todo
Public Types
-
typedef sequence<SubscriptionStatus> subscriptions
todo
-
typedef sequence<PublicationStatus> publications
todo
-
typedef sequence<SubscriptionStatus> subscriptions
-
struct ClientStatus
3.2.7.4. MQTT Subscription
3.2.7.5. MQTT Publication
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
, andRTI::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.
-
RTI_RS_MQTT_ADAPTER_VERSION_MAJOR
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.
-
RTI_MQTT_PROPERTY_PREFIX_CLIENT
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
.
-
RTI_MQTT_PROPERTY_PREFIX_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 theRTI_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.
-
RTI_MQTT_PROPERTY_PREFIX_PUBLICATION