SharkSSL™ Embedded SSL/TLS Stack

Detailed Description

A secure MQTT client designed for SharkSSL.

SharkMQTT is an extremely compact and secure MQTT client library optimized for memory constrained embedded systems. The MQTT stack is for this reason limited to message sizes less than 16384 bytes.

Modules

 Error codes returned by function SharkMQTT_getMessage
 
 Response codes returned by function SharkMQTT_getMessage
 

Data Structures

struct  MqttWillMsg
 Optional MQTT Will Message; used when calling function SharkMQTT_connect. More...
 
struct  MqttCredentials
 Optional credentials used when calling function SharkMQTT_connect. More...
 
struct  SharkMQTT
 SharkMQTT structure. More...
 

Macros

#define SharkMQTT_setCtx(o, ctx)   SOCKET_constructor(&(o)->sock, ctx)
 Bare metal configuration. More...
 
#define SharkMQTT_msgConsumed(o)   (((o)->packetLen - (o)->bytesRead) == 0)
 Read packet data using SharkMQTT_getMessage until SharkMQTT_msgConsumed returns TRUE. More...
 
#define SharkMQTT_connackCode(o)   (o)->recPackHeader[3]
 Connection response (CONNACK) return code. More...
 
#define SharkMQTT_sessionPresent(o)   ((o)->recPackHeader[2] & 1)
 Returns TRUE if a session is restored. More...
 
#define SharkMQTT_trustInfo(o)   ((SharkSslConTrust)(o)->packetLen)
 Returns SharkSslConTrust when SharkMQTT_connect returns SMQTTE_SERVERNOTTRUSTED. More...
 
#define SharkMQTT_pub0(o, topic, msg, msgLen)   SharkMQTT_publish(o, topic, msg, msgLen, FALSE, 0)
 Publish a QOS 0 message and set the retain flag to FALSE. More...
 
#define SharkMQTT_packetId(o)   (o)->recPacketId
 Returns packetId when the return value from SharkMQTT_getMessage is SMQTT_SUBACK or SMQTT_UNSUBACK. More...
 
#define SharkMQTT_subAckCode(o)   ((U16)(o)->recPackHeader[4])
 Returns the subscribe response code when the return value from SharkMQTT_getMessage is SMQTT_SUBACK. More...
 
#define SharkMQTT_dup(o)   (((o)->recPackHeader[0] & 8) ? TRUE : FALSE)
 Returns the dup flag (TRUE/FALSE) [MQTT-3.3.1.1] for received PUBLISH messages i.e. More...
 
#define SharkMQTT_QOS(o)   (((o)->recPackHeader[0] >> 1) & 3)
 Returns QOS (0, 1, or 2) [MQTT-3.3.1.2] for received PUBLISH messages i.e. More...
 
#define SharkMQTT_retain(o)   ((o)->recPackHeader[0] & 1)
 Returns the retain flag (TRUE/FALSE) [MQTT-3.3.1.3] for received PUBLISH messages i.e. More...
 
#define SharkMQTT_topic(o)   ((const char*)((o)->recPackHeader+1))
 Returns the topic name for received PUBLISH messages i.e. More...
 

Functions

void SharkMQTT_constructor (SharkMQTT *o, U8 *buf, U16 bufLen)
 Create a SharkMQTT client instance. More...
 
void SharkMQTT_destructor (SharkMQTT *o)
 Terminate a SharkMQTT instance. More...
 
int SharkMQTT_connect (SharkMQTT *o, SharkSslCon *scon, const char *address, U16 port, const char *clientId, MqttCredentials *cred, BaBool cleanSession, MqttWillMsg *wm)
 Establish (or re-establish) an MQTT session. More...
 
int SharkMQTT_subscribe (SharkMQTT *o, const char *topic, U8 qos, U16 *packetId)
 Subscribe to topic. More...
 
int SharkMQTT_unsubscribe (SharkMQTT *o, const char *topic, U16 *packetId)
 Requests the broker to unsubscribe the client from a topic. More...
 
U8 * SharkMQTT_zeroCopyPub (SharkMQTT *o, const char *topic, U8 qos, int *maxMsgLen)
 Prepare a zero copy publish by fetching the SharkSSL send buffer pointer and offset the pointer to the MQTT message payload. More...
 
int SharkMQTT_publish (SharkMQTT *o, const char *topic, const void *msg, int msgLen, U8 retain, U8 qos)
 Publish messages to a topic. More...
 
int SharkMQTT_getMessage (SharkMQTT *o, U8 **msg)
 Wait for messages sent from the broker. More...
 
void SharkMQTT_disconnect (SharkMQTT *o)
 Send a disconnect command to the broker and gracefully close the connection. More...
 

Macro Definition Documentation

◆ SharkMQTT_connackCode

#define SharkMQTT_connackCode (   o)    (o)->recPackHeader[3]

Connection response (CONNACK) return code.

This function should be called if SharkMQTT_connect returns SMQTTE_CONREFUSED.

Returns
one of the following codes:
  • 0x00 Connection Accepted
  • 0x01 Connection Refused, unacceptable protocol version
  • 0x02 Connection Refused, identifier rejected
  • 0x03 Connection Refused, Server unavailable
  • 0x04 Connection Refused, bad user name or password
  • 0x05 Connection Refused, not authorized

See [MQTT-3.2.2.3] for details.

◆ SharkMQTT_dup

#define SharkMQTT_dup (   o)    (((o)->recPackHeader[0] & 8) ? TRUE : FALSE)

Returns the dup flag (TRUE/FALSE) [MQTT-3.3.1.1] for received PUBLISH messages i.e.

when SharkMQTT_getMessage returns a value greater than zero.

Parameters
oSharkMQTT instance

◆ SharkMQTT_msgConsumed

#define SharkMQTT_msgConsumed (   o)    (((o)->packetLen - (o)->bytesRead) == 0)

Read packet data using SharkMQTT_getMessage until SharkMQTT_msgConsumed returns TRUE.

Parameters
oSharkMQTT instance

◆ SharkMQTT_packetId

#define SharkMQTT_packetId (   o)    (o)->recPacketId

Returns packetId when the return value from SharkMQTT_getMessage is SMQTT_SUBACK or SMQTT_UNSUBACK.

Parameters
oSharkMQTT instance

◆ SharkMQTT_pub0

#define SharkMQTT_pub0 (   o,
  topic,
  msg,
  msgLen 
)    SharkMQTT_publish(o, topic, msg, msgLen, FALSE, 0)

Publish a QOS 0 message and set the retain flag to FALSE.

Parameters
oSharkMQTT instance
topicthe topic name
msgmessage payload.
msgLenpayload length.
Returns
zero on success and a negative value on socket error.
See also
SharkMQTT_publish

◆ SharkMQTT_QOS

#define SharkMQTT_QOS (   o)    (((o)->recPackHeader[0] >> 1) & 3)

Returns QOS (0, 1, or 2) [MQTT-3.3.1.2] for received PUBLISH messages i.e.

when SharkMQTT_getMessage returns a value greater than zero.

Parameters
oSharkMQTT instance

◆ SharkMQTT_retain

#define SharkMQTT_retain (   o)    ((o)->recPackHeader[0] & 1)

Returns the retain flag (TRUE/FALSE) [MQTT-3.3.1.3] for received PUBLISH messages i.e.

when SharkMQTT_getMessage returns a value greater than zero.

Parameters
oSharkMQTT instance

◆ SharkMQTT_sessionPresent

#define SharkMQTT_sessionPresent (   o)    ((o)->recPackHeader[2] & 1)

Returns TRUE if a session is restored.

This function can only be used immediately after calling function SharkMQTT_connect.

See [MQTT-3.2.2.2] for details.

Parameters
oSharkMQTT instance
See also
argument cleanSession in function SharkMQTT_connect

◆ SharkMQTT_setCtx

#define SharkMQTT_setCtx (   o,
  ctx 
)    SOCKET_constructor(&(o)->sock, ctx)

Bare metal configuration.

This macro must be called immediately after calling the constructor on bare metal systems.

Parameters
othe SharkMQ instance.
ctxan SeCtx instance.

◆ SharkMQTT_subAckCode

#define SharkMQTT_subAckCode (   o)    ((U16)(o)->recPackHeader[4])

Returns the subscribe response code when the return value from SharkMQTT_getMessage is SMQTT_SUBACK.

Parameters
oSharkMQTT instance
Returns
  • 0x00: Success - Maximum QoS 0
  • 0x01: Success - Maximum QoS 1
  • 0x02: Success - Maximum QoS 2
  • 0x80: Failure

◆ SharkMQTT_topic

#define SharkMQTT_topic (   o)    ((const char*)((o)->recPackHeader+1))

Returns the topic name for received PUBLISH messages i.e.

when SharkMQTT_getMessage returns a value greater than zero.

Parameters
oSharkMQTT instance

◆ SharkMQTT_trustInfo

#define SharkMQTT_trustInfo (   o)    ((SharkSslConTrust)(o)->packetLen)

Returns SharkSslConTrust when SharkMQTT_connect returns SMQTTE_SERVERNOTTRUSTED.

Parameters
oSharkMQTT instance

Function Documentation

◆ SharkMQTT_connect()

int SharkMQTT_connect ( SharkMQTT o,
SharkSslCon scon,
const char *  address,
U16  port,
const char *  clientId,
MqttCredentials cred,
BaBool  cleanSession,
MqttWillMsg wm 
)

Establish (or re-establish) an MQTT session.

Parameters
oSharkMQTT instance
sconSharkSslCon instance created by calling SharkSsl_createCon.
addressthe MQTT broker address
portthe MQTT broker listen port number (typically 8883)
clientIda unique ID [MQTT-3.1.3.1]
credoptional credentials
cleanSession
wmoptional MQTT will message
Returns
a return value greater than zero means that a connection is established, but the connection is not trusted unless the return value is SharkSslConTrust_CertCn.

one of the following values on error.

Error codes -1 to -3 are error codes from se_connect

If SMQTTE_CONREFUSED is returned, the reason for the refused connection is found by calling SharkMQTT_connackCode.

See also
SharkMQTT_sessionPresent

◆ SharkMQTT_constructor()

void SharkMQTT_constructor ( SharkMQTT o,
U8 *  buf,
U16  bufLen 
)

Create a SharkMQTT client instance.

Parameters
oUninitialized data of size sizeof(SharkMQTT).
bufis used for internal management and must not be less than the size of the largest control message. Function SharkMQTT_getMessage will return SMQTTE_OVERFLOW if the buffer is not sufficiently large.
bufLenbuffer length.

◆ SharkMQTT_destructor()

void SharkMQTT_destructor ( SharkMQTT o)

Terminate a SharkMQTT instance.

Parameters
oSharkMQTT instance

◆ SharkMQTT_disconnect()

void SharkMQTT_disconnect ( SharkMQTT o)

Send a disconnect command to the broker and gracefully close the connection.

Parameters
oSharkMQTT instance

◆ SharkMQTT_getMessage()

int SharkMQTT_getMessage ( SharkMQTT o,
U8 **  msg 
)

Wait for messages sent from the broker.

Parameters
oSharkMQTT instance
msga pointer to the response data (out param)
Returns
  • a negative value signals an error code or an asynchronous response code.
  • a value greater than zero signals the reception of a full message or a message fragment. See receiving large packets for details.
Receiving large packets:
The MQTT protocol is frame based, but the function can return a fragment before the complete MQTT packet is received if the packet sent by the broker is larger than the SharkSSL buffer. The message payload length is returned in SharkMQTT::packetLen and the data consumed thus far is returned in SharkMQTT::bytesRead. The complete frame is consumed when SharkMQTT::packetLen == SharkMQTT::bytesRead. Function SharkMQTT_msgConsumed returns TRUE when the complete packet has been received.

Note: the default timeout value is set to one minute. You can set the timeout value by setting SharkMQTT::timeout to the number of milliseconds you want to wait for incoming messages before the timeout triggers. Note: Setting a long timeout may interfere with the built in PING timer.

◆ SharkMQTT_publish()

int SharkMQTT_publish ( SharkMQTT o,
const char *  topic,
const void *  msg,
int  msgLen,
U8  retain,
U8  qos 
)

Publish messages to a topic.

Messages with QOS 1 or 2 cannot be larger than the SharkSSL outbuf size.

Parameters
oSharkMQTT instance
topicthe topic name
msgmessage payload. This pointer is set to NULL when used together with function SharkMQTT_zeroCopyPub.
msgLenpayload length.
retainflag is set to TRUE or FALSE [MQTT-3.3.1.3]
qosQuality Of Zero is 0, 1, or 2. Note that SharkMQTT must dynamically allocate and keep messages with QOS 1 and 2 until the broker QOS handshaking has completed.
Returns
zero on success and a negative value on socket error.
See also
SharkMQTT_pub0

◆ SharkMQTT_subscribe()

int SharkMQTT_subscribe ( SharkMQTT o,
const char *  topic,
U8  qos,
U16 *  packetId 
)

Subscribe to topic.

The response to SharkMQ_subscribe is asynchronous and returned as status SMQTT_SUBACK via SharkMQTT_getMessage.

Parameters
oSharkMQTT instance
topicthe topic name to subscribe to.
qosMaximum Quality Of Zero on inbound messages can be set to 0, 1, or 2. Note that SharkMQTT must dynamically allocate and keep a small control structure for each received message with QOS 2. This structure is kept until the broker QOS 2 handshaking has completed.
packetIdoptional packet ID. The packetId can be matched when SharkMQ_getMessage returns SMQTT_SUBACK.
Returns
zero on success and a negative value on socket error.

◆ SharkMQTT_unsubscribe()

int SharkMQTT_unsubscribe ( SharkMQTT o,
const char *  topic,
U16 *  packetId 
)

Requests the broker to unsubscribe the client from a topic.

The response to SharkMQ_unsubscribe is asynchronous and returned as status SMQTT_UNSUBACK via SharkMQTT_getMessage.

Parameters
oSharkMQTT instance
topicthe topic name to unsubscribe from.
packetIdoptional packet ID. The packetId can be matched when SharkMQ_getMessage returns SMQTT_UNSUBACK.
Returns
zero on success and a negative value on socket error.

◆ SharkMQTT_zeroCopyPub()

U8* SharkMQTT_zeroCopyPub ( SharkMQTT o,
const char *  topic,
U8  qos,
int *  maxMsgLen 
)

Prepare a zero copy publish by fetching the SharkSSL send buffer pointer and offset the pointer to the MQTT message payload.

Parameters
oSharkMQTT instance
topicmust match topic passed into function SharkMQTT_publish
qosmust also match
maxMsgLenis an out value and indicates the maximum number of bytes that can be copied into the pointer return by this function. The length is the SharkSSL buffer's out buffer size - the MQTT header size.
Returns
a pointer to where you can copy the message.

Example:

int maxMsgLen;
U8* buf = SharkMQTT_zeroCopyPub(mqtt, "/message/", 1, &maxMsgLen);
strcpy(buf, "Hello World")
SharkMQTT_publish(mqtt, "/message/", NULL, strlen(buf), FALSE, 1);

Notice that the message pointer is set to NULL when calling SharkMQTT_publish.

SharkMQTT_publish
int SharkMQTT_publish(SharkMQTT *o, const char *topic, const void *msg, int msgLen, U8 retain, U8 qos)
Publish messages to a topic.
SharkMQTT_zeroCopyPub
U8 * SharkMQTT_zeroCopyPub(SharkMQTT *o, const char *topic, U8 qos, int *maxMsgLen)
Prepare a zero copy publish by fetching the SharkSSL send buffer pointer and offset the pointer to th...