mqtt_client.h File Reference

MQTT client. More...

#include "core/net.h"
#include "mqtt/mqtt_common.h"
#include "core/crypto.h"
#include "tls.h"
#include "web_socket/web_socket.h"

Go to the source code of this file.

Data Structures

struct  MqttClientWillMessage
 Will message. More...
 
struct  MqttClientCallbacks
 MQTT client callback functions. More...
 
struct  MqttClientSettings
 MQTT client settings. More...
 
struct  _MqttClientContext
 MQTT client context. More...
 

Macros

#define MQTT_CLIENT_SUPPORT   ENABLED
 
#define MQTT_CLIENT_TLS_SUPPORT   DISABLED
 
#define MQTT_CLIENT_WS_SUPPORT   DISABLED
 
#define MQTT_CLIENT_DEFAULT_KEEP_ALIVE   0
 
#define MQTT_CLIENT_DEFAULT_TIMEOUT   20000
 
#define MQTT_CLIENT_MAX_HOST_LEN   32
 
#define MQTT_CLIENT_MAX_URI_LEN   16
 
#define MQTT_CLIENT_MAX_ID_LEN   23
 
#define MQTT_CLIENT_MAX_USERNAME_LEN   16
 
#define MQTT_CLIENT_MAX_PASSWORD_LEN   16
 
#define MQTT_CLIENT_MAX_WILL_TOPIC_LEN   16
 
#define MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN   16
 
#define MQTT_CLIENT_BUFFER_SIZE   1024
 
#define MQTT_CLIENT_PRIVATE_CONTEXT
 
#define MqttClientContext   struct _MqttClientContext
 

Typedefs

typedef void(* MqttClientConnAckCallback) (MqttClientContext *context, uint8_t connectAckFlags, uint8_t connectReturnCode)
 CONNACK message received callback. More...
 
typedef void(* MqttClientPublishCallback) (MqttClientContext *context, const char_t *topic, const uint8_t *message, size_t length, bool_t dup, MqttQosLevel qos, bool_t retain, uint16_t packetId)
 PUBLISH message received callback. More...
 
typedef void(* MqttClientPubAckCallback) (MqttClientContext *context, uint16_t packetId)
 PUBACK message received callback. More...
 
typedef void(* MqttClientPubRecCallback) (MqttClientContext *context, uint16_t packetId)
 PUBREC message received callback. More...
 
typedef void(* MqttClientPubRelCallback) (MqttClientContext *context, uint16_t packetId)
 PUBREL message received callback. More...
 
typedef void(* MqttClientPubCompCallback) (MqttClientContext *context, uint16_t packetId)
 PUBCOMP message received callback. More...
 
typedef void(* MqttClientSubAckCallback) (MqttClientContext *context, uint16_t packetId)
 SUBACK message received callback. More...
 
typedef void(* MqttClientUnsubAckCallback) (MqttClientContext *context, uint16_t packetId)
 UNSUBACK message received callback. More...
 
typedef void(* MqttClientPingRespCallback) (MqttClientContext *context)
 PINGRESP message received callback. More...
 
typedef error_t(* MqttClientTlsInitCallback) (MqttClientContext *context, TlsContext *tlsContext)
 TLS initialization callback. More...
 

Enumerations

enum  MqttClientState {
  MQTT_CLIENT_STATE_DISCONNECTED = 0 , MQTT_CLIENT_STATE_CONNECTING = 1 , MQTT_CLIENT_STATE_CONNECTED = 2 , MQTT_CLIENT_STATE_IDLE = 3 ,
  MQTT_CLIENT_STATE_SENDING_PACKET = 4 , MQTT_CLIENT_STATE_PACKET_SENT = 5 , MQTT_CLIENT_STATE_WAITING_PACKET = 6 , MQTT_CLIENT_STATE_RECEIVING_PACKET = 7 ,
  MQTT_CLIENT_STATE_PACKET_RECEIVED = 8 , MQTT_CLIENT_STATE_DISCONNECTING = 9
}
 MQTT client states. More...
 

Functions

error_t mqttClientInit (MqttClientContext *context)
 Initialize MQTT client context. More...
 
void mqttClientInitCallbacks (MqttClientCallbacks *callbacks)
 Initialize callback structure. More...
 
error_t mqttClientRegisterCallbacks (MqttClientContext *context, const MqttClientCallbacks *callbacks)
 Register MQTT client callbacks. More...
 
error_t mqttClientSetVersion (MqttClientContext *context, MqttVersion version)
 Set the MQTT protocol version to be used. More...
 
error_t mqttClientSetTransportProtocol (MqttClientContext *context, MqttTransportProtocol transportProtocol)
 Set the transport protocol to be used. More...
 
error_t mqttClientRegisterTlsInitCallback (MqttClientContext *context, MqttClientTlsInitCallback callback)
 Register TLS initialization callback function. More...
 
error_t mqttClientRegisterPublishCallback (MqttClientContext *context, MqttClientPublishCallback callback)
 Register publish callback function. More...
 
error_t mqttClientSetTimeout (MqttClientContext *context, systime_t timeout)
 Set communication timeout. More...
 
error_t mqttClientSetKeepAlive (MqttClientContext *context, uint16_t keepAlive)
 Set keep-alive value. More...
 
error_t mqttClientSetHost (MqttClientContext *context, const char_t *host)
 Set the domain name of the server (for virtual hosting) More...
 
error_t mqttClientSetUri (MqttClientContext *context, const char_t *uri)
 Set the name of the resource being requested. More...
 
error_t mqttClientSetIdentifier (MqttClientContext *context, const char_t *clientId)
 Set client identifier. More...
 
error_t mqttClientSetAuthInfo (MqttClientContext *context, const char_t *username, const char_t *password)
 Set authentication information. More...
 
error_t mqttClientSetWillMessage (MqttClientContext *context, const char_t *topic, const void *message, size_t length, MqttQosLevel qos, bool_t retain)
 Specify the Will message. More...
 
error_t mqttClientBindToInterface (MqttClientContext *context, NetInterface *interface)
 Bind the MQTT client to a particular network interface. More...
 
error_t mqttClientConnect (MqttClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort, bool_t cleanSession)
 Establish connection with the MQTT server. More...
 
error_t mqttClientPublish (MqttClientContext *context, const char_t *topic, const void *message, size_t length, MqttQosLevel qos, bool_t retain, uint16_t *packetId)
 Publish message. More...
 
error_t mqttClientSubscribe (MqttClientContext *context, const char_t *topic, MqttQosLevel qos, uint16_t *packetId)
 Subscribe to topic. More...
 
error_t mqttClientUnsubscribe (MqttClientContext *context, const char_t *topic, uint16_t *packetId)
 Unsubscribe from topic. More...
 
error_t mqttClientPing (MqttClientContext *context, systime_t *rtt)
 Send ping request. More...
 
error_t mqttClientTask (MqttClientContext *context, systime_t timeout)
 Process MQTT client events. More...
 
error_t mqttClientDisconnect (MqttClientContext *context)
 Gracefully disconnect from the MQTT server. More...
 
error_t mqttClientClose (MqttClientContext *context)
 Close the connection with the MQTT server. More...
 
void mqttClientDeinit (MqttClientContext *context)
 Release MQTT client context. More...
 
error_t mqttClientProcessEvents (MqttClientContext *context, systime_t timeout)
 Process MQTT client events. More...
 

Detailed Description

MQTT client.

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.0

Definition in file mqtt_client.h.

Macro Definition Documentation

◆ MQTT_CLIENT_BUFFER_SIZE

#define MQTT_CLIENT_BUFFER_SIZE   1024

Definition at line 124 of file mqtt_client.h.

◆ MQTT_CLIENT_DEFAULT_KEEP_ALIVE

#define MQTT_CLIENT_DEFAULT_KEEP_ALIVE   0

Definition at line 61 of file mqtt_client.h.

◆ MQTT_CLIENT_DEFAULT_TIMEOUT

#define MQTT_CLIENT_DEFAULT_TIMEOUT   20000

Definition at line 68 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_HOST_LEN

#define MQTT_CLIENT_MAX_HOST_LEN   32

Definition at line 75 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_ID_LEN

#define MQTT_CLIENT_MAX_ID_LEN   23

Definition at line 89 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_PASSWORD_LEN

#define MQTT_CLIENT_MAX_PASSWORD_LEN   16

Definition at line 103 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_URI_LEN

#define MQTT_CLIENT_MAX_URI_LEN   16

Definition at line 82 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_USERNAME_LEN

#define MQTT_CLIENT_MAX_USERNAME_LEN   16

Definition at line 96 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN

#define MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN   16

Definition at line 117 of file mqtt_client.h.

◆ MQTT_CLIENT_MAX_WILL_TOPIC_LEN

#define MQTT_CLIENT_MAX_WILL_TOPIC_LEN   16

Definition at line 110 of file mqtt_client.h.

◆ MQTT_CLIENT_PRIVATE_CONTEXT

#define MQTT_CLIENT_PRIVATE_CONTEXT

Definition at line 131 of file mqtt_client.h.

◆ MQTT_CLIENT_SUPPORT

#define MQTT_CLIENT_SUPPORT   ENABLED

Definition at line 40 of file mqtt_client.h.

◆ MQTT_CLIENT_TLS_SUPPORT

#define MQTT_CLIENT_TLS_SUPPORT   DISABLED

Definition at line 47 of file mqtt_client.h.

◆ MQTT_CLIENT_WS_SUPPORT

#define MQTT_CLIENT_WS_SUPPORT   DISABLED

Definition at line 54 of file mqtt_client.h.

◆ MqttClientContext

#define MqttClientContext   struct _MqttClientContext

Definition at line 147 of file mqtt_client.h.

Typedef Documentation

◆ MqttClientConnAckCallback

typedef void(* MqttClientConnAckCallback) (MqttClientContext *context, uint8_t connectAckFlags, uint8_t connectReturnCode)

CONNACK message received callback.

Definition at line 178 of file mqtt_client.h.

◆ MqttClientPingRespCallback

typedef void(* MqttClientPingRespCallback) (MqttClientContext *context)

PINGRESP message received callback.

Definition at line 243 of file mqtt_client.h.

◆ MqttClientPubAckCallback

typedef void(* MqttClientPubAckCallback) (MqttClientContext *context, uint16_t packetId)

PUBACK message received callback.

Definition at line 195 of file mqtt_client.h.

◆ MqttClientPubCompCallback

typedef void(* MqttClientPubCompCallback) (MqttClientContext *context, uint16_t packetId)

PUBCOMP message received callback.

Definition at line 219 of file mqtt_client.h.

◆ MqttClientPublishCallback

typedef void(* MqttClientPublishCallback) (MqttClientContext *context, const char_t *topic, const uint8_t *message, size_t length, bool_t dup, MqttQosLevel qos, bool_t retain, uint16_t packetId)

PUBLISH message received callback.

Definition at line 186 of file mqtt_client.h.

◆ MqttClientPubRecCallback

typedef void(* MqttClientPubRecCallback) (MqttClientContext *context, uint16_t packetId)

PUBREC message received callback.

Definition at line 203 of file mqtt_client.h.

◆ MqttClientPubRelCallback

typedef void(* MqttClientPubRelCallback) (MqttClientContext *context, uint16_t packetId)

PUBREL message received callback.

Definition at line 211 of file mqtt_client.h.

◆ MqttClientSubAckCallback

typedef void(* MqttClientSubAckCallback) (MqttClientContext *context, uint16_t packetId)

SUBACK message received callback.

Definition at line 227 of file mqtt_client.h.

◆ MqttClientTlsInitCallback

typedef error_t(* MqttClientTlsInitCallback) (MqttClientContext *context, TlsContext *tlsContext)

TLS initialization callback.

Definition at line 253 of file mqtt_client.h.

◆ MqttClientUnsubAckCallback

typedef void(* MqttClientUnsubAckCallback) (MqttClientContext *context, uint16_t packetId)

UNSUBACK message received callback.

Definition at line 235 of file mqtt_client.h.

Enumeration Type Documentation

◆ MqttClientState

MQTT client states.

Enumerator
MQTT_CLIENT_STATE_DISCONNECTED 
MQTT_CLIENT_STATE_CONNECTING 
MQTT_CLIENT_STATE_CONNECTED 
MQTT_CLIENT_STATE_IDLE 
MQTT_CLIENT_STATE_SENDING_PACKET 
MQTT_CLIENT_STATE_PACKET_SENT 
MQTT_CLIENT_STATE_WAITING_PACKET 
MQTT_CLIENT_STATE_RECEIVING_PACKET 
MQTT_CLIENT_STATE_PACKET_RECEIVED 
MQTT_CLIENT_STATE_DISCONNECTING 

Definition at line 159 of file mqtt_client.h.

Function Documentation

◆ mqttClientBindToInterface()

error_t mqttClientBindToInterface ( MqttClientContext context,
NetInterface interface 
)

Bind the MQTT client to a particular network interface.

Parameters
[in]contextPointer to the MQTT client context
[in]interfaceNetwork interface to be used
Returns
Error code

Definition at line 445 of file mqtt_client.c.

◆ mqttClientClose()

error_t mqttClientClose ( MqttClientContext context)

Close the connection with the MQTT server.

Parameters
[in]contextPointer to the MQTT client context
Returns
Error code

Definition at line 1208 of file mqtt_client.c.

◆ mqttClientConnect()

error_t mqttClientConnect ( MqttClientContext context,
const IpAddr serverIpAddr,
uint16_t  serverPort,
bool_t  cleanSession 
)

Establish connection with the MQTT server.

Parameters
[in]contextPointer to the MQTT client context
[in]serverIpAddrIP address of the MQTT server to connect to
[in]serverPortTCP port number that will be used to establish the connection
[in]cleanSessionIf this flag is set, then the client and server must discard any previous session and start a new one
Returns
Error code

Definition at line 471 of file mqtt_client.c.

◆ mqttClientDeinit()

void mqttClientDeinit ( MqttClientContext context)

Release MQTT client context.

Parameters
[in]contextPointer to the MQTT client context

Definition at line 1229 of file mqtt_client.c.

◆ mqttClientDisconnect()

error_t mqttClientDisconnect ( MqttClientContext context)

Gracefully disconnect from the MQTT server.

Parameters
[in]contextPointer to the MQTT client context
Returns
Error code

Definition at line 1105 of file mqtt_client.c.

◆ mqttClientInit()

error_t mqttClientInit ( MqttClientContext context)

Initialize MQTT client context.

Parameters
[in]contextPointer to the MQTT client context
Returns
Error code

Definition at line 52 of file mqtt_client.c.

◆ mqttClientInitCallbacks()

void mqttClientInitCallbacks ( MqttClientCallbacks callbacks)

Initialize callback structure.

Parameters
[in]callbacksPointer to a structure that contains callback functions

Definition at line 102 of file mqtt_client.c.

◆ mqttClientPing()

error_t mqttClientPing ( MqttClientContext context,
systime_t rtt 
)

Send ping request.

Parameters
[in]contextPointer to the MQTT client context
[out]rttRound-trip time (optional parameter)
Returns
Error code

Definition at line 962 of file mqtt_client.c.

◆ mqttClientProcessEvents()

error_t mqttClientProcessEvents ( MqttClientContext context,
systime_t  timeout 
)

Process MQTT client events.

Parameters
[in]contextPointer to the MQTT client context
[in]timeoutMaximum time to wait before returning
Returns
Error code

Definition at line 67 of file mqtt_client_misc.c.

◆ mqttClientPublish()

error_t mqttClientPublish ( MqttClientContext context,
const char_t topic,
const void *  message,
size_t  length,
MqttQosLevel  qos,
bool_t  retain,
uint16_t *  packetId 
)

Publish message.

Parameters
[in]contextPointer to the MQTT client context
[in]topicTopic name
[in]messageMessage payload
[in]lengthLength of the message payload
[in]qosQoS level to be used when publishing the message
[in]retainThis flag specifies if the message is to be retained
[out]packetIdPacket identifier used to send the PUBLISH packet
Returns
Error code

Definition at line 609 of file mqtt_client.c.

◆ mqttClientRegisterCallbacks()

error_t mqttClientRegisterCallbacks ( MqttClientContext context,
const MqttClientCallbacks callbacks 
)

Register MQTT client callbacks.

Parameters
[in]contextPointer to the MQTT client context
[in]callbacksPointer to a structure that contains callback functions
Returns
Error code

Definition at line 116 of file mqtt_client.c.

◆ mqttClientRegisterPublishCallback()

error_t mqttClientRegisterPublishCallback ( MqttClientContext context,
MqttClientPublishCallback  callback 
)

Register publish callback function.

Parameters
[in]contextPointer to the MQTT client context
[in]callbackCallback function to be called when a PUBLISH message is received
Returns
Error code

Definition at line 209 of file mqtt_client.c.

◆ mqttClientRegisterTlsInitCallback()

error_t mqttClientRegisterTlsInitCallback ( MqttClientContext context,
MqttClientTlsInitCallback  callback 
)

Register TLS initialization callback function.

Parameters
[in]contextPointer to the MQTT- client context
[in]callbackTLS initialization callback function
Returns
Error code

Definition at line 184 of file mqtt_client.c.

◆ mqttClientSetAuthInfo()

error_t mqttClientSetAuthInfo ( MqttClientContext context,
const char_t username,
const char_t password 
)

Set authentication information.

Parameters
[in]contextPointer to the MQTT client context
[in]usernameNULL-terminated string containing the user name to be used
[in]passwordNULL-terminated string containing the password to be used
Returns
Error code

Definition at line 356 of file mqtt_client.c.

◆ mqttClientSetHost()

error_t mqttClientSetHost ( MqttClientContext context,
const char_t host 
)

Set the domain name of the server (for virtual hosting)

Parameters
[in]contextPointer to the MQTT client context
[in]hostNULL-terminated string containing the hostname
Returns
Error code

Definition at line 275 of file mqtt_client.c.

◆ mqttClientSetIdentifier()

error_t mqttClientSetIdentifier ( MqttClientContext context,
const char_t clientId 
)

Set client identifier.

Parameters
[in]contextPointer to the MQTT client context
[in]clientIdNULL-terminated string containing the client identifier
Returns
Error code

Definition at line 329 of file mqtt_client.c.

◆ mqttClientSetKeepAlive()

error_t mqttClientSetKeepAlive ( MqttClientContext context,
uint16_t  keepAlive 
)

Set keep-alive value.

Parameters
[in]contextPointer to the MQTT client context
[in]keepAliveMaximum time interval that is permitted to elapse between the point at which the client finishes transmitting one control packet and the point it starts sending the next
Returns
Error code

Definition at line 254 of file mqtt_client.c.

◆ mqttClientSetTimeout()

error_t mqttClientSetTimeout ( MqttClientContext context,
systime_t  timeout 
)

Set communication timeout.

Parameters
[in]contextPointer to the MQTT client context
[in]timeoutTimeout value, in seconds
Returns
Error code

Definition at line 231 of file mqtt_client.c.

◆ mqttClientSetTransportProtocol()

error_t mqttClientSetTransportProtocol ( MqttClientContext context,
MqttTransportProtocol  transportProtocol 
)

Set the transport protocol to be used.

Parameters
[in]contextPointer to the MQTT client context
[in]transportProtocolTransport protocol to be used (TCP, TLS, WebSocket, or secure WebSocket)
Returns
Error code

Definition at line 160 of file mqtt_client.c.

◆ mqttClientSetUri()

error_t mqttClientSetUri ( MqttClientContext context,
const char_t uri 
)

Set the name of the resource being requested.

Parameters
[in]contextPointer to the MQTT client context
[in]uriNULL-terminated string that contains the resource name
Returns
Error code

Definition at line 302 of file mqtt_client.c.

◆ mqttClientSetVersion()

error_t mqttClientSetVersion ( MqttClientContext context,
MqttVersion  version 
)

Set the MQTT protocol version to be used.

Parameters
[in]contextPointer to the MQTT client context
[in]versionMQTT protocol version (3.1 or 3.1.1)
Returns
Error code

Definition at line 138 of file mqtt_client.c.

◆ mqttClientSetWillMessage()

error_t mqttClientSetWillMessage ( MqttClientContext context,
const char_t topic,
const void *  message,
size_t  length,
MqttQosLevel  qos,
bool_t  retain 
)

Specify the Will message.

Parameters
[in]contextPointer to the MQTT client context
[in]topicWill topic name
[in]messageWill message
[in]lengthLength of the Will message
[in]qosQoS level to be used when publishing the Will message
[in]retainThis flag specifies if the Will message is to be retained
Returns
Error code

Definition at line 392 of file mqtt_client.c.

◆ mqttClientSubscribe()

error_t mqttClientSubscribe ( MqttClientContext context,
const char_t topic,
MqttQosLevel  qos,
uint16_t *  packetId 
)

Subscribe to topic.

Parameters
[in]contextPointer to the MQTT client context
[in]topicTopic filter
[in]qosMaximum QoS level at which the server can send application messages to the client
[out]packetIdPacket identifier used to send the SUBSCRIBE packet
Returns
Error code

Definition at line 737 of file mqtt_client.c.

◆ mqttClientTask()

error_t mqttClientTask ( MqttClientContext context,
systime_t  timeout 
)

Process MQTT client events.

Parameters
[in]contextPointer to the MQTT client context
[in]timeoutMaximum time to wait before returning
Returns
Error code

Definition at line 1076 of file mqtt_client.c.

◆ mqttClientUnsubscribe()

error_t mqttClientUnsubscribe ( MqttClientContext context,
const char_t topic,
uint16_t *  packetId 
)

Unsubscribe from topic.

Parameters
[in]contextPointer to the MQTT client context
[in]topicTopic filter
[out]packetIdPacket identifier used to send the UNSUBSCRIBE packet
Returns
Error code

Definition at line 850 of file mqtt_client.c.