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-2019 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 1.9.6
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 //DTLS supported?
138 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
139  #include "core/crypto.h"
140  #include "tls.h"
141 #endif
142 
143 //Forward declaration of MqttSnClientContext structure
144 struct _MqttSnClientContext;
145 #define MqttSnClientContext struct _MqttSnClientContext
146 
147 //C++ guard
148 #ifdef __cplusplus
149 extern "C" {
150 #endif
151 
152 
153 /**
154  * @brief MQTT-SN client states
155  **/
156 
157 typedef enum
158 {
170 
171 
172 //DTLS supported?
173 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
174 
175 /**
176  * @brief DTLS initialization callback
177  **/
178 
181 
182 #endif
183 
184 
185 /**
186  * @brief PUBLISH message received callback
187  **/
188 
190  const char_t *topic, const uint8_t *message, size_t length,
192 
193 
194 /**
195  * @brief Will message
196  **/
197 
198 typedef struct
199 {
200  char_t topic[MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN + 1]; ///<Will topic name
201  uint8_t payload[MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN]; ///<Will message payload
202  size_t length; ///<Length of the Will message payload
203  MqttSnFlags flags; ///<Flags
205 
206 
207 /**
208  * @brief Mapping between a topic name and a topic ID
209  **/
210 
211 typedef struct
212 {
214  uint16_t topicId; ///<Topic identifier
216 
217 
218 /**
219  * @brief QoS 2 message state
220  **/
221 
222 typedef struct
223 {
224  bool_t ownership; ///<Ownership of message accepted by the client
225  uint16_t msgId; ///<Message identifier
227 
228 
229 /**
230  * @brief MQTT-SN client context
231  **/
232 
234 {
235  MqttSnClientState state; ///<MQTT-SN client state
236  MqttSnTransportProtocol transportProtocol; ///<Transport protocol (UDP or DTLS)
237  const MqttSnPredefinedTopic *predefinedTopicTable; ///<List of predefined topics
238  uint_t predefinedTopicTableSize; ///<Number of predefined topics
239  systime_t timeout; ///<Timeout value
240  systime_t keepAlive; ///<Keep-alive interval
241  char_t clientId[MQTT_SN_CLIENT_MAX_ID_LEN + 1]; ///<Client identifier
243  NetInterface *interface; ///<Underlying network interface
244  Socket *socket; ///<Underlying TCP socket
245 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
246  TlsContext *dtlsContext; ///<DTLS context
247  TlsSessionState dtlsSession; ///<DTLS session state
248  MqttSnClientDtlsInitCallback dtlsInitCallback; ///<DTLS initialization callback
249 #endif
250  MqttSnClientPublishCallback publishCallback; ///<PUBLISH message received callback
251  IpAddr gwIpAddr; ///<Gateway IP address
252  uint16_t gwPort; ///<Gateway port number
253  systime_t startTime; ///<Start time
254  systime_t retransmitStartTime; ///<Time at which the last message was sent
255  systime_t retransmitTimeout; ///<Retransmission timeout
256  systime_t keepAliveTimestamp; ///<Timestamp used to manage keep-alive
257  uint_t keepAliveCounter; ///<PINGREQ retransmission counter
258  MqttSnMessage message; ///<MQTT-SN message
259  MqttSnMsgType msgType; ///<Message type
260  uint16_t msgId; ///<Message identifier
261  uint16_t topicId; ///<Topic identifier returned by the gateway (REGACK/SUBACK)
262  MqttSnReturnCode returnCode; ///<Status code returned by the gateway
265 };
266 
267 
268 //MQTT-SN client related functions
270 
272  MqttSnTransportProtocol transportProtocol);
273 
274 #if (MQTT_SN_CLIENT_DTLS_SUPPORT == ENABLED)
275 
278 
279 #endif
280 
282  MqttSnClientPublishCallback callback);
283 
285  MqttSnPredefinedTopic *predefinedTopics, uint_t size);
286 
288  systime_t timeout);
289 
291  systime_t keepAlive);
292 
294  const char_t *clientId);
295 
297  const char_t *topic, const void *message, size_t length,
299 
301  NetInterface *interface);
302 
304  const IpAddr *gwIpAddr, uint16_t gwPort);
305 
307  const IpAddr *destIpAddr, uint16_t destPort);
308 
310 
312  const char_t *topicName, const void *message, size_t length,
314 
317 
319  const char_t *topicName);
320 
322 
324  const char_t *topic, const void *message, size_t length,
326 
329 
331 
334 
335 //C++ guard
336 #ifdef __cplusplus
337 }
338 #endif
339 
340 #endif
bool_t ownership
Ownership of message accepted by the client.
error_t mqttSnClientTask(MqttSnClientContext *context, systime_t timeout)
Process MQTT-SN client events.
error_t mqttSnClientSetPredefinedTopics(MqttSnClientContext *context, MqttSnPredefinedTopic *predefinedTopics, uint_t size)
Set the list of predefined topics.
MqttSnReturnCode returnCode
Status code returned by the gateway.
uint_t keepAliveCounter
PINGREQ retransmission counter.
uint8_t length
Definition: dtls_misc.h:149
error_t mqttSnClientDisconnect(MqttSnClientContext *context)
Disconnect from the MQTT-SN gateway.
int bool_t
Definition: compiler_port.h:49
@ MQTT_SN_CLIENT_STATE_ASLEEP
Predefined topic.
IP network address.
Definition: ip.h:71
uint16_t topicId
Topic identifier returned by the gateway (REGACK/SUBACK)
size_t length
Length of the Will message payload.
error_t(* MqttSnClientDtlsInitCallback)(MqttSnClientContext *context, TlsContext *dtlsContext)
DTLS initialization callback.
#define MqttSnClientContext
MqttSnReturnCode
MQTT-SN return codes.
MqttSnQosLevel
Quality of service level.
#define MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE
MqttSnFlags flags
Flags.
uint16_t msgId
uint16_t destPort
Definition: tcp.h:303
uint8_t qos
Definition: mqtt_common.h:179
uint16_t gwPort
Gateway port number.
void mqttSnClientDeinit(MqttSnClientContext *context)
Release MQTT-SN client context.
uint8_t returnCode
#define MQTT_SN_CLIENT_MAX_WILL_PAYLOAD_LEN
error_t mqttSnClientBindToInterface(MqttSnClientContext *context, NetInterface *interface)
Bind the MQTT-SN client to a particular network interface.
@ MQTT_SN_CLIENT_STATE_SENDING_REQ
#define MQTT_SN_CLIENT_MAX_ID_LEN
__start_packed struct @232 MqttSnFlags
MQTT-SN flags.
@ MQTT_SN_CLIENT_STATE_SEARCHING
error_t mqttSnClientPing(MqttSnClientContext *context)
Send ping request.
MqttSnClientState
MQTT-SN client states.
error_t mqttSnClientSetKeepAlive(MqttSnClientContext *context, systime_t keepAlive)
Set keep-alive value.
TlsContext * dtlsContext
DTLS context.
Mapping between a topic name and a topic ID.
MqttSnMessage message
MQTT-SN message.
error_t mqttSnClientRegisterDtlsInitCallback(MqttSnClientContext *context, MqttSnClientDtlsInitCallback callback)
Register DTLS initialization callback function.
QoS 2 message state.
const MqttSnPredefinedTopic * predefinedTopicTable
List of predefined topics.
systime_t startTime
Start time.
#define MQTT_SN_CLIENT_TOPIC_TABLE_SIZE
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
error_t mqttSnClientInit(MqttSnClientContext *context)
Initialize MQTT-SN client context.
error_t mqttSnClientRegisterPublishCallback(MqttSnClientContext *context, MqttSnClientPublishCallback callback)
Register publish callback function.
@ MQTT_SN_CLIENT_STATE_LOST
systime_t keepAliveTimestamp
Timestamp used to manage keep-alive.
MqttSnClientDtlsInitCallback dtlsInitCallback
DTLS initialization callback.
error_t mqttSnClientGetReturnCode(MqttSnClientContext *context, MqttSnReturnCode *returnCode)
Retrieve return code.
error_t mqttSnClientUpdateWillMessage(MqttSnClientContext *context, const char_t *topic, const void *message, size_t length, MqttSnQosLevel qos, bool_t retain)
Update the Will message.
uint8_t retain
Definition: mqtt_common.h:178
char_t clientId[MQTT_SN_CLIENT_MAX_ID_LEN+1]
Client identifier.
error_t mqttSnClientSetTransportProtocol(MqttSnClientContext *context, MqttSnTransportProtocol transportProtocol)
Set the transport protocol to be used.
error_t mqttSnClientSubscribe(MqttSnClientContext *context, const char_t *topicName, MqttSnQosLevel qos)
Subscribe to topic.
#define NetInterface
Definition: net.h:36
IpAddr gwIpAddr
Gateway IP address.
MQTT-SN client context.
systime_t keepAlive
Keep-alive interval.
General definitions for cryptographic algorithms.
char_t topicName[]
@ MQTT_SN_CLIENT_STATE_AWAKE
@ MQTT_SN_CLIENT_STATE_DISCONNECTED
MqttSnClientState state
MQTT-SN client state.
error_t mqttSnClientSetTimeout(MqttSnClientContext *context, systime_t timeout)
Set communication timeout.
@ MQTT_SN_CLIENT_STATE_RESP_RECEIVED
MqttSnTransportProtocol transportProtocol
Transport protocol (UDP or DTLS)
@ MQTT_SN_CLIENT_STATE_DISCONNECTING
uint_t predefinedTopicTableSize
Number of predefined topics.
systime_t timeout
Timeout value.
MqttSnClientPublishCallback publishCallback
PUBLISH message received callback.
Definitions common to MQTT-SN client and gateway.
error_t mqttSnClientUnsubscribe(MqttSnClientContext *context, const char_t *topicName)
Unsubscribe from topic.
MqttSnClientTopicEntry topicTable[MQTT_SN_CLIENT_TOPIC_TABLE_SIZE]
char char_t
Definition: compiler_port.h:43
MqttSnMsgType msgType
Message type.
Socket * socket
Underlying TCP socket.
MqttSnMsgType
MQTT-SN message types.
error_t mqttSnClientSetIdentifier(MqttSnClientContext *context, const char_t *clientId)
Set client identifier.
TlsSessionState dtlsSession
DTLS session state.
systime_t retransmitStartTime
Time at which the last message was sent.
TLS session state.
Definition: tls.h:1834
uint16_t topicId
Topic identifier.
error_t mqttSnClientConnect(MqttSnClientContext *context, bool_t cleanSession)
Establish connection with the MQTT-SN gateway.
MQTT-SN message.
#define MQTT_SN_CLIENT_MAX_WILL_TOPIC_LEN
uint8_t cleanSession
#define Socket
Definition: socket.h:36
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.
uint8_t message[]
Definition: chap.h:152
uint16_t msgId
Message identifier.
TLS (Transport Layer Security)
uint8_t dup
Definition: mqtt_common.h:180
@ MQTT_SN_CLIENT_STATE_ACTIVE
error_t mqttSnClientSearchGateway(MqttSnClientContext *context, const IpAddr *destIpAddr, uint16_t destPort)
Search for a gateway.
@ MQTT_SN_CLIENT_STATE_CONNECTING
error_t mqttSnClientSetGateway(MqttSnClientContext *context, const IpAddr *gwIpAddr, uint16_t gwPort)
Specify the address of the gateway.
NetInterface * interface
Underlying network interface.
#define MQTT_SN_CLIENT_MAX_TOPIC_NAME_LEN
MqttSnTransportProtocol
MQTT-SN transport protocols.
systime_t retransmitTimeout
Retransmission timeout.
MQTT-SN message formatting and parsing.
MqttSnClientMsgIdEntry msgIdTable[MQTT_SN_CLIENT_MSG_ID_TABLE_SIZE]
char_t clientId[]
unsigned int uint_t
Definition: compiler_port.h:45
TCP/IP stack core.
error_t mqttSnClientSetWillMessage(MqttSnClientContext *context, const char_t *topic, const void *message, size_t length, MqttSnQosLevel qos, bool_t retain)
Specify the Will message.
uint32_t systime_t
Definition: compiler_port.h:46
MqttSnClientWillMessage willMessage
Will message.
void(* MqttSnClientPublishCallback)(MqttSnClientContext *context, const char_t *topic, const uint8_t *message, size_t length, MqttSnQosLevel qos, bool_t retain)
PUBLISH message received callback.
uint16_t msgId
Message identifier.
Ipv4Addr destIpAddr
Definition: ipcp.h:78