Real Time Logic LLC / SharkSSL-Lite

This package includes the SharkSSL lite library and header files.

Dependents:   WebSocket-Client-Example SharkMQ-LED-Demo

SharkSSL-Lite

Description: SharkSSL is an SSL v3.0 TLS v1.0/1.1/1.2 implementation of the TLS and SSL protocol standard. With its array of compile-time options and Raycrypto proprietary cryptographic algorithms, SharkSSL can be fine-tuned to a footprint that occupies less than 20 kB, while maintaining full x.509 authentication. The SharkSSL-Lite download includes a subset of SharkSSL and header files made for use in non-commercial and for evaluation purposes.

Features

Examples

Limitations

SharkSSL-Lite includes a limited set of ciphers. To use SharkSSL-Lite, the peer side must support Elliptic Curve Cryptography (ECC) and you must use ECC certificates. The peer side must also support the new ChaCha20/Poly1305 cipher combination.

ChaCha20 and Poly1305 for TLS is published RFC 7905. The development of this new cipher was a response to many attacks discovered against other widely used TLS cipher suites. ChaCha20 is the cipher and Poly1305 is an authenticated encryption mode.

SharkSSL-Lite occupies less than 20kB, while maintaining full x.509 authentication. The ChaCha20/Poly1305 cipher software implementation is equally as fast as many hardware accelerated AES engines.

Creating ECC Certificates for SharkSSL-Lite

The following video shows how to create an Elliptic Curve Cryptography (ECC) certificate for a server, how to install the certificate in the server, and how to make the mbed clients connecting to the server trust this certificate. The server in this video is installed on a private/personal computer on a private network for test purposes. The video was produced for the embedded.com article How to run your own secure IoT cloud server.

inc/SharkMQTT.h@1:d5e0e1dcf0d6, 2016-05-23 (annotated)

Committer:
wini
Date:
Mon May 23 13:56:30 2016 +0000
Revision:
1:d5e0e1dcf0d6
Parent:
0:e0adec41ad6b 
Type conflict fix (U8-U32) for latest mbed release.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
wini 0:e0adec41ad6b 1 /*
wini 0:e0adec41ad6b 2 * ____ _________ __ _
wini 0:e0adec41ad6b 3 * / __ \___ ____ _/ /_ __(_)___ ___ ___ / / ____ ____ _(_)____
wini 0:e0adec41ad6b 4 * / /_/ / _ \/ __ `/ / / / / / __ `__ \/ _ \/ / / __ \/ __ `/ / ___/
wini 0:e0adec41ad6b 5 * / _, _/ __/ /_/ / / / / / / / / / / / __/ /___/ /_/ / /_/ / / /__
wini 0:e0adec41ad6b 6 * /_/ |_|\___/\__,_/_/ /_/ /_/_/ /_/ /_/\___/_____/\____/\__, /_/\___/
wini 0:e0adec41ad6b 7 * /____/
wini 0:e0adec41ad6b 8 ****************************************************************************
wini 0:e0adec41ad6b 9 * HEADER
wini 0:e0adec41ad6b 10 *
wini 0:e0adec41ad6b 11 * This file is part of SharkMQTT:
wini 0:e0adec41ad6b 12 * https://realtimelogic.com/products/sharkmqtt/
wini 0:e0adec41ad6b 13 *
wini 0:e0adec41ad6b 14 * $Id: SharkMQTT.h 3663 2015-03-05 16:52:37Z wini $
wini 0:e0adec41ad6b 15 *
wini 0:e0adec41ad6b 16 * COPYRIGHT: Real Time Logic, 2015
wini 0:e0adec41ad6b 17 *
wini 0:e0adec41ad6b 18 * This software is copyrighted by and is the sole property of Real
wini 0:e0adec41ad6b 19 * Time Logic LLC. All rights, title, ownership, or other interests in
wini 0:e0adec41ad6b 20 * the software remain the property of Real Time Logic LLC. This
wini 0:e0adec41ad6b 21 * software may only be used in accordance with the terms and
wini 0:e0adec41ad6b 22 * conditions stipulated in the corresponding license agreement under
wini 0:e0adec41ad6b 23 * which the software has been supplied. Any unauthorized use,
wini 0:e0adec41ad6b 24 * duplication, transmission, distribution, or disclosure of this
wini 0:e0adec41ad6b 25 * software is expressly forbidden.
wini 0:e0adec41ad6b 26 *
wini 0:e0adec41ad6b 27 * This Copyright notice may not be removed or modified without prior
wini 0:e0adec41ad6b 28 * written consent of Real Time Logic LLC.
wini 0:e0adec41ad6b 29 *
wini 0:e0adec41ad6b 30 * Real Time Logic LLC. reserves the right to modify this software
wini 0:e0adec41ad6b 31 * without notice.
wini 0:e0adec41ad6b 32 *
wini 0:e0adec41ad6b 33 * http://www.realtimelogic.com
wini 0:e0adec41ad6b 34 */
wini 0:e0adec41ad6b 35
wini 0:e0adec41ad6b 36 #ifndef _SharkMQTT_h
wini 0:e0adec41ad6b 37 #define _SharkMQTT_h
wini 0:e0adec41ad6b 38
wini 0:e0adec41ad6b 39 #include <selib.h>
wini 0:e0adec41ad6b 40 #include <DoubleList.h>
wini 0:e0adec41ad6b 41
wini 0:e0adec41ad6b 42
wini 0:e0adec41ad6b 43
wini 0:e0adec41ad6b 44 typedef enum
wini 0:e0adec41ad6b 45 {
wini 0:e0adec41ad6b 46 MqttState_Invalid,
wini 0:e0adec41ad6b 47 MqttState_Pub,
wini 0:e0adec41ad6b 48 MqttState_PubRel,
wini 0:e0adec41ad6b 49 MqttState_PubRec,
wini 0:e0adec41ad6b 50 MqttState_SubOrUnsub
wini 0:e0adec41ad6b 51 } MqttState;
wini 0:e0adec41ad6b 52
wini 0:e0adec41ad6b 53
wini 0:e0adec41ad6b 54 typedef struct
wini 0:e0adec41ad6b 55 {
wini 0:e0adec41ad6b 56 DoubleLink super;
wini 0:e0adec41ad6b 57 U32 timeStamp;
wini 0:e0adec41ad6b 58 U16 packetId; /* [MQTT-2.3.1] Packet Identifier */
wini 0:e0adec41ad6b 59 U8 state; /* type MqttState */
wini 0:e0adec41ad6b 60 } MqttInFlightMsg;
wini 0:e0adec41ad6b 61
wini 0:e0adec41ad6b 62
wini 0:e0adec41ad6b 63
wini 0:e0adec41ad6b 64 /** @addtogroup MQTTLib
wini 0:e0adec41ad6b 65 @{
wini 0:e0adec41ad6b 66 */
wini 0:e0adec41ad6b 67
wini 0:e0adec41ad6b 68 /** \defgroup SharkMQTTErrorCodes Error codes returned by function SharkMQTT_getMessage
wini 0:e0adec41ad6b 69 \ingroup SharkMQTT
wini 0:e0adec41ad6b 70 \anchor SharkMQTTErrorCodes Error codes returned by function #SharkMQTT_getMessage
wini 0:e0adec41ad6b 71 @{
wini 0:e0adec41ad6b 72 */
wini 0:e0adec41ad6b 73
wini 0:e0adec41ad6b 74 /** Error codes received from the TCP/IP stack are sent "as is". These
wini 0:e0adec41ad6b 75 error codes have a value greater than #SMQTTE_ERRORBASE.
wini 0:e0adec41ad6b 76 */
wini 0:e0adec41ad6b 77 #define SMQTTE_SOCKET -1
wini 0:e0adec41ad6b 78
wini 0:e0adec41ad6b 79 /** This code is not used. The code is the base for error codes returned by SharkMQ.
wini 0:e0adec41ad6b 80 */
wini 0:e0adec41ad6b 81 #define SMQTTE_ERRORBASE -10000
wini 0:e0adec41ad6b 82
wini 0:e0adec41ad6b 83 /** Similar to #SMQTT_TIMEOUT, but returned when a timeout was not expected.
wini 0:e0adec41ad6b 84 */
wini 0:e0adec41ad6b 85 #define SMQTTE_TIMEOUT -10001
wini 0:e0adec41ad6b 86
wini 0:e0adec41ad6b 87 /** The client sent a PING to the broker but did not receive a PONG response.
wini 0:e0adec41ad6b 88 */
wini 0:e0adec41ad6b 89 #define SMQTTE_PONGTIMEOUT -10002
wini 0:e0adec41ad6b 90
wini 0:e0adec41ad6b 91 /** Something's wrong.
wini 0:e0adec41ad6b 92 */
wini 0:e0adec41ad6b 93 #define SMQTTE_PROTOCOL_ERROR -10003
wini 0:e0adec41ad6b 94
wini 0:e0adec41ad6b 95 /** The SharkSSL output buffer is not sufficiently large for the operation
wini 0:e0adec41ad6b 96 you are attempting. Increase the buffer size.
wini 0:e0adec41ad6b 97 */
wini 0:e0adec41ad6b 98 #define SMQTTE_OVERFLOW -10005
wini 0:e0adec41ad6b 99
wini 0:e0adec41ad6b 100 /** Calling SharkMQ_connect when a connection is already established.
wini 0:e0adec41ad6b 101 */
wini 0:e0adec41ad6b 102 #define SMQTTE_ALREADYCON -10006
wini 0:e0adec41ad6b 103
wini 0:e0adec41ad6b 104 /** Broker refused the connection request. See #SharkMQTT_connackCode
wini 0:e0adec41ad6b 105 for details.
wini 0:e0adec41ad6b 106 */
wini 0:e0adec41ad6b 107 #define SMQTTE_CONREFUSED -10007
wini 0:e0adec41ad6b 108
wini 0:e0adec41ad6b 109 /** Returned by SharkMQTT_connect if a password was provided and if
wini 0:e0adec41ad6b 110 the broker's certificate/name is not trusted.
wini 0:e0adec41ad6b 111 */
wini 0:e0adec41ad6b 112 #define SMQTTE_SERVERNOTTRUSTED -10008
wini 0:e0adec41ad6b 113
wini 0:e0adec41ad6b 114
wini 0:e0adec41ad6b 115 /** @} */ /* end SharkMQTTErrorCodes */
wini 0:e0adec41ad6b 116
wini 0:e0adec41ad6b 117
wini 0:e0adec41ad6b 118 /** \defgroup SharkMQTTRespCodes Response codes returned by function SharkMQTT_getMessage
wini 0:e0adec41ad6b 119 \ingroup SharkMQTT
wini 0:e0adec41ad6b 120 \anchor SharkMQTTRespCodes Response codes returned by function #SharkMQTT_getMessage
wini 0:e0adec41ad6b 121 @{
wini 0:e0adec41ad6b 122 */
wini 0:e0adec41ad6b 123
wini 0:e0adec41ad6b 124
wini 0:e0adec41ad6b 125 /** #SharkMQTT_getMessage call timed out. The variable
wini 0:e0adec41ad6b 126 SharkMQTT::timeout controls the timout period.
wini 0:e0adec41ad6b 127 */
wini 0:e0adec41ad6b 128 #define SMQTT_TIMEOUT -20000
wini 0:e0adec41ad6b 129
wini 0:e0adec41ad6b 130 /** Asynchronous #SharkMQTT_subscribe response message received via
wini 0:e0adec41ad6b 131 #SharkMQTT_getMessage.
wini 0:e0adec41ad6b 132 */
wini 0:e0adec41ad6b 133 #define SMQTT_SUBACK -20001
wini 0:e0adec41ad6b 134
wini 0:e0adec41ad6b 135 /** Asynchronous #SharkMQTT_unsubscribe response message received via
wini 0:e0adec41ad6b 136 #SharkMQTT_getMessage.
wini 0:e0adec41ad6b 137 */
wini 0:e0adec41ad6b 138 #define SMQTT_UNSUBACK -20002
wini 0:e0adec41ad6b 139
wini 0:e0adec41ad6b 140 /** @} */ /* end SharkMQTTRespCodes */
wini 0:e0adec41ad6b 141
wini 0:e0adec41ad6b 142
wini 0:e0adec41ad6b 143 /** Optional MQTT Will Message; used when calling function SharkMQTT_connect.
wini 0:e0adec41ad6b 144 */
wini 0:e0adec41ad6b 145 typedef struct
wini 0:e0adec41ad6b 146 {
wini 0:e0adec41ad6b 147 const char* topic; /*!< Will topic (utf-8). [MQTT-3.1.3.2] */
wini 0:e0adec41ad6b 148 const U8* message; /*!< Will message (binary). [MQTT-3.1.3.3] */
wini 0:e0adec41ad6b 149 U16 msgLen; /*!< Will message length */
wini 0:e0adec41ad6b 150 U8 qos; /*!< Will QoS: 0, 1, or 2. [MQTT-3.1.2.6] */
wini 0:e0adec41ad6b 151 /** Specifies if the Will Message is to be Retained when it is published.
wini 0:e0adec41ad6b 152 [MQTT-3.1.2.7] Will Retain.
wini 0:e0adec41ad6b 153 */
wini 0:e0adec41ad6b 154 BaBool retain;
wini 0:e0adec41ad6b 155 } MqttWillMsg;
wini 0:e0adec41ad6b 156
wini 0:e0adec41ad6b 157
wini 0:e0adec41ad6b 158 /** Optional credentials used when calling function SharkMQTT_connect.
wini 0:e0adec41ad6b 159 */
wini 0:e0adec41ad6b 160 typedef struct
wini 0:e0adec41ad6b 161 {
wini 0:e0adec41ad6b 162 /** Optional User Name (utf-8). Set to NULL if not used. [MQTT-3.1.3.4] */
wini 0:e0adec41ad6b 163 const char* username;
wini 0:e0adec41ad6b 164 /** Optional Password (binary). Set to NULL if not
wini 0:e0adec41ad6b 165 used. [MQTT-3.1.3.5]. If username is set to NULL, the password
wini 0:e0adec41ad6b 166 MUST be set to NULL [MQTT-3.1.2-22].
wini 0:e0adec41ad6b 167 */
wini 0:e0adec41ad6b 168 const U8* password;
wini 0:e0adec41ad6b 169 /** You must provide a password length if 'password' is non NULL. */
wini 0:e0adec41ad6b 170 U16 pwdlen;
wini 0:e0adec41ad6b 171 } MqttCredentials;
wini 0:e0adec41ad6b 172
wini 0:e0adec41ad6b 173
wini 0:e0adec41ad6b 174 /** SharkMQTT structure.
wini 0:e0adec41ad6b 175 See [SharkMQ library](@ref MQTTLib) for details.
wini 0:e0adec41ad6b 176 */
wini 0:e0adec41ad6b 177 typedef struct
wini 0:e0adec41ad6b 178 {
wini 0:e0adec41ad6b 179 SOCKET sock;
wini 0:e0adec41ad6b 180
wini 0:e0adec41ad6b 181 DoubleList recQueue; /* type MqttInFlightMsg: for QOS > 0 */
wini 0:e0adec41ad6b 182 DoubleList sendQueue; /* type MqttInFlightMsg: for QOS > 0 */
wini 0:e0adec41ad6b 183
wini 0:e0adec41ad6b 184 SharkSslCon* scon;
wini 0:e0adec41ad6b 185
wini 0:e0adec41ad6b 186 /** Time interval in seconds for MQTT PING messages sent to the
wini 0:e0adec41ad6b 187 * server. The default value is 20 minutes (1200 seconds). Note:
wini 0:e0adec41ad6b 188 * the variable must be set before calling SharkMQTT_connect.
wini 0:e0adec41ad6b 189 */
wini 0:e0adec41ad6b 190 S32 pingTmo;
wini 0:e0adec41ad6b 191
wini 0:e0adec41ad6b 192 S32 pongTmoCounter;
wini 0:e0adec41ad6b 193 U32 pingTickTime;
wini 0:e0adec41ad6b 194
wini 0:e0adec41ad6b 195 U8* recPackHeader; /* from constructor: buf */
wini 0:e0adec41ad6b 196 U16 recPackHeaderLen; /* from constructor: bufLen */
wini 0:e0adec41ad6b 197
wini 0:e0adec41ad6b 198 U16 packetId; /* send packet ID counter */
wini 0:e0adec41ad6b 199
wini 0:e0adec41ad6b 200 /** MQTT packet length
wini 0:e0adec41ad6b 201 */
wini 0:e0adec41ad6b 202 U32 packetLen;
wini 0:e0adec41ad6b 203
wini 0:e0adec41ad6b 204 /** Read packet data using #SharkMQTT_getMessage until:
wini 0:e0adec41ad6b 205 packetLen-bytesRead == 0.
wini 0:e0adec41ad6b 206 \sa SharkMQTT_msgConsumed
wini 0:e0adec41ad6b 207 */
wini 0:e0adec41ad6b 208 U32 bytesRead;
wini 0:e0adec41ad6b 209
wini 0:e0adec41ad6b 210 /** MQTT message length
wini 0:e0adec41ad6b 211 */
wini 0:e0adec41ad6b 212 U32 msgLen;
wini 0:e0adec41ad6b 213
wini 0:e0adec41ad6b 214 U8* overflowPtr; /* Set if: consumed more data from stream than frame len */
wini 0:e0adec41ad6b 215 int overflowLen; /* overflowPtr len is used internally in wsRawRead */
wini 0:e0adec41ad6b 216 int messageHeaderIx; /* Cursor used when reading recPackHeader from socket */
wini 0:e0adec41ad6b 217
wini 0:e0adec41ad6b 218 /** Timeout in milliseconds to wait in functions waiting for server
wini 0:e0adec41ad6b 219 data
wini 0:e0adec41ad6b 220 */
wini 0:e0adec41ad6b 221 U32 timeout;
wini 0:e0adec41ad6b 222
wini 0:e0adec41ad6b 223 U16 recPacketId; /* For received packets with QOS 1 or 2 */
wini 0:e0adec41ad6b 224 U8 recQOS; /* For received packets with QOS 1 or 2 */
wini 0:e0adec41ad6b 225 } SharkMQTT;
wini 0:e0adec41ad6b 226
wini 0:e0adec41ad6b 227
wini 0:e0adec41ad6b 228 /** Create a SharkMQTT client instance.
wini 0:e0adec41ad6b 229 \param o Uninitialized data of size sizeof(SharkMQTT).
wini 0:e0adec41ad6b 230 \param buf is used for internal management and must not be less
wini 0:e0adec41ad6b 231 than the size of the largest control message. Function
wini 0:e0adec41ad6b 232 SharkMQTT_getMessage will return #SMQTTE_OVERFLOW if the buffer is
wini 0:e0adec41ad6b 233 not sufficiently large.
wini 0:e0adec41ad6b 234 \param bufLen buffer length.
wini 0:e0adec41ad6b 235 */
wini 0:e0adec41ad6b 236 void SharkMQTT_constructor(SharkMQTT* o, U8* buf, U16 bufLen);
wini 0:e0adec41ad6b 237
wini 0:e0adec41ad6b 238
wini 0:e0adec41ad6b 239 /** Terminate a SharkMQTT instance.
wini 0:e0adec41ad6b 240 \param o SharkMQTT instance
wini 0:e0adec41ad6b 241 */
wini 0:e0adec41ad6b 242 void SharkMQTT_destructor(SharkMQTT* o);
wini 0:e0adec41ad6b 243
wini 0:e0adec41ad6b 244
wini 0:e0adec41ad6b 245 /** Read packet data using #SharkMQTT_getMessage until
wini 0:e0adec41ad6b 246 SharkMQTT_msgConsumed returns TRUE.
wini 0:e0adec41ad6b 247 \param o SharkMQTT instance
wini 0:e0adec41ad6b 248 */
wini 0:e0adec41ad6b 249 #define SharkMQTT_msgConsumed(o) (((o)->packetLen - (o)->bytesRead) == 0)
wini 0:e0adec41ad6b 250
wini 0:e0adec41ad6b 251
wini 0:e0adec41ad6b 252 /** Connection response (CONNACK) return code.
wini 0:e0adec41ad6b 253 This function should be called if SharkMQTT_connect returns
wini 0:e0adec41ad6b 254 #SMQTTE_CONREFUSED.
wini 0:e0adec41ad6b 255 \returns one of the following codes:
wini 0:e0adec41ad6b 256 - 0x00 Connection Accepted
wini 0:e0adec41ad6b 257 - 0x01 Connection Refused, unacceptable protocol version
wini 0:e0adec41ad6b 258 - 0x02 Connection Refused, identifier rejected
wini 0:e0adec41ad6b 259 - 0x03 Connection Refused, Server unavailable
wini 0:e0adec41ad6b 260 - 0x04 Connection Refused, bad user name or password
wini 0:e0adec41ad6b 261 - 0x05 Connection Refused, not authorized
wini 0:e0adec41ad6b 262
wini 0:e0adec41ad6b 263 See [MQTT-3.2.2.3] for details.
wini 0:e0adec41ad6b 264 */
wini 0:e0adec41ad6b 265 #define SharkMQTT_connackCode(o) (o)->recPackHeader[3]
wini 0:e0adec41ad6b 266
wini 0:e0adec41ad6b 267
wini 0:e0adec41ad6b 268 /** Returns TRUE if a session is restored. This function can only be
wini 0:e0adec41ad6b 269 used immediately after calling function SharkMQTT_connect.
wini 0:e0adec41ad6b 270
wini 0:e0adec41ad6b 271 See [MQTT-3.2.2.2] for details.
wini 0:e0adec41ad6b 272
wini 0:e0adec41ad6b 273 \param o SharkMQTT instance
wini 0:e0adec41ad6b 274
wini 0:e0adec41ad6b 275 \sa argument cleanSession in function #SharkMQTT_connect
wini 0:e0adec41ad6b 276 */
wini 0:e0adec41ad6b 277 #define SharkMQTT_sessionPresent(o) ((o)->recPackHeader[2] & 1)
wini 0:e0adec41ad6b 278
wini 0:e0adec41ad6b 279 /** Returns SharkSslConTrust when SharkMQTT_connect returns
wini 0:e0adec41ad6b 280 #SMQTTE_SERVERNOTTRUSTED
wini 0:e0adec41ad6b 281
wini 0:e0adec41ad6b 282 \param o SharkMQTT instance
wini 0:e0adec41ad6b 283 */
wini 0:e0adec41ad6b 284 #define SharkMQTT_trustInfo(o) ((SharkSslConTrust)(o)->packetLen)
wini 0:e0adec41ad6b 285
wini 0:e0adec41ad6b 286
wini 0:e0adec41ad6b 287 /** Establish (or re-establish) an MQTT session.
wini 0:e0adec41ad6b 288
wini 0:e0adec41ad6b 289 \param o SharkMQTT instance
wini 0:e0adec41ad6b 290 \param scon SharkSslCon instance created by calling #SharkSsl_createCon.
wini 0:e0adec41ad6b 291
wini 0:e0adec41ad6b 292 \param address the MQTT broker address
wini 0:e0adec41ad6b 293 \param port the MQTT broker listen port number (typically 1883)
wini 0:e0adec41ad6b 294 \param clientId a unique ID [MQTT-3.1.3.1]
wini 0:e0adec41ad6b 295 \param cred optional credentials
wini 0:e0adec41ad6b 296 \param cleanSession
wini 0:e0adec41ad6b 297 \param wm optional MQTT will message
wini 0:e0adec41ad6b 298
wini 0:e0adec41ad6b 299 \returns a return value greater than zero means that a connection is
wini 0:e0adec41ad6b 300 established, but the connection is not trusted unless the return
wini 0:e0adec41ad6b 301 value is #SharkSslConTrust_CertCn.
wini 0:e0adec41ad6b 302
wini 0:e0adec41ad6b 303 one of the following values on error.
wini 0:e0adec41ad6b 304 - #SMQTTE_ALREADYCON
wini 0:e0adec41ad6b 305 - #SMQTTE_CONREFUSED
wini 0:e0adec41ad6b 306 - #SMQTTE_TIMEOUT
wini 0:e0adec41ad6b 307 - #SMQTTE_OVERFLOW
wini 0:e0adec41ad6b 308 - #SMQTTE_SERVERNOTTRUSTED
wini 0:e0adec41ad6b 309 - -1
wini 0:e0adec41ad6b 310 - -2
wini 0:e0adec41ad6b 311 - -3
wini 0:e0adec41ad6b 312
wini 0:e0adec41ad6b 313 Error codes -1 to -3 are error codes from #se_connect
wini 0:e0adec41ad6b 314
wini 0:e0adec41ad6b 315 If #SMQTTE_CONREFUSED is returned, the reason for the refused
wini 0:e0adec41ad6b 316 connection is found by calling #SharkMQTT_connackCode.
wini 0:e0adec41ad6b 317
wini 0:e0adec41ad6b 318 \sa #SharkMQTT_sessionPresent
wini 0:e0adec41ad6b 319 */
wini 0:e0adec41ad6b 320 int SharkMQTT_connect(SharkMQTT* o, SharkSslCon* scon,
wini 0:e0adec41ad6b 321 const char* address, U16 port,
wini 0:e0adec41ad6b 322 const char* clientId, MqttCredentials* cred,
wini 0:e0adec41ad6b 323 BaBool cleanSession, MqttWillMsg* wm);
wini 0:e0adec41ad6b 324
wini 0:e0adec41ad6b 325
wini 0:e0adec41ad6b 326 /** Subscribe to topic.
wini 0:e0adec41ad6b 327
wini 0:e0adec41ad6b 328 The response to SharkMQ_subscribe is asynchronous and returned as status
wini 0:e0adec41ad6b 329 #SMQTT_SUBACK via #SharkMQTT_getMessage.
wini 0:e0adec41ad6b 330
wini 0:e0adec41ad6b 331 \param o SharkMQTT instance
wini 0:e0adec41ad6b 332 \param topic the topic name to subscribe to.
wini 0:e0adec41ad6b 333 \param qos Maximum Quality Of Zero on inbound messages can be set
wini 0:e0adec41ad6b 334 to 0, 1, or 2. Note that SharkMQTT must dynamically allocate and
wini 0:e0adec41ad6b 335 keep a small control structure for each received message
wini 0:e0adec41ad6b 336 with QOS 2. This structure is kept until the broker QOS 2
wini 0:e0adec41ad6b 337 handshaking has completed.
wini 0:e0adec41ad6b 338 \param packetId optional packet ID. The packetId can be matched
wini 0:e0adec41ad6b 339 when #SharkMQ_getMessage returns #SMQTT_SUBACK.
wini 0:e0adec41ad6b 340 \returns zero on success and a negative value on socket error.
wini 0:e0adec41ad6b 341 */
wini 0:e0adec41ad6b 342 int SharkMQTT_subscribe(SharkMQTT* o, const char* topic, U8 qos, U16* packetId);
wini 0:e0adec41ad6b 343
wini 0:e0adec41ad6b 344
wini 0:e0adec41ad6b 345 /** Requests the broker to unsubscribe the client from a topic.
wini 0:e0adec41ad6b 346
wini 0:e0adec41ad6b 347 The response to SharkMQ_unsubscribe is asynchronous and returned as status
wini 0:e0adec41ad6b 348 #SMQTT_UNSUBACK via #SharkMQTT_getMessage.
wini 0:e0adec41ad6b 349
wini 0:e0adec41ad6b 350 \param o SharkMQTT instance
wini 0:e0adec41ad6b 351 \param topic the topic name to unsubscribe from.
wini 0:e0adec41ad6b 352 \param packetId optional packet ID. The packetId can be matched
wini 0:e0adec41ad6b 353 when #SharkMQ_getMessage returns #SMQTT_UNSUBACK.
wini 0:e0adec41ad6b 354 \returns zero on success and a negative value on socket error.
wini 0:e0adec41ad6b 355 */
wini 0:e0adec41ad6b 356 int SharkMQTT_unsubscribe(SharkMQTT* o, const char* topic, U16* packetId);
wini 0:e0adec41ad6b 357
wini 0:e0adec41ad6b 358
wini 0:e0adec41ad6b 359 /** Prepare a zero copy publish by fetching the SharkSSL send buffer
wini 0:e0adec41ad6b 360 pointer and offset the pointer to the MQTT message payload.
wini 0:e0adec41ad6b 361 \param o SharkMQTT instance
wini 0:e0adec41ad6b 362 \param topic must match topic passed into function #SharkMQTT_publish
wini 0:e0adec41ad6b 363 \param qos must also match
wini 0:e0adec41ad6b 364 \param maxMsgLen is an out value and indicates the maximum number
wini 0:e0adec41ad6b 365 of bytes that can be copied into the pointer return by this
wini 0:e0adec41ad6b 366 function. The length is the SharkSSL buffer's out buffer size -
wini 0:e0adec41ad6b 367 the MQTT header size.
wini 0:e0adec41ad6b 368
wini 0:e0adec41ad6b 369 \returns a pointer to where you can copy the message.
wini 0:e0adec41ad6b 370
wini 0:e0adec41ad6b 371 Example:
wini 0:e0adec41ad6b 372
wini 0:e0adec41ad6b 373 \code
wini 0:e0adec41ad6b 374 int maxMsgLen;
wini 0:e0adec41ad6b 375 U8* buf = SharkMQTT_zeroCopyPub(mqtt, "/message/", 1, &maxMsgLen);
wini 0:e0adec41ad6b 376 strcpy(buf, "Hello World")
wini 0:e0adec41ad6b 377 SharkMQTT_publish(mqtt, "/message/", NULL, strlen(buf), FALSE, 1);
wini 0:e0adec41ad6b 378 \endcode
wini 0:e0adec41ad6b 379
wini 0:e0adec41ad6b 380 Notice that the message pointer is set to NULL when calling
wini 0:e0adec41ad6b 381 SharkMQTT_publish.
wini 0:e0adec41ad6b 382 */
wini 0:e0adec41ad6b 383 U8* SharkMQTT_zeroCopyPub(
wini 0:e0adec41ad6b 384 SharkMQTT* o, const char* topic, U8 qos, int* maxMsgLen);
wini 0:e0adec41ad6b 385
wini 0:e0adec41ad6b 386
wini 0:e0adec41ad6b 387 /** Publish a QOS 0 message and set the retain flag to FALSE.
wini 0:e0adec41ad6b 388 \param o SharkMQTT instance
wini 0:e0adec41ad6b 389 \param topic the topic name
wini 0:e0adec41ad6b 390 \param msg message payload.
wini 0:e0adec41ad6b 391 \param msgLen payload length.
wini 0:e0adec41ad6b 392
wini 0:e0adec41ad6b 393 \returns zero on success and a negative value on socket error.
wini 0:e0adec41ad6b 394 \sa SharkMQTT_publish
wini 0:e0adec41ad6b 395 */
wini 0:e0adec41ad6b 396 #define SharkMQTT_pub0(o, topic, msg, msgLen) \
wini 0:e0adec41ad6b 397 SharkMQTT_publish(o, topic, msg, msgLen, FALSE, 0)
wini 0:e0adec41ad6b 398
wini 0:e0adec41ad6b 399
wini 0:e0adec41ad6b 400 /** Publish messages to a topic.
wini 0:e0adec41ad6b 401
wini 0:e0adec41ad6b 402 Messages with QOS 1 or 2 cannot be larger than the SharkSSL outbuf size.
wini 0:e0adec41ad6b 403
wini 0:e0adec41ad6b 404 \param o SharkMQTT instance
wini 0:e0adec41ad6b 405 \param topic the topic name
wini 0:e0adec41ad6b 406 \param msg message payload. This pointer is set to
wini 0:e0adec41ad6b 407 NULL when used together with function #SharkMQTT_zeroCopyPub.
wini 0:e0adec41ad6b 408 \param msgLen payload length.
wini 0:e0adec41ad6b 409 \param retain flag is set to TRUE or FALSE [MQTT-3.3.1.3]
wini 0:e0adec41ad6b 410 \param qos Quality Of Zero is 0, 1, or 2. Note that SharkMQTT must
wini 0:e0adec41ad6b 411 dynamically allocate and keep messages with QOS 1 and 2 until the
wini 0:e0adec41ad6b 412 broker QOS handshaking has completed.
wini 0:e0adec41ad6b 413
wini 0:e0adec41ad6b 414 \returns zero on success and a negative value on socket error.
wini 0:e0adec41ad6b 415 \sa SharkMQTT_pub0
wini 0:e0adec41ad6b 416 */
wini 0:e0adec41ad6b 417 int SharkMQTT_publish(SharkMQTT* o, const char* topic,
wini 0:e0adec41ad6b 418 const void* msg, int msgLen, U8 retain, U8 qos);
wini 0:e0adec41ad6b 419
wini 0:e0adec41ad6b 420
wini 0:e0adec41ad6b 421 /** Returns packetId when the return value from #SharkMQTT_getMessage
wini 0:e0adec41ad6b 422 is #SMQTT_SUBACK or #SMQTT_UNSUBACK.
wini 0:e0adec41ad6b 423
wini 0:e0adec41ad6b 424 \param o SharkMQTT instance
wini 0:e0adec41ad6b 425 */
wini 0:e0adec41ad6b 426 #define SharkMQTT_packetId(o) (o)->recPacketId
wini 0:e0adec41ad6b 427
wini 0:e0adec41ad6b 428 /** Returns the subscribe response code when the return value from
wini 0:e0adec41ad6b 429 #SharkMQTT_getMessage is #SMQTT_SUBACK.
wini 0:e0adec41ad6b 430
wini 0:e0adec41ad6b 431 \param o SharkMQTT instance
wini 0:e0adec41ad6b 432
wini 0:e0adec41ad6b 433 \returns
wini 0:e0adec41ad6b 434 - 0x00: Success - Maximum QoS 0
wini 0:e0adec41ad6b 435 - 0x01: Success - Maximum QoS 1
wini 0:e0adec41ad6b 436 - 0x02: Success - Maximum QoS 2
wini 0:e0adec41ad6b 437 - 0x80: Failure
wini 0:e0adec41ad6b 438 */
wini 0:e0adec41ad6b 439 #define SharkMQTT_subAckCode(o) ((U16)(o)->recPackHeader[4])
wini 0:e0adec41ad6b 440
wini 0:e0adec41ad6b 441
wini 0:e0adec41ad6b 442 /** Returns the dup flag (TRUE/FALSE) [MQTT-3.3.1.1] for received
wini 0:e0adec41ad6b 443 PUBLISH messages i.e. when #SharkMQTT_getMessage returns a value
wini 0:e0adec41ad6b 444 greater than zero.
wini 0:e0adec41ad6b 445
wini 0:e0adec41ad6b 446 \param o SharkMQTT instance
wini 0:e0adec41ad6b 447 */
wini 0:e0adec41ad6b 448 #define SharkMQTT_dup(o) (((o)->recPackHeader[0] & 8) ? TRUE : FALSE)
wini 0:e0adec41ad6b 449
wini 0:e0adec41ad6b 450 /** Returns QOS (0, 1, or 2) [MQTT-3.3.1.2] for received
wini 0:e0adec41ad6b 451 PUBLISH messages i.e. when #SharkMQTT_getMessage returns a value
wini 0:e0adec41ad6b 452 greater than zero.
wini 0:e0adec41ad6b 453 \param o SharkMQTT instance
wini 0:e0adec41ad6b 454 */
wini 0:e0adec41ad6b 455 #define SharkMQTT_QOS(o) (((o)->recPackHeader[0] >> 1) & 3)
wini 0:e0adec41ad6b 456
wini 0:e0adec41ad6b 457 /** Returns the retain flag (TRUE/FALSE) [MQTT-3.3.1.3] for received
wini 0:e0adec41ad6b 458 PUBLISH messages i.e. when #SharkMQTT_getMessage returns a value
wini 0:e0adec41ad6b 459 greater than zero.
wini 0:e0adec41ad6b 460 \param o SharkMQTT instance
wini 0:e0adec41ad6b 461 */
wini 0:e0adec41ad6b 462 #define SharkMQTT_retain(o) ((o)->recPackHeader[0] & 1)
wini 0:e0adec41ad6b 463
wini 0:e0adec41ad6b 464 /** Returns the topic name for received PUBLISH messages i.e. when
wini 0:e0adec41ad6b 465 #SharkMQTT_getMessage returns a value greater than zero.
wini 0:e0adec41ad6b 466 \param o SharkMQTT instance
wini 0:e0adec41ad6b 467 */
wini 0:e0adec41ad6b 468 #define SharkMQTT_topic(o) ((const char*)((o)->recPackHeader+1))
wini 0:e0adec41ad6b 469
wini 0:e0adec41ad6b 470 /** Wait for messages sent from the broker.
wini 0:e0adec41ad6b 471
wini 0:e0adec41ad6b 472 \param o SharkMQTT instance
wini 0:e0adec41ad6b 473
wini 0:e0adec41ad6b 474 \param msg a pointer to the response data (out param)
wini 0:e0adec41ad6b 475
wini 0:e0adec41ad6b 476 \returns
wini 0:e0adec41ad6b 477 \li a negative value signals an
wini 0:e0adec41ad6b 478 [error code](\ref SharkMQTTErrorCodes) or an
wini 0:e0adec41ad6b 479 [asynchronous response code](\ref SharkMQTTRespCodes).
wini 0:e0adec41ad6b 480 \li a value greater than zero signals the reception of a full
wini 0:e0adec41ad6b 481 message or a message fragment. See receiving large packets for details.
wini 0:e0adec41ad6b 482
wini 0:e0adec41ad6b 483 <b>Receiving large packets:</b><br>
wini 0:e0adec41ad6b 484 The MQTT protocol is frame based, but the function can return a
wini 0:e0adec41ad6b 485 fragment before the complete MQTT packet is received if the packet
wini 0:e0adec41ad6b 486 sent by the broker is larger than the SharkSSL buffer. The message
wini 0:e0adec41ad6b 487 payload length is returned in SharkMQTT::packetLen and the data
wini 0:e0adec41ad6b 488 consumed thus far is returned in SharkMQTT::bytesRead. The
wini 0:e0adec41ad6b 489 complete frame is consumed when SharkMQTT::packetLen ==
wini 0:e0adec41ad6b 490 SharkMQTT::bytesRead. Function #SharkMQTT_msgConsumed returns TRUE
wini 0:e0adec41ad6b 491 when the complete packet has been received.
wini 0:e0adec41ad6b 492
wini 0:e0adec41ad6b 493 <b>Note:</b> the default timeout value is set to one minute. You
wini 0:e0adec41ad6b 494 can set the timeout value by setting SharkMQTT::timeout to the
wini 0:e0adec41ad6b 495 number of milliseconds you want to wait for incoming messages
wini 0:e0adec41ad6b 496 before the timeout triggers. Note: Setting a long timeout may
wini 0:e0adec41ad6b 497 interfere with the built in PING timer.
wini 0:e0adec41ad6b 498 */
wini 0:e0adec41ad6b 499 int SharkMQTT_getMessage(SharkMQTT* o, U8** msg);
wini 0:e0adec41ad6b 500
wini 0:e0adec41ad6b 501
wini 0:e0adec41ad6b 502 /** Send a disconnect command to the broker and gracefully close the connection.
wini 0:e0adec41ad6b 503 \param o SharkMQTT instance
wini 0:e0adec41ad6b 504 */
wini 0:e0adec41ad6b 505 void SharkMQTT_disconnect(SharkMQTT* o);
wini 0:e0adec41ad6b 506
wini 0:e0adec41ad6b 507 /** @} */ /* end group MQTTLib */
wini 0:e0adec41ad6b 508
wini 0:e0adec41ad6b 509 #endif