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
	Error codes returned by function SharkMQTT_getMessage

	Response 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

o	SharkMQTT instance

◆ SharkMQTT_msgConsumed

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

Read packet data using SharkMQTT_getMessage until SharkMQTT_msgConsumed returns TRUE.

Parameters

o	SharkMQTT 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

o	SharkMQTT 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

o	SharkMQTT instance
topic	the topic name
msg	message payload.
msgLen	payload 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

o	SharkMQTT 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

o	SharkMQTT 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

o	SharkMQTT 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

o	the SharkMQ instance.
ctx	an 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

o	SharkMQTT 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

o	SharkMQTT instance

◆ SharkMQTT_trustInfo

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

Returns SharkSslConTrust when SharkMQTT_connect returns SMQTTE_SERVERNOTTRUSTED.

Parameters

o	SharkMQTT 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

o	SharkMQTT instance
scon	SharkSslCon instance created by calling SharkSsl_createCon.
address	the MQTT broker address
port	the MQTT broker listen port number (typically 8883)
clientId	a unique ID [MQTT-3.1.3.1]
cred	optional credentials
cleanSession
wm	optional 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

o	Uninitialized data of size sizeof(SharkMQTT).
buf	is 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.
bufLen	buffer length.

◆ SharkMQTT_destructor()

void SharkMQTT_destructor ( SharkMQTT * o )

Terminate a SharkMQTT instance.

Parameters

o	SharkMQTT instance

◆ SharkMQTT_disconnect()

void SharkMQTT_disconnect ( SharkMQTT * o )

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

Parameters

o	SharkMQTT instance

◆ SharkMQTT_getMessage()

int SharkMQTT_getMessage	(	SharkMQTT *	o,
		U8 **	msg
	)

Wait for messages sent from the broker.

Parameters

o	SharkMQTT instance
msg	a 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

o	SharkMQTT instance
topic	the topic name
msg	message payload. This pointer is set to NULL when used together with function SharkMQTT_zeroCopyPub.
msgLen	payload length.
retain	flag is set to TRUE or FALSE [MQTT-3.3.1.3]
qos	Quality 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

o	SharkMQTT instance
topic	the topic name to subscribe to.
qos	Maximum 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.
packetId	optional 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

o	SharkMQTT instance
topic	the topic name to unsubscribe from.
packetId	optional 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

o	SharkMQTT instance
topic	must match topic passed into function SharkMQTT_publish
qos	must also match
maxMsgLen	is 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.

Detailed Description

Modules

Data Structures

Macros

Functions

Macro Definition Documentation

◆ SharkMQTT_connackCode

◆ SharkMQTT_dup

◆ SharkMQTT_msgConsumed

◆ SharkMQTT_packetId

◆ SharkMQTT_pub0

◆ SharkMQTT_QOS

◆ SharkMQTT_retain

◆ SharkMQTT_sessionPresent

◆ SharkMQTT_setCtx

◆ SharkMQTT_subAckCode

◆ SharkMQTT_topic

◆ SharkMQTT_trustInfo

Function Documentation

◆ SharkMQTT_connect()

◆ SharkMQTT_constructor()

◆ SharkMQTT_destructor()

◆ SharkMQTT_disconnect()

◆ SharkMQTT_getMessage()

◆ SharkMQTT_publish()

◆ SharkMQTT_subscribe()

◆ SharkMQTT_unsubscribe()

◆ SharkMQTT_zeroCopyPub()