mqtt_sn_client.h
Go to the documentation of this file.
1 /**
2  * @file mqtt_sn_client.h
3  * @brief MQTT-SN client
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.0
29  **/
30 
31 #ifndef _MQTT_SN_CLIENT_H
32 #define _MQTT_SN_CLIENT_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "mqtt_sn/mqtt_sn_common.h"
38 
39 //MQTT-SN client support
40 #ifndef MQTT_SN_CLIENT_SUPPORT
41  #define MQTT_SN_CLIENT_SUPPORT ENABLED
42 #elif (MQTT_SN_CLIENT_SUPPORT != ENABLED && MQTT_SN_CLIENT_SUPPORT != DISABLED)
43  #error MQTT_SN_CLIENT_SUPPORT parameter is not valid
44 #endif
45 
46 //MQTT-SN over DTLS
47 #ifndef MQTT_SN_CLIENT_DTLS_SUPPORT
48  #define MQTT_SN_CLIENT_DTLS_SUPPORT DISABLED
49 #elif (MQTT_SN_CLIENT_DTLS_SUPPORT != ENABLED && MQTT_SN_CLIENT_DTLS_SUPPORT != DISABLED)
50  #error MQTT_SN_CLIENT_DTLS_SUPPORT parameter is not valid
51 #endif
52 
53 //Maximum number of topics that can be registered
54 #ifndef MQTT_SN_CLIENT_TOPIC_TABLE_SIZE
55  #define MQTT_SN_CLIENT_TOPIC_TABLE_SIZE 10
56 #elif (MQTT_SN_CLIENT_TOPIC_TABLE_SIZE < 0)
57  #error MQTT_SN_CLIENT_TOPIC_TABLE_SIZE parameter is not valid
58 #endif
59 
60 //Maximum number of QoS 2 messages that can be accepted
61 #ifndef MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE
62  #define MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE 10
63 #elif (MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE < 0)
64  #error MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE parameter is not valid
65 #endif
66 
67 //Maximum length of the client identifier
68 #ifndef MQTT_SN_CLIENT_MAX_ID_LEN
69  #define MQTT_SN_CLIENT_MAX_ID_LEN 23
70 #elif (MQTT_SN_CLIENT_MAX_ID_LEN < 0)
71  #error MQTT_SN_CLIENT_MAX_ID_LEN parameter is not valid
72 #endif
73 
74 //Maximum length of topic names
75 #ifndef MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN
76  #define MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN 32
77 #elif (MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN < 0)
78  #error MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN parameter is not valid
79 #endif
80 
81 //Maximum length of the will topic
82 #ifndef MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN
83  #define MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN 32
84 #elif (MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN < 0)
85  #error MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN parameter is not valid
86 #endif
87 
88 //Maximum length of the will message payload
89 #ifndef MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN
90  #define MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN 32
91 #elif (MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN < 0)
92  #error MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN parameter is not valid
93 #endif
94 
95 //MQTT-SN client tick interval
96 #ifndef MQTT_SN_CLIENT_TICK_INTERVAL
97  #define MQTT_SN_CLIENT_TICK_INTERVAL 100
98 #elif (MQTT_SN_CLIENT_TICK_INTERVAL < 10)
99  #error MQTT_SN_CLIENT_TICK_INTERVAL parameter is not valid
100 #endif
101 
102 //Default timeout
103 #ifndef MQTT_SN_CLIENT_DEFAULT_TIMEOUT
104  #define MQTT_SN_CLIENT_DEFAULT_TIMEOUT 30000
105 #elif (MQTT_SN_CLIENT_DEFAULT_TIMEOUT < 0)
106  #error MQTT_SN_CLIENT_DEFAULT_TIMEOUT parameter is not valid
107 #endif
108 
109 //Default keep-alive time interval
110 #ifndef MQTT_SN_CLIENT_DEFAULT_KEEP_ALIVE
111  #define MQTT_SN_CLIENT_DEFAULT_KEEP_ALIVE 0
112 #elif (MQTT_SN_CLIENT_DEFAULT_KEEP_ALIVE < 0)
113  #error MQTT_SN_CLIENT_DEFAULT_KEEP_ALIVE parameter is not valid
114 #endif
115 
116 //Number of retransmissions of keep-alive probes
117 #ifndef MQTT_SN_CLIENT_MAX_KEEP_ALIVE_PROBES
118  #define MQTT_SN_CLIENT_MAX_KEEP_ALIVE_PROBES 5
119 #elif (MQTT_SN_CLIENT_MAX_KEEP_ALIVE_PROBES < 0)
120  #error MQTT_SN_CLIENT_MAX_KEEP_ALIVE_PROBES parameter is not valid
121 #endif
122 
123 //Initial delay before the client starts searching for gateways
124 #ifndef MQTT_SN_CLIENT_SEARCH_DELAY
125  #define MQTT_SN_CLIENT_SEARCH_DELAY 0
126 #elif (MQTT_SN_CLIENT_SEARCH_DELAY < 0)
127  #error MQTT_SN_CLIENT_SEARCH_DELAY parameter is not valid
128 #endif
129 
130 //Retransmission timeout
131 #ifndef MQTT_SN_CLIENT_RETRY_TIMEOUT
132  #define MQTT_SN_CLIENT_RETRY_TIMEOUT 5000
133 #elif (MQTT_SN_CLIENT_RETRY_TIMEOUT < 1000)
134  #error MQTT_SN_CLIENT_RETRY_TIMEOUT parameter is not valid
135 #endif
136 
137 //Application specific context
138 #ifndef MQTT_SN_CLIENT_PRIVATE_CONTEXT
139  #define MQTT_SN_CLIENT_PRIVATE_CONTEXT
140 #endif
141 
142 //DTLS supported?
143 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
144  #include "core/crypto.h"
145  #include "tls.h"
146 #endif
147 
148 //Forward declaration of MqttSnClientContext structure
149 struct _MqttSnClientContext;
150 #define MqttSnClientContext struct _MqttSnClientContext
151 
152 //C++ guard
153 #ifdef __cplusplus
154 extern "C" {
155 #endif
156 
157 
158 /**
159  * @brief MQTT-SN client states
160  **/
161 
162 typedef enum
163 {
175 
176 
177 //DTLS supported?
178 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
179 
180 /**
181  * @brief DTLS initialization callback
182  **/
183 
186 
187 #endif
188 
189 
190 /**
191  * @brief PUBLISH message received callback
192  **/
193 
195  const char_t *topic, const uint8_t *message, size_t length,
196  MqttSnQosLevel qos, bool_t retain);
197 
198 
199 /**
200  * @brief Will message
201  **/
202 
203 typedef struct
204 {
205  char_t topic[MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN + 1]; ///<Will topic name
206  uint8_t payload[MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN]; ///<Will message payload
207  size_t length; ///<Length of the Will message payload
208  MqttSnFlags flags; ///<Flags
210 
211 
212 /**
213  * @brief Mapping between a topic name and a topic ID
214  **/
215 
216 typedef struct
217 {
219  uint16_t topicId; ///<Topic identifier
221 
222 
223 /**
224  * @brief QoS 2 message state
225  **/
226 
227 typedef struct
228 {
229  bool_t ownership; ///<Ownership of message accepted by the client
230  uint16_t msgId; ///<Message identifier
232 
233 
234 /**
235  * @brief MQTT-SN client context
236  **/
237 
239 {
240  MqttSnClientState state; ///<MQTT-SN client state
241  MqttSnTransportProtocol transportProtocol; ///<Transport protocol (UDP or DTLS)
242  const MqttSnPredefinedTopic *predefinedTopicTable; ///<List of predefined topics
243  uint_t predefinedTopicTableSize; ///<Number of predefined topics
244  systime_t timeout; ///<Timeout value
245  systime_t keepAlive; ///<Keep-alive interval
246  char_t clientId[MQTT_SN_CLIENT_MAX_ID_LEN + 1]; ///<Client identifier
248  NetInterface *interface; ///<Underlying network interface
249  Socket *socket; ///<Underlying TCP socket
250 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
251  TlsContext *dtlsContext; ///<DTLS context
252  TlsSessionState dtlsSession; ///<DTLS session state
253  MqttSnClientDtlsInitCallback dtlsInitCallback; ///<DTLS initialization callback
254 #endif
255  MqttSnClientPublishCallback publishCallback; ///<PUBLISH message received callback
256  IpAddr gwIpAddr; ///<Gateway IP address
257  uint16_t gwPort; ///<Gateway port number
258  systime_t startTime; ///<Start time
259  systime_t retransmitStartTime; ///<Time at which the last message was sent
260  systime_t retransmitTimeout; ///<Retransmission timeout
261  systime_t keepAliveTimestamp; ///<Timestamp used to manage keep-alive
262  uint_t keepAliveCounter; ///<PINGREQ retransmission counter
263  MqttSnMessage message; ///<MQTT-SN message
264  MqttSnMsgType msgType; ///<Message type
265  uint16_t msgId; ///<Message identifier
266  uint16_t topicId; ///<Topic identifier returned by the gateway (REGACK/SUBACK)
267  MqttSnReturnCode returnCode; ///<Status code returned by the gateway
270  MQTT_SN_CLIENT_PRIVATE_CONTEXT ///<Application specific context
271 };
272 
273 
274 //MQTT-SN client related functions
276 
278  MqttSnTransportProtocol transportProtocol);
279 
280 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
281 
284 
285 #endif
286 
288  MqttSnClientPublishCallback callback);
289 
291  MqttSnPredefinedTopic *predefinedTopics, uint_t size);
292 
294  systime_t timeout);
295 
297  systime_t keepAlive);
298 
300  const char_t *clientId);
301 
303  const char_t *topic, const void *message, size_t length,
304  MqttSnQosLevel qos, bool_t retain);
305 
307  NetInterface *interface);
308 
310  const IpAddr *gwIpAddr, uint16_t gwPort);
311 
313  const IpAddr *destIpAddr, uint16_t destPort);
314 
315 error_t mqttSnClientConnect(MqttSnClientContext *context, bool_t cleanSession);
316 
318  const char_t *topicName, const void *message, size_t length,
319  MqttSnQosLevel qos, bool_t retain, bool_t dup, uint16_t *msgId);
320 
323 
325  const char_t *topicName);
326 
328 
330  const char_t *topic, const void *message, size_t length,
331  MqttSnQosLevel qos, bool_t retain);
332 
335 
337 
340 
342 
343 //C++ guard
344 #ifdef __cplusplus
345 }
346 #endif
347 
348 #endif
uint8_t message[]
Definition: chap.h:154
unsigned int uint_t
Definition: compiler_port.h:50
char char_t
Definition: compiler_port.h:48
int bool_t
Definition: compiler_port.h:53
General definitions for cryptographic algorithms.
error_t
Error codes.
Definition: error.h:43
Ipv4Addr destIpAddr
Definition: ipcp.h:80
uint8_t payload[]
Definition: ipv6.h:277
uint8_t dup
Definition: mqtt_common.h:182
uint8_t qos
Definition: mqtt_common.h:181
error_t(* MqttSnClientDtlsInitCallback)(MqttSnClientContext *context, TlsContext *dtlsContext)
DTLS initialization callback.
#define MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN
error_t mqttSnClientGetReturnCode(MqttSnClientContext *context, MqttSnReturnCode *returnCode)
Retrieve return code.
error_t mqttSnClientRegisterPublishCallback(MqttSnClientContext *context, MqttSnClientPublishCallback callback)
Register publish callback function.
error_t mqttSnClientSetWillMessage(MqttSnClientContext *context, const char_t *topic, const void *message, size_t length, MqttSnQosLevel qos, bool_t retain)
Specify the Will message.
error_t mqttSnClientSetPredefinedTopics(MqttSnClientContext *context, MqttSnPredefinedTopic *predefinedTopics, uint_t size)
Set the list of predefined topics.
error_t mqttSnClientSetGateway(MqttSnClientContext *context, const IpAddr *gwIpAddr, uint16_t gwPort)
Specify the address of the gateway.
#define MQTT_SN_CLIENT_PRIVATE_CONTEXT
error_t mqttSnClientSetTimeout(MqttSnClientContext *context, systime_t timeout)
Set communication timeout.
error_t mqttSnClientSearchGateway(MqttSnClientContext *context, const IpAddr *destIpAddr, uint16_t destPort)
Search for a gateway.
void(* MqttSnClientPublishCallback)(MqttSnClientContext *context, const char_t *topic, const uint8_t *message, size_t length, MqttSnQosLevel qos, bool_t retain)
PUBLISH message received callback.
error_t mqttSnClientSetIdentifier(MqttSnClientContext *context, const char_t *clientId)
Set client identifier.
#define MQTT_SN_CLIENT_TOPIC_TABLE_SIZE
error_t mqttSnClientPing(MqttSnClientContext *context)
Send ping request.
#define MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE
#define MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN
error_t mqttSnClientConnect(MqttSnClientContext *context, bool_t cleanSession)
Establish connection with the MQTT-SN gateway.
error_t mqttSnClientUnsubscribe(MqttSnClientContext *context, const char_t *topicName)
Unsubscribe from topic.
error_t mqttSnClientSubscribe(MqttSnClientContext *context, const char_t *topicName, MqttSnQosLevel qos)
Subscribe to topic.
#define MQTT_SN_CLIENT_MAX_ID_LEN
error_t mqttSnClientDisconnect(MqttSnClientContext *context, systime_t duration)
Disconnect from the MQTT-SN gateway.
error_t mqttSnClientTask(MqttSnClientContext *context, systime_t timeout)
Process MQTT-SN client events.
error_t mqttSnClientInit(MqttSnClientContext *context)
Initialize MQTT-SN client context.
void mqttSnClientDeinit(MqttSnClientContext *context)
Release MQTT-SN client context.
error_t mqttSnClientBindToInterface(MqttSnClientContext *context, NetInterface *interface)
Bind the MQTT-SN client to a particular network interface.
MqttSnClientState
MQTT-SN client states.
@ MQTT_SN_CLIENT_STATE_ASLEEP
@ MQTT_SN_CLIENT_STATE_SEARCHING
@ MQTT_SN_CLIENT_STATE_LOST
@ MQTT_SN_CLIENT_STATE_ACTIVE
@ MQTT_SN_CLIENT_STATE_AWAKE
@ MQTT_SN_CLIENT_STATE_DISCONNECTED
@ MQTT_SN_CLIENT_STATE_RESP_RECEIVED
@ MQTT_SN_CLIENT_STATE_CONNECTING
@ MQTT_SN_CLIENT_STATE_DISCONNECTING
@ MQTT_SN_CLIENT_STATE_SENDING_REQ
#define MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN
#define MqttSnClientContext
error_t mqttSnClientSetKeepAlive(MqttSnClientContext *context, systime_t keepAlive)
Set keep-alive value.
error_t mqttSnClientSetTransportProtocol(MqttSnClientContext *context, MqttSnTransportProtocol transportProtocol)
Set the transport protocol to be used.
error_t mqttSnClientUpdateWillMessage(MqttSnClientContext *context, const char_t *topic, const void *message, size_t length, MqttSnQosLevel qos, bool_t retain)
Update the Will message.
error_t mqttSnClientRegisterDtlsInitCallback(MqttSnClientContext *context, MqttSnClientDtlsInitCallback callback)
Register DTLS initialization callback function.
error_t mqttSnClientPublish(MqttSnClientContext *context, const char_t *topicName, const void *message, size_t length, MqttSnQosLevel qos, bool_t retain, bool_t dup, uint16_t *msgId)
Publish message.
Definitions common to MQTT-SN client and gateway.
MqttSnMsgType
MQTT-SN message types.
MqttSnFlags
MqttSnTransportProtocol
MQTT-SN transport protocols.
uint16_t msgId
MqttSnQosLevel
Quality of service level.
uint16_t duration
char_t topicName[]
uint8_t returnCode
MqttSnReturnCode
MQTT-SN return codes.
char_t clientId[]
MQTT-SN message formatting and parsing.
TCP/IP stack core.
#define NetInterface
Definition: net.h:36
uint32_t systime_t
System time.
#define Socket
Definition: socket.h:36
MQTT-SN client context.
uint16_t gwPort
Gateway port number.
char_t clientId[MQTT_SN_CLIENT_MAX_ID_LEN+1]
Client identifier.
systime_t keepAlive
Keep-alive interval.
uint16_t msgId
Message identifier.
MqttSnClientTopicEntry topicTable[MQTT_SN_CLIENT_TOPIC_TABLE_SIZE]
systime_t retransmitTimeout
Retransmission timeout.
MqttSnClientPublishCallback publishCallback
PUBLISH message received callback.
MqttSnTransportProtocol transportProtocol
Transport protocol (UDP or DTLS)
MqttSnClientWillMessage willMessage
Will message.
MqttSnClientState state
MQTT-SN client state.
TlsSessionState dtlsSession
DTLS session state.
IpAddr gwIpAddr
Gateway IP address.
MqttSnReturnCode returnCode
Status code returned by the gateway.
const MqttSnPredefinedTopic * predefinedTopicTable
List of predefined topics.
uint16_t topicId
Topic identifier returned by the gateway (REGACK/SUBACK)
TlsContext * dtlsContext
DTLS context.
systime_t keepAliveTimestamp
Timestamp used to manage keep-alive.
uint_t keepAliveCounter
PINGREQ retransmission counter.
MqttSnMsgType msgType
Message type.
systime_t timeout
Timeout value.
MqttSnClientDtlsInitCallback dtlsInitCallback
DTLS initialization callback.
systime_t retransmitStartTime
Time at which the last message was sent.
Socket * socket
Underlying TCP socket.
MqttSnMessage message
MQTT-SN message.
systime_t startTime
Start time.
uint_t predefinedTopicTableSize
Number of predefined topics.
NetInterface * interface
Underlying network interface.
MqttSnClientMsgIdEntry msgIdTable[MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE]
IP network address.
Definition: ip.h:79
QoS 2 message state.
uint16_t msgId
Message identifier.
bool_t ownership
Ownership of message accepted by the client.
Mapping between a topic name and a topic ID.
uint16_t topicId
Topic identifier.
MqttSnFlags flags
Flags.
size_t length
Length of the Will message payload.
MQTT-SN message.
Predefined topic.
TLS session state.
Definition: tls.h:2021
uint8_t length
Definition: tcp.h:368
uint16_t destPort
Definition: tcp.h:340
TLS (Transport Layer Security)
#define TlsContext
Definition: tls.h:36