mqtt_client

IMqttClient is a MQTT 5 client interface.
Note: Only MQTT version 5 is officially supported. WebSocket transport is not supported. For more information, refer to MQTT v5.0 spec .

File information

File	common/interface/mqtt_client.h
Public functions	Create MQTTConnect MQTTSubscribe MQTTPublish MQTTUnsubscribe MQTTPing MQTTDisconnect MQTTSendAuthData GetAliasByTopicName GetNameByTopicAlias
Classes	IMqttClient UMqttClient
Data types	MqttError MQTTReasonCode MQTTAuthReasonCode MQTTClientDisconnectReason
Structs	MqttUserProperty MqttConnectCredentials MqttWillOptions MqttConnectOptions MqttSubscribeOptions MqttPublishOptions MqttDisconnectOptions MqttAuthOptions MqttConnectAckInfo MqttPublishRecvInfo MqttPublishCompleteInfo
Examples	Code Example

Classes

IMqttClient

class IMqttClient {
public:
    static IMqttClient* Create(class IIoMux* const iomux,
        class ISocketProvider* const tcpSocketProvider,
        class ISocketProvider* const tlsSocketProvider,
        class UMqttClient* const user,
        class IInstanceLog* const log,
        class IDns* const dns);

    virtual MqttError MQTTConnect(const char* broker,
                                  char* outputClientId,
                                  size_t outputClientIdSize,
                                  const char* inputClientId = nullptr,
                                  const MqttConnectOptions& options = {}) = 0;

    virtual MqttError MQTTSubscribe(dword subscriptionIdentifier,
                                    const char* topicFilter,
                                    const MqttSubscribeOptions& options = {}) = 0;

    virtual MqttError MQTTPublish(const char* topicName,
                                  const MqttPublishOptions& options = {}) = 0;

    virtual MqttError MQTTUnsubscribe(const char* topicFilter,
                                      const MqttUserProperty& userProperty = {}) = 0;

    virtual MqttError MQTTPing() = 0;

    virtual MqttError MQTTDisconnect(const MqttDisconnectOptions& options = {}) = 0;

    virtual MqttError MQTTSendAuthData(const char* authenticationMethod,
                                       const byte* authenticationData,
                                       word authenticationDataSize,
                                       const MqttAuthOptions& options = {}) = 0;

    virtual word GetAliasByTopicName(const char* topicName) const = 0;
    virtual const char* GetNameByTopicAlias(word alias) const = 0;
};

This class is the main interface for MQTT client functionality. It allows connecting to a broker via either TCP or TLS socket, publishing and subscribing to one or multiple topics (separated by commas), sending pings, handling authentication, and more. The ClientId can either be generated if nothing is passed, or an explicit ClientId can be used if provided. If you want to generate an ID, be sure to pass a buffer of at least 24 bytes because the generated ID is 23 bytes plus the null terminator.

Optional parameters are grouped into structs (e.g., MqttConnectOptions, MqttPublishOptions). All struct fields have sensible defaults, so only the fields that are actually needed have to be set.

Subscription Identifiers: When subscribing, a subscription identifier can be provided (e.g., 12). The user of this interface should store these identifiers to handle incoming messages properly.

QoS: Allowed values are 0, 1, or 2. If another value is used, the function returns IncorrectValue.

User Properties: Can be provided with comma-separated names and comma-separated values via MqttUserProperty. They correspond index-wise, e.g. userProp1,userProp2 for names and val1,val2 for values. Each name must have a matching value. A mismatch in the count (e.g., two names, one value) leads to an error.

Topic Aliases: You can use topicAlias inside MqttPublishOptions to assign or reuse aliases. If a topic alias already exists, you can publish with the same alias to avoid resending the full topic name. (Details are described in the MQTT v5 specification.)

Public functions

Create (static function)

Creates an IMqttClient instance.

Parameters

IIoMux * const iomux	The iomux instance needed for socket communication.
ISocketProvider * const tcpSocketProvider	A socket provider to create a TCP socket for MQTT transport.
ISocketProvider * const tlsSocketProvider	A socket provider to create a TLS socket for secured MQTT (MQTT over TLS).
UMqttClient * const user	An `UMqttClient` instance to receive callbacks from `IMqttClient`.
IInstanceLog * const log	The log instance for logging.
IDns * const dns	An optional DNS instance for DNS resolution.

Return Value

The IMqttClient* instance. Must be deleted if no longer used.

MQTTConnect

Connects to an MQTT broker. Optional parameters are grouped in MqttConnectOptions, which itself embeds MqttConnectCredentials and MqttWillOptions. If the broker is secured (TLS), set options.tls = true and use the corresponding port (e.g., 8883) via options.port.