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/SharkMQ.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 ****************************************************************************
wini 0:e0adec41ad6b 10 * HEADER
wini 0:e0adec41ad6b 11 *
wini 0:e0adec41ad6b 12 * This file is part of SharkMQ:
wini 0:e0adec41ad6b 13 * https://realtimelogic.com/products/simplemq/
wini 0:e0adec41ad6b 14 *
wini 0:e0adec41ad6b 15 * $Id: SharkMQ.h 3635 2014-12-31 03:39:41Z wini $
wini 0:e0adec41ad6b 16 *
wini 0:e0adec41ad6b 17 * COPYRIGHT: Real Time Logic LLC, 2014
wini 0:e0adec41ad6b 18 *
wini 0:e0adec41ad6b 19 * This software is copyrighted by and is the sole property of Real
wini 0:e0adec41ad6b 20 * Time Logic LLC. All rights, title, ownership, or other interests in
wini 0:e0adec41ad6b 21 * the software remain the property of Real Time Logic LLC. This
wini 0:e0adec41ad6b 22 * software may only be used in accordance with the terms and
wini 0:e0adec41ad6b 23 * conditions stipulated in the corresponding license agreement under
wini 0:e0adec41ad6b 24 * which the software has been supplied. Any unauthorized use,
wini 0:e0adec41ad6b 25 * duplication, transmission, distribution, or disclosure of this
wini 0:e0adec41ad6b 26 * software is expressly forbidden.
wini 0:e0adec41ad6b 27 *
wini 0:e0adec41ad6b 28 * This Copyright notice may not be removed or modified without prior
wini 0:e0adec41ad6b 29 * written consent of Real Time Logic LLC.
wini 0:e0adec41ad6b 30 *
wini 0:e0adec41ad6b 31 * Real Time Logic LLC. reserves the right to modify this software
wini 0:e0adec41ad6b 32 * without notice.
wini 0:e0adec41ad6b 33 *
wini 0:e0adec41ad6b 34 * http://sharkssl.com
wini 0:e0adec41ad6b 35 ****************************************************************************
wini 0:e0adec41ad6b 36 *
wini 0:e0adec41ad6b 37 */
wini 0:e0adec41ad6b 38
wini 0:e0adec41ad6b 39 #ifndef __SharkMQ_h
wini 0:e0adec41ad6b 40 #define __SharkMQ_h
wini 0:e0adec41ad6b 41
wini 0:e0adec41ad6b 42 #include "selib.h"
wini 0:e0adec41ad6b 43
wini 0:e0adec41ad6b 44 /** @addtogroup SMQLib
wini 0:e0adec41ad6b 45 @{
wini 0:e0adec41ad6b 46 */
wini 0:e0adec41ad6b 47
wini 0:e0adec41ad6b 48 /** \defgroup SharkMQErrorCodes Error codes returned by function SharkMQ_getMessage
wini 0:e0adec41ad6b 49 \ingroup SharkMQ
wini 0:e0adec41ad6b 50 \anchor SharkMQErrorCodes Error codes returned by function #SharkMQ_getMessage
wini 0:e0adec41ad6b 51 @{
wini 0:e0adec41ad6b 52 */
wini 0:e0adec41ad6b 53
wini 0:e0adec41ad6b 54 /** The buffer provided in SharkMQ_constructor is not sufficiently large.
wini 0:e0adec41ad6b 55 */
wini 0:e0adec41ad6b 56 #define SMQE_BUF_OVERFLOW -10000
wini 0:e0adec41ad6b 57
wini 0:e0adec41ad6b 58 /** The URL provided is invalid.
wini 0:e0adec41ad6b 59 */
wini 0:e0adec41ad6b 60 #define SMQE_INVALID_URL -10002
wini 0:e0adec41ad6b 61
wini 0:e0adec41ad6b 62 /** TCP connection error
wini 0:e0adec41ad6b 63 */
wini 0:e0adec41ad6b 64 #define SMQE_PROTOCOL_ERROR -10003
wini 0:e0adec41ad6b 65
wini 0:e0adec41ad6b 66 /** Server sent a disconnect message
wini 0:e0adec41ad6b 67 */
wini 0:e0adec41ad6b 68 #define SMQE_DISCONNECT -10004
wini 0:e0adec41ad6b 69
wini 0:e0adec41ad6b 70
wini 0:e0adec41ad6b 71 /** No PONG response to PING: timeout
wini 0:e0adec41ad6b 72 */
wini 0:e0adec41ad6b 73 #define SMQE_PONGTIMEOUT -10005
wini 0:e0adec41ad6b 74
wini 0:e0adec41ad6b 75
wini 0:e0adec41ad6b 76 /** The SharkMQ_getMessage call timed out.
wini 0:e0adec41ad6b 77 */
wini 0:e0adec41ad6b 78 #define SMQE_TIMEOUT -10100
wini 0:e0adec41ad6b 79
wini 0:e0adec41ad6b 80
wini 0:e0adec41ad6b 81 /** @} */ /* end SharkMQErrorCodes */
wini 0:e0adec41ad6b 82
wini 0:e0adec41ad6b 83
wini 0:e0adec41ad6b 84 /** \defgroup SharkMQRespCodes Response codes returned by function SharkMQ_getMessage
wini 0:e0adec41ad6b 85 \ingroup SharkMQ
wini 0:e0adec41ad6b 86 \anchor SharkMQRespCodes Response codes returned by function #SharkMQ_getMessage
wini 0:e0adec41ad6b 87 @{
wini 0:e0adec41ad6b 88 */
wini 0:e0adec41ad6b 89
wini 0:e0adec41ad6b 90 /** Asynchronous #SharkMQ_subscribe response message received via
wini 0:e0adec41ad6b 91 #SharkMQ_getMessage.
wini 0:e0adec41ad6b 92
wini 0:e0adec41ad6b 93 \li SharkMQ::ptid is set to the subscribed Topic ID.
wini 0:e0adec41ad6b 94 \li SharkMQ::status is set to zero (0) if the request was accepted and
wini 0:e0adec41ad6b 95 a negative value if the request was denied.
wini 0:e0adec41ad6b 96 \li the 'msg' out parameter in #SharkMQ_getMessage is set to the optional
wini 0:e0adec41ad6b 97 server's authentication response message if the request was
wini 0:e0adec41ad6b 98 denied.
wini 0:e0adec41ad6b 99 */
wini 0:e0adec41ad6b 100 #define SMQ_SUBACK -20000
wini 0:e0adec41ad6b 101
wini 0:e0adec41ad6b 102 /** Asynchronous #SharkMQ_create response message received via
wini 0:e0adec41ad6b 103 #SharkMQ_getMessage.
wini 0:e0adec41ad6b 104
wini 0:e0adec41ad6b 105 \li SharkMQ::ptid is set to the created Topic ID.
wini 0:e0adec41ad6b 106 \li SharkMQ::status is set to zero (0) if the request was accepted and
wini 0:e0adec41ad6b 107 a negative value if the request was denied.
wini 0:e0adec41ad6b 108 \li the 'msg' out parameter in #SharkMQ_getMessage is set to the optional
wini 0:e0adec41ad6b 109 server's authentication response message if the request was
wini 0:e0adec41ad6b 110 denied.
wini 0:e0adec41ad6b 111 */
wini 0:e0adec41ad6b 112 #define SMQ_CREATEACK -20001
wini 0:e0adec41ad6b 113
wini 0:e0adec41ad6b 114 /** Asynchronous #SharkMQ_createsub response message received via
wini 0:e0adec41ad6b 115 #SharkMQ_getMessage.
wini 0:e0adec41ad6b 116
wini 0:e0adec41ad6b 117 \li SharkMQ::ptid is set to the created Sub Topic ID.
wini 0:e0adec41ad6b 118 \li SharkMQ::status is set to zero (0) if the request was accepted and
wini 0:e0adec41ad6b 119 a negative value if the request was denied.
wini 0:e0adec41ad6b 120 */
wini 0:e0adec41ad6b 121 #define SMQ_CREATESUBACK -20002
wini 0:e0adec41ad6b 122
wini 0:e0adec41ad6b 123 /** Change notification event (from observed tid). Observe events are
wini 0:e0adec41ad6b 124 * initiated via #SharkMQ_observe.
wini 0:e0adec41ad6b 125
wini 0:e0adec41ad6b 126 \li SharkMQ::ptid is set to the observed Topic ID.
wini 0:e0adec41ad6b 127 \li SharkMQ::status is set to the number of clients subscribed to the topic.
wini 0:e0adec41ad6b 128 */
wini 0:e0adec41ad6b 129 #define SMQ_SUBCHANGE -20003
wini 0:e0adec41ad6b 130
wini 0:e0adec41ad6b 131 /** @} */ /* end SharkMQRespCodes */
wini 0:e0adec41ad6b 132
wini 0:e0adec41ad6b 133
wini 0:e0adec41ad6b 134 #define SMQSTR(str) str, (sizeof(str)-1)
wini 0:e0adec41ad6b 135
wini 0:e0adec41ad6b 136 /** SharkMQ structure.
wini 0:e0adec41ad6b 137 */
wini 0:e0adec41ad6b 138 typedef struct
wini 0:e0adec41ad6b 139 {
wini 0:e0adec41ad6b 140 SOCKET sock;
wini 0:e0adec41ad6b 141 SharkSslCon* scon;
wini 0:e0adec41ad6b 142
wini 0:e0adec41ad6b 143 U8* sharkBuf; /* SharkSSL read buffer is set when we have data from Shark */
wini 0:e0adec41ad6b 144 U16 sharkBufLen; /* Received payload len */
wini 0:e0adec41ad6b 145 U16 sharkBufIx; /* Current read index in sharkBuf */
wini 0:e0adec41ad6b 146
wini 0:e0adec41ad6b 147 U8* recBuf; /*Buffer provided by the application and set in the constructor*/
wini 0:e0adec41ad6b 148 /* 'buf' is managed internally and is either the internal Shark
wini 0:e0adec41ad6b 149 recv-buf or (recBuf).
wini 0:e0adec41ad6b 150 */
wini 0:e0adec41ad6b 151 U8* buf; /**< The buffer provides an [out] param for a few methods. */
wini 0:e0adec41ad6b 152
wini 0:e0adec41ad6b 153 /** Timeout in milliseconds to wait in functions waiting for server
wini 0:e0adec41ad6b 154 data
wini 0:e0adec41ad6b 155 */
wini 0:e0adec41ad6b 156 U32 timeout;
wini 0:e0adec41ad6b 157 S32 pingTmoCounter,pingTmo;
wini 0:e0adec41ad6b 158 U32 clientTid; /**< Client's unique topic ID */
wini 0:e0adec41ad6b 159 U32 tid; /**< Topic: set when receiving MSG_PUBLISH from broker */
wini 0:e0adec41ad6b 160 U32 ptid; /**< Publisher's tid: Set when receiving MSG_PUBLISH from broker */
wini 0:e0adec41ad6b 161 U32 subtid; /**< Sub-tid: set when receiving MSG_PUBLISH from broker */
wini 0:e0adec41ad6b 162 int status; /**< Last known error code */
wini 0:e0adec41ad6b 163 U16 recBufLen;
wini 0:e0adec41ad6b 164 U16 sendBufIx;
wini 0:e0adec41ad6b 165 U16 frameLen; /**< The SimpleMQ frame size for the incomming data */
wini 0:e0adec41ad6b 166 /** Read frame data using SharkMQ_getMessage until: frameLen-bytesRead = 0 */
wini 0:e0adec41ad6b 167 U16 bytesRead;
wini 0:e0adec41ad6b 168 } SharkMQ;
wini 0:e0adec41ad6b 169
wini 0:e0adec41ad6b 170 /** Create a SimpleMQ client instance.
wini 0:e0adec41ad6b 171 \param o Uninitialized data of size sizeof(SharkMQ).
wini 0:e0adec41ad6b 172 \param buf is used for internal management and must not be less
wini 0:e0adec41ad6b 173 than 127 bytes and not smaller than the largest control
wini 0:e0adec41ad6b 174 frame. Function SharkMQ_getMessage will return #SMQE_BUF_OVERFLOW if
wini 0:e0adec41ad6b 175 the buffer is not sufficiently large.
wini 0:e0adec41ad6b 176 \param bufLen buffer length.
wini 0:e0adec41ad6b 177 */
wini 0:e0adec41ad6b 178 void SharkMQ_constructor(SharkMQ* o, U8* buf, U16 bufLen);
wini 0:e0adec41ad6b 179
wini 0:e0adec41ad6b 180 /** Bare metal configuration. This macro must be called immediately
wini 0:e0adec41ad6b 181 after calling the constructor on bare metal systems.
wini 0:e0adec41ad6b 182 \param o the #SharkMQ instance.
wini 0:e0adec41ad6b 183 \param ctx an #SeCtx instance.
wini 0:e0adec41ad6b 184 */
wini 0:e0adec41ad6b 185 #define SharkMQ_setCtx(o, ctx) SOCKET_constructor(&(o)->sock, ctx)
wini 0:e0adec41ad6b 186
wini 0:e0adec41ad6b 187 /** Initiate the SharkMQ server connection. The connection phase is
wini 0:e0adec41ad6b 188 divided into two steps: (1) initiating and (2) connecting via
wini 0:e0adec41ad6b 189 SharkMQ_connect.
wini 0:e0adec41ad6b 190 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 191 \param scon SharkSslCon instance created by calling #SharkSsl_createCon.
wini 0:e0adec41ad6b 192 \param url is a URL that starts with http:// and this URL
wini 0:e0adec41ad6b 193 must be to a server resource that initiates a SimpleMQ connection.
wini 0:e0adec41ad6b 194 \param rnd (out param) a random number created by the server. This
wini 0:e0adec41ad6b 195 number can be used for securing hash based password encryption.
wini 0:e0adec41ad6b 196 \return
wini 0:e0adec41ad6b 197
wini 0:e0adec41ad6b 198 - The return value is #SharkSslConTrust for any return value
wini 0:e0adec41ad6b 199 greater than zero.
wini 0:e0adec41ad6b 200 - A negative return value is one of: an error code from #se_connect, or
wini 0:e0adec41ad6b 201 a [SimpleMQ error code](\ref SharkMQErrorCodes).
wini 0:e0adec41ad6b 202
wini 0:e0adec41ad6b 203 A return value greater than zero means that a connection is
wini 0:e0adec41ad6b 204 established, but the connection is not trusted unless the return
wini 0:e0adec41ad6b 205 value is #SharkSslConTrust_CertCn.
wini 0:e0adec41ad6b 206
wini 0:e0adec41ad6b 207 On success, SharkMQ::buf is set to the IP address of the client as
wini 0:e0adec41ad6b 208 seen by the broker.
wini 0:e0adec41ad6b 209 */
wini 0:e0adec41ad6b 210 int SharkMQ_init(SharkMQ* o, SharkSslCon* scon, const char* url, U32* rnd);
wini 0:e0adec41ad6b 211
wini 0:e0adec41ad6b 212 /** Connect/establish a persistent SimpleMQ connection. The connection
wini 0:e0adec41ad6b 213 phase is divided into two steps: (1) initiating via SharkMQ_init and (2)
wini 0:e0adec41ad6b 214 connecting.
wini 0:e0adec41ad6b 215 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 216 \param uid a universally unique client identifier (uid) must be
wini 0:e0adec41ad6b 217 unique across all clients connecting to the same broker
wini 0:e0adec41ad6b 218 instance. The uid is preferably a stringified version of the
wini 0:e0adec41ad6b 219 client's Ethernet MAC address.
wini 0:e0adec41ad6b 220 \param uidLen the uid length.
wini 0:e0adec41ad6b 221 \param credentials provide credentials if required by the broker instance.
wini 0:e0adec41ad6b 222 \param credLen credentials length.
wini 0:e0adec41ad6b 223 \param info a string that provides information to optional server
wini 0:e0adec41ad6b 224 code interacting with the broker. This string is also passed into
wini 0:e0adec41ad6b 225 the optional broker's authentication callback function.
wini 0:e0adec41ad6b 226 \param infoLen length of info.
wini 0:e0adec41ad6b 227 \returns 0 on success, error code from TCP/IP stack,
wini 0:e0adec41ad6b 228 [SimpleMQ error code](\ref SharkMQErrorCodes), or one of the
wini 0:e0adec41ad6b 229 following error codes from the broker:
wini 0:e0adec41ad6b 230
wini 0:e0adec41ad6b 231 \li 0x01 Connection Refused: unacceptable protocol version
wini 0:e0adec41ad6b 232 \li 0x02 Connection Refused: server unavailable
wini 0:e0adec41ad6b 233 \li 0x03 Connection Refused: Incorrect credentials
wini 0:e0adec41ad6b 234 \li 0x04 Connection Refused: Client certificate required
wini 0:e0adec41ad6b 235 \li 0x05 Connection Refused: Client certificate not accepted
wini 0:e0adec41ad6b 236 \li 0x06 Connection Refused: Access denied
wini 0:e0adec41ad6b 237
wini 0:e0adec41ad6b 238 The broker may optionally send a human readable string in addition
wini 0:e0adec41ad6b 239 to the above broker produced error codes. This string is avaiable
wini 0:e0adec41ad6b 240 via SharkMQ::buf.
wini 0:e0adec41ad6b 241 */
wini 0:e0adec41ad6b 242 int SharkMQ_connect(SharkMQ* o, const char* uid, int uidLen,
wini 0:e0adec41ad6b 243 const char* credentials, U8 credLen,
wini 0:e0adec41ad6b 244 const char* info, int infoLen);
wini 0:e0adec41ad6b 245
wini 0:e0adec41ad6b 246
wini 0:e0adec41ad6b 247 /** Gracefully close the connection. You cannot publish any messages
wini 0:e0adec41ad6b 248 after calling this method.
wini 0:e0adec41ad6b 249 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 250 */
wini 0:e0adec41ad6b 251 void SharkMQ_disconnect(SharkMQ* o);
wini 0:e0adec41ad6b 252
wini 0:e0adec41ad6b 253
wini 0:e0adec41ad6b 254 /** Terminate a SimpleMQ instance.
wini 0:e0adec41ad6b 255 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 256 */
wini 0:e0adec41ad6b 257 void SharkMQ_destructor(SharkMQ* o);
wini 0:e0adec41ad6b 258
wini 0:e0adec41ad6b 259
wini 0:e0adec41ad6b 260 /** Create a topic an fetch the topic ID (tid). The SharkMQ protocol is
wini 0:e0adec41ad6b 261 optimized and does not directly use a string when publishing, but a
wini 0:e0adec41ad6b 262 number. The server randomly a creates 32 bit number and
wini 0:e0adec41ad6b 263 persistently stores the topic name and number.
wini 0:e0adec41ad6b 264
wini 0:e0adec41ad6b 265 The response to SharkMQ_create is asynchronous and returned as status
wini 0:e0adec41ad6b 266 #SMQ_CREATEACK via #SharkMQ_getMessage.
wini 0:e0adec41ad6b 267
wini 0:e0adec41ad6b 268 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 269 \param topic the topic name where you plan on publishing messages.
wini 0:e0adec41ad6b 270 */
wini 0:e0adec41ad6b 271 int SharkMQ_create(SharkMQ* o, const char* topic);
wini 0:e0adec41ad6b 272
wini 0:e0adec41ad6b 273
wini 0:e0adec41ad6b 274 /** Create a sub-topic and fetch the subtopic ID.
wini 0:e0adec41ad6b 275
wini 0:e0adec41ad6b 276 The response to SharkMQ_subscribe is asynchronous and returned as status
wini 0:e0adec41ad6b 277 #SMQ_CREATESUBACK via #SharkMQ_getMessage.
wini 0:e0adec41ad6b 278
wini 0:e0adec41ad6b 279 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 280 \param subtopic the sub-topic name you want registered.
wini 0:e0adec41ad6b 281 */
wini 0:e0adec41ad6b 282 int SharkMQ_createsub(SharkMQ* o, const char* subtopic);
wini 0:e0adec41ad6b 283
wini 0:e0adec41ad6b 284
wini 0:e0adec41ad6b 285 /** Subscribe to topic.
wini 0:e0adec41ad6b 286
wini 0:e0adec41ad6b 287 The response to SharkMQ_subscribe is asynchronous and returned as status
wini 0:e0adec41ad6b 288 #SMQ_SUBACK via #SharkMQ_getMessage.
wini 0:e0adec41ad6b 289
wini 0:e0adec41ad6b 290 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 291 \param topic the topic name to subscribe to.
wini 0:e0adec41ad6b 292 */
wini 0:e0adec41ad6b 293 int SharkMQ_subscribe(SharkMQ* o, const char* topic);
wini 0:e0adec41ad6b 294
wini 0:e0adec41ad6b 295
wini 0:e0adec41ad6b 296 /** Requests the broker to unsubscribe the client from a topic.
wini 0:e0adec41ad6b 297 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 298 \param tid the topic name's Topic ID.
wini 0:e0adec41ad6b 299 */
wini 0:e0adec41ad6b 300 int SharkMQ_unsubscribe(SharkMQ* o, U32 tid);
wini 0:e0adec41ad6b 301
wini 0:e0adec41ad6b 302
wini 0:e0adec41ad6b 303 /** Publish messages to a topic and optionally to a sub-topic. Topic
wini 0:e0adec41ad6b 304 name must have previosly been been resolved by #SharkMQ_create and
wini 0:e0adec41ad6b 305 sub-topic should preferably have been created by #SharkMQ_createsub.
wini 0:e0adec41ad6b 306 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 307 \param data message payload.
wini 0:e0adec41ad6b 308 \param len payload length.
wini 0:e0adec41ad6b 309 \param tid the topic ID (created with SharkMQ_create).
wini 0:e0adec41ad6b 310 \param subtid optional sub-topic ID preferably created with SharkMQ_createsub.
wini 0:e0adec41ad6b 311 */
wini 0:e0adec41ad6b 312 int SharkMQ_publish(SharkMQ* o, const void* data, int len, U32 tid, U32 subtid);
wini 0:e0adec41ad6b 313
wini 0:e0adec41ad6b 314
wini 0:e0adec41ad6b 315 /** Publish a message in chunks and request the broker to assemble the
wini 0:e0adec41ad6b 316 message before publishing to the subscriber(s). This method uses
wini 0:e0adec41ad6b 317 the internal SharkSSL send buffer and sends the message as a chunk
wini 0:e0adec41ad6b 318 when the internal buffer is full, thus sending the message as an
wini 0:e0adec41ad6b 319 incomplete message to the broker. The message is assembled by the
wini 0:e0adec41ad6b 320 broker when you flush the remaining bytes in the buffer by calling
wini 0:e0adec41ad6b 321 #SharkMQ_pubflush.
wini 0:e0adec41ad6b 322
wini 0:e0adec41ad6b 323 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 324 \param str a string.
wini 0:e0adec41ad6b 325 */
wini 0:e0adec41ad6b 326 int SharkMQ_wrtstr(SharkMQ* o, const char* str);
wini 0:e0adec41ad6b 327
wini 0:e0adec41ad6b 328 /** Publish a message in chunks and request the broker to assemble the
wini 0:e0adec41ad6b 329 message before publishing to the subscriber(s). This method uses
wini 0:e0adec41ad6b 330 the internal SharkSSL send buffer and sends the message as a chunk
wini 0:e0adec41ad6b 331 when the internal buffer is full, thus sending the message as an
wini 0:e0adec41ad6b 332 incomplete message to the broker. The message is assembled by the
wini 0:e0adec41ad6b 333 broker when you flush the remaining bytes in the buffer by calling
wini 0:e0adec41ad6b 334 #SharkMQ_pubflush.
wini 0:e0adec41ad6b 335
wini 0:e0adec41ad6b 336
wini 0:e0adec41ad6b 337 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 338 \param data message payload.
wini 0:e0adec41ad6b 339 \param len payload length.
wini 0:e0adec41ad6b 340 */
wini 0:e0adec41ad6b 341 int SharkMQ_write(SharkMQ* o, const void* data, int len);
wini 0:e0adec41ad6b 342
wini 0:e0adec41ad6b 343 /** Flush the internal buffer and request the broker to assemble all
wini 0:e0adec41ad6b 344 stored fragments as one message. This message is then published to
wini 0:e0adec41ad6b 345 topic 'tid', and sub-topic 'subtid'.
wini 0:e0adec41ad6b 346
wini 0:e0adec41ad6b 347 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 348 \param tid the topic ID (created with SharkMQ_create).
wini 0:e0adec41ad6b 349 \param subtid optional sub-topic ID preferably created with SharkMQ_createsub.
wini 0:e0adec41ad6b 350
wini 0:e0adec41ad6b 351 Example:
wini 0:e0adec41ad6b 352 \code
wini 0:e0adec41ad6b 353 SharkMQ_wrtstr(smq, "Hello");
wini 0:e0adec41ad6b 354 SharkMQ_wrtstr(smq, " ");
wini 0:e0adec41ad6b 355 SharkMQ_wrtstr(smq, "World");
wini 0:e0adec41ad6b 356 SharkMQ_pubflush(smq,tid,subtid);
wini 0:e0adec41ad6b 357 \endcode
wini 0:e0adec41ad6b 358
wini 0:e0adec41ad6b 359 */
wini 0:e0adec41ad6b 360 int SharkMQ_pubflush(SharkMQ* o, U32 tid, U32 subtid);
wini 0:e0adec41ad6b 361
wini 0:e0adec41ad6b 362
wini 0:e0adec41ad6b 363 /** Request the broker to provide change notification events when the
wini 0:e0adec41ad6b 364 number of subscribers to a specific topic changes. Ephemeral topic
wini 0:e0adec41ad6b 365 IDs can also be observed. The number of connected subscribers for
wini 0:e0adec41ad6b 366 an ephemeral ID can only be one, which means the client is
wini 0:e0adec41ad6b 367 connected. Receiving a change notification for an ephemeral ID
wini 0:e0adec41ad6b 368 means the client has disconnected and that you no longer will get
wini 0:e0adec41ad6b 369 any change notifications for the observed topic ID.
wini 0:e0adec41ad6b 370
wini 0:e0adec41ad6b 371 Change notification events are received as #SMQ_SUBCHANGE via
wini 0:e0adec41ad6b 372 #SharkMQ_getMessage.
wini 0:e0adec41ad6b 373
wini 0:e0adec41ad6b 374 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 375 \param tid the Topic ID you which to observe.
wini 0:e0adec41ad6b 376 */
wini 0:e0adec41ad6b 377 int SharkMQ_observe(SharkMQ* o, U32 tid);
wini 0:e0adec41ad6b 378
wini 0:e0adec41ad6b 379
wini 0:e0adec41ad6b 380 /** Stop receiving change notifications for a topic ID or ephemeral topic ID.
wini 0:e0adec41ad6b 381 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 382 \param tid the Topic ID you no longer want to observe.
wini 0:e0adec41ad6b 383 */
wini 0:e0adec41ad6b 384 int SharkMQ_unobserve(SharkMQ* o, U32 tid);
wini 0:e0adec41ad6b 385
wini 0:e0adec41ad6b 386
wini 0:e0adec41ad6b 387 /** Wait for messages sent from the broker.
wini 0:e0adec41ad6b 388 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 389 \param msg a pointer to the response data (out param)
wini 0:e0adec41ad6b 390 \returns
wini 0:e0adec41ad6b 391 \li a negative value signals an
wini 0:e0adec41ad6b 392 [error code](\ref SharkMQErrorCodes) or an
wini 0:e0adec41ad6b 393 [asynchronous response code](\ref SharkMQRespCodes).
wini 0:e0adec41ad6b 394 \li zero signals timeout.
wini 0:e0adec41ad6b 395 \li a value greater than zero signals the reception of a full
wini 0:e0adec41ad6b 396 message or a message fragment. See receiving large frames for details.
wini 0:e0adec41ad6b 397
wini 0:e0adec41ad6b 398 <b>Receiving large frames:</b><br>
wini 0:e0adec41ad6b 399 The SimpleMQ protocol is frame based, but the function can return
wini 0:e0adec41ad6b 400 a fragment before the complete SimpleMQ frame is received if the
wini 0:e0adec41ad6b 401 frame sent by the peer is larger than the provided buffer. The
wini 0:e0adec41ad6b 402 frame length is returned in SharkMQ::frameLen and the data consumed
wini 0:e0adec41ad6b 403 thus far is returned in SharkMQ::bytesRead. The complete frame is
wini 0:e0adec41ad6b 404 consumed when frameLen == bytesRead.
wini 0:e0adec41ad6b 405
wini 0:e0adec41ad6b 406 <b>Note:</b> the default timeout value is set to one minute. You
wini 0:e0adec41ad6b 407 can set the timeout value by setting SharkMQ::timeout to the
wini 0:e0adec41ad6b 408 number of milliseconds you want to wait for incoming messages
wini 0:e0adec41ad6b 409 before the timeout triggers. Note: Setting a long timeout may
wini 0:e0adec41ad6b 410 interfere with the built in PING timer.
wini 0:e0adec41ad6b 411 */
wini 0:e0adec41ad6b 412 int SharkMQ_getMessage(SharkMQ* o, U8** msg);
wini 0:e0adec41ad6b 413
wini 0:e0adec41ad6b 414
wini 0:e0adec41ad6b 415 /** Returns the message size, which is SharkMQ::frameLen - 15.
wini 0:e0adec41ad6b 416 \param o the SharkMQ instance.
wini 0:e0adec41ad6b 417 */
wini 0:e0adec41ad6b 418 #define SMQ_getMsgSize(o)
wini 0:e0adec41ad6b 419
wini 0:e0adec41ad6b 420 /** @} */ /* end group SMQLib */
wini 0:e0adec41ad6b 421
wini 0:e0adec41ad6b 422 #endif