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
Examples	Code Example

Functions

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,
                                  word port = 1883,
                                  bool tls = false,
                                  const char* payloadUserName = nullptr,
                                  const byte* payloadPassword = nullptr,
                                  word payloadPasswordSize = 0,
                                  const char* inputClientId = nullptr,
                                  word keepAlive = 0,
                                  const char* willTopic = nullptr,
                                  const byte* willPayload = nullptr,
                                  word willPayloadSize = 0,
                                  byte willQoS = 0,
                                  bool willRetain = false,
                                  const char* userPropertyName = nullptr,
                                  const char* userPropertyValue = nullptr,
                                  dword sessionExpiryInterval = 0,
                                  const char* authenticationMethod = nullptr,
                                  const byte* authenticationData = nullptr,
                                  word authenticationDataSize = 0,
                                  word reciveMaximum = 65535,
                                  dword maximumPacketSize = 65535,
                                  word topicAliasMaximum = 0,
                                  bool requestResponseInformation = 0,
                                  bool requestProblemInformation = 1,
                                  dword willDelayInterval = 0,
                                  bool payloadFormatIndicator = 0,
                                  dword messageExpiryInterval = 0,
                                  const char* contentType = nullptr,
                                  const char* responseTopic = nullptr,
                                  const byte* correlationData = nullptr,
                                  word correlationDataSize = 0,
                                  const char* payloadUserPropertyName = nullptr,
                                  const char* payloadUserPropertyValue = nullptr) = 0;

    virtual MqttError MQTTSubscribe(word subscriptionIdentifier,
                                    const char* topicFilter,
                                    const char* qosLevels = nullptr,
                                    const char* noLocalFlags = nullptr,
                                    const char* retainFlags = nullptr,
                                    const char* retainHandlingFlags = nullptr) = 0;

    virtual MqttError MQTTPublish(const char* topicName,
                                  byte QoS = 0,
                                  word topicAlias = 0,
                                  const byte* payload = nullptr,
                                  size_t payloadSize = 0,
                                  const char* contentType = nullptr,
                                  bool retain = false,
                                  const char* userPropertyName = nullptr,
                                  const char* userPropertyValue = nullptr,
                                  dword messageExpiryInterval = 0,
                                  const char* responseTopic = nullptr,
                                  const byte* correlationData = nullptr,
                                  word correlationDataSize = 0) = 0;

    virtual MqttError MQTTUnsubscribe(const char* topicFilter,
                                      const char* userPropertyName = nullptr,
                                      const char* userPropertyValue = nullptr) = 0;

    virtual MqttError MQTTPing() = 0;

    virtual MqttError MQTTDisconnect(MQTTClientDisconnectReason reason = NormalDisconnection,
                                     dword sessionExpiryInterval = 0,
                                     const char* reasonString = nullptr,
                                     const char* userPropertyname = nullptr,
                                     const char* userPropertyValue = nullptr,
                                     const char* serverReference = nullptr) = 0;

    virtual MqttError MQTTSendAuthData(const char* authenticationMethod,
                                       const byte* authenticationData,
                                       word authenticationDataSize,
                                       MQTTAuthReasonCode reasonCode = MQTTAuthReasonCode::ContinueAuthentication,
                                       const char* reasonString = nullptr,
                                       const char* userPropertyName = nullptr,
                                       const char* userPropertyValue = nullptr) = 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.

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. 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 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 using the given parameters. If the broker is secured (TLS), set tls to true and connect to the corresponding port (e.g., 8883).