Detailed Description

A secure SimpleMQ client designed for SharkSSL.

SimpleMQ is an easy to use IoT Message Queues architecture solution that follows the publish subscribe broadcast design pattern.

SharkMQ is a secure SimpleMQ client implementation delivered with SharkSSL standalone.

The SharkMQ C library comes with a C++ wrapper API, which includes a brief description of the API. See the C API for the full documentation.

Modules
	Error codes returned by function SharkMQ_getMessage
	Error codes returned by function SharkMQ_getMessage

	Response codes returned by function SharkMQ_getMessage
	Response codes returned by function SharkMQ_getMessage

	C API

Data Structures
struct	SharkMQ
	SharkMQ structure. More...

Macros
#define	SMQSTR(str) str, (sizeof(str)-1)

Typedefs
typedef struct SharkMQ	SharkMQ
	SharkMQ structure. More...

Functions
	SharkMQ::SharkMQ (U8 *buf, U16 bufLen)
	Create a secure SMQ client instance. More...

int	SharkMQ::init (SharkSslCon scon, const char url, U32 *rnd)
	Initiate the SMQ server connection. More...

int	SharkMQ::connect (const char uid, int uidLen, const char credentials, U8 credLen, const char *info, int infoLen, U16 maxTlsFrameSize)
	Connect/establish a persistent SMQ connection. More...

void	SharkMQ::disconnect ()
	Gracefully close the connection. More...

	SharkMQ::~SharkMQ ()
	Terminate an SMQ instance. More...

int	SharkMQ::create (const char *topic)
	Create a topic an fetch the topic ID (tid). More...

int	SharkMQ::createsub (const char *subtopic)
	Create a sub-topic and fetch the subtopic ID. More...

int	SharkMQ::subscribe (const char *topic)
	The response to SharkMQ_subscribe is asynchronous and returned as status SMQ_SUBACK via SharkMQ_getMessage. More...

int	SharkMQ::unsubscribe (U32 tid)
	Requests the broker to unsubscribe the server from a topic. More...

int	SharkMQ::publish (const void *data, int len, U32 tid, U32 subtid)
	Publish messages to a topic and optionally to a sub-topic. More...

int	SharkMQ::wrtstr (const char *str)
	Publish a message in chunks and request the broker to assemble the message before publishing to the subscriber(s). More...

int	SharkMQ::write (const void *data, int len)
	Publish a message in chunks and request the broker to assemble the message before publishing to the subscriber(s). More...

int	SharkMQ::pubflush (U32 tid, U32 subtid)
	Flush the internal buffer and request the broker to assemble all stored fragments as one message. More...

int	SharkMQ::observe (U32 tid)
	Request the broker to provide change notification events when the number of subscribers to a specific topic changes. More...

int	SharkMQ::unobserve (U32 tid)
	Stop receiving change notifications for a topic ID or ephemeral topic ID. More...

int	SharkMQ::getMessage (U8 **msg)
	Wait for messages sent from the broker. More...

int	SharkMQ::getMsgSize ()
	Returns the message size, which is SMQ::frameLen - 15. More...

Macro Definition Documentation

◆ SMQSTR

#define SMQSTR ( str ) str, (sizeof(str)-1)

Typedef Documentation

◆ SharkMQ

typedef struct SharkMQ SharkMQ

SharkMQ structure.

Function Documentation

◆ connect()

int SharkMQ::connect	(	const char *	uid,
		int	uidLen,
		const char *	credentials,
		U8	credLen,
		const char *	info,
		int	infoLen,
		U16	maxTlsFrameSize
	)

Connect/establish a persistent SMQ connection.

See also: SharkMQ_connect

Parameters

uid	const char *; required unique client ID bytes, borrowed for this call.
uidLen	int; ID length from 1 to 255 bytes.
credentials	const char *; credential bytes, required when credLen is nonzero.
credLen	U8; credential byte count.
info	const char *; optional information bytes for the broker, or NULL with infoLen=0.
infoLen	int; nonnegative information length. The complete CONNECT frame (8+uidLen+credLen+infoLen bytes) must fit the TLS send buffer.
maxTlsFrameSize	U16; requested maximum server TLS frame size in bytes, or zero for no requested limit.

Returns: int: 0 only for an accepted CONNECT. SMQ_TIMEOUT means call connect again to await CONNACK without resending; use bounded retries. Positive values are broker refusal codes; other negative values are transport/protocol errors.

◆ create()

int SharkMQ::create ( const char * topic )

Create a topic an fetch the topic ID (tid).

See also: SharkMQ_create

Parameters

topic const char *; required nonempty NUL-terminated name, borrowed for this call. Its bytes plus the 3-byte header must fit the TLS send buffer.

Returns: int: 0 when the request was sent; negative on failure. The broker response is asynchronous: process SMQ_CREATEACK from SharkMQ_getMessage; this return value is not a topic ID.

◆ createsub()

int SharkMQ::createsub ( const char * subtopic )

Create a sub-topic and fetch the subtopic ID.

See also: SMQ:createsub

Parameters

subtopic const char *; required nonempty NUL-terminated name, borrowed for this call. Its bytes plus the 3-byte header must fit the TLS send buffer.

Returns: int: 0 when the request was sent; negative on failure. The broker response is asynchronous: process SMQ_CREATESUBACK from SharkMQ_getMessage; this return value is not a topic ID.

◆ disconnect()

void SharkMQ::disconnect ( )

Gracefully close the connection.

See also: SharkMQ_disconnect

◆ getMessage()

int SharkMQ::getMessage ( U8 ** msg )

Wait for messages sent from the broker.

See also: SharkMQ_getMessage

Parameters

msg	U8 **; required output pointer. Payload bytes borrow the TLS/SMQ buffers and must be consumed before the next receive/connection operation.

Returns: int: positive payload byte count for this chunk; 0 for a continuation timeout or empty payload; SMQ_TIMEOUT for a frame-header timeout; other negative SMQ events or errors. Dispatch documented events separately from errors. Use getMsgSize and bytesRead to detect a complete message.

◆ getMsgSize()

int SharkMQ::getMsgSize ( )

Returns the message size, which is SMQ::frameLen - 15.

See also: SharkMQ_getMsgSize

Returns: int; complete current PUBLISH payload size in bytes (frameLen minus the 15-byte header), not the current receive-chunk size. Use only while processing a PUBLISH message.

◆ init()

int SharkMQ::init	(	SharkSslCon *	scon,
		const char *	url,
		U32 *	rnd
	)

Initiate the SMQ server connection.

See also: SharkMQ_init

Parameters

scon	SharkSslCon *; caller-owned client TLS connection, retained until disconnect/destruction; terminate it separately.
url	const char *; required NUL-terminated URL using the HTTPS scheme and including a path, borrowed for this call.
rnd	U32 *; optional output broker-provided random value, or NULL.

Returns: int: SharkSslConTrust_CertCnDate on successful TLS authentication and SMQ initialization; a negative socket/TLS/SMQ result otherwise. This does not yet complete the SMQ CONNECT exchange.

◆ observe()

int SharkMQ::observe ( U32 tid )

Request the broker to provide change notification events when the number of subscribers to a specific topic changes.

Ephemeral topic IDs can also be observed. Receive notifications through SharkMQ_getMessage as SMQ_SUBCHANGE.

See also: SharkMQ_observe

Parameters

tid	U32; broker topic ID to observe.

Returns: int: 0 when the request was sent; negative on failure. This is not a broker acknowledgement.

◆ pubflush()

int SharkMQ::pubflush	(	U32	tid,
		U32	subtid
	)

Flush the internal buffer and request the broker to assemble all stored fragments as one message.

See also: SharkMQ_pubflush

Parameters

tid	U32; destination topic ID obtained from the broker.
subtid	U32; subtopic ID, or zero when unused.

Returns: int: 0 when the remaining fragment and destination were sent; negative on failure. The broker assembles preceding write/wrtstr fragments into this message.

◆ publish()

int SharkMQ::publish	(	const void *	data,
		int	len,
		U32	tid,
		U32	subtid
	)

Publish messages to a topic and optionally to a sub-topic.

Topic name must have previosly been been resolved by SharkMQ_create and sub-topic should preferably have been created by SharkMQ_createsub.

See also: SharkMQ_publish

Parameters

data	const void *; payload borrowed for the call, or NULL for a prepared zero-copy send buffer.
len	int; payload length from 0 to 65520 bytes. A NULL data pointer requires len to fit SharkMQ_getSendBufSize.
tid	U32; destination topic ID obtained from the broker.
subtid	U32; subtopic ID, or zero when unused.

Returns: int: 0 on complete sending; negative on failure. Invalid lengths and zero-copy capacity overruns are rejected before sending. Incomplete transport writes close the connection.

◆ SharkMQ()

SharkMQ::SharkMQ	(	U8 *	buf,
		U16	bufLen
	)

Create a secure SMQ client instance.

See also: SharkMQ_constructor

Parameters

buf	U8 *; caller-owned control-message buffer, retained for the instance lifetime.
bufLen	U16; buffer capacity in bytes; at least 127 and large enough for the largest control message.

◆ subscribe()

int SharkMQ::subscribe ( const char * topic )

The response to SharkMQ_subscribe is asynchronous and returned as status SMQ_SUBACK via SharkMQ_getMessage.

See also: SharkMQ_subscribe

Parameters

topic const char *; required nonempty NUL-terminated name, borrowed for this call. Its bytes plus the 3-byte header must fit the TLS send buffer.

Returns: int: 0 when the request was sent; negative on failure. The broker response is asynchronous: process SMQ_SUBACK from SharkMQ_getMessage; this return value is not a topic ID.

◆ unobserve()

int SharkMQ::unobserve ( U32 tid )

Stop receiving change notifications for a topic ID or ephemeral topic ID.

See also: SharkMQ_unobserve

Parameters

tid	U32; broker topic ID to unobserve.

Returns: int: 0 when the request was sent; negative on failure. This is not a broker acknowledgement.

◆ unsubscribe()

int SharkMQ::unsubscribe ( U32 tid )

Requests the broker to unsubscribe the server from a topic.

See also: SharkMQ_unsubscribe

Parameters

tid	U32; broker topic ID to unsubscribe.

Returns: int: 0 when the request was sent; negative on failure. This is not a broker acknowledgement.

◆ write()

int SharkMQ::write	(	const void *	data,
		int	len
	)

Publish a message in chunks and request the broker to assemble the message before publishing to the subscriber(s).

See also: SharkMQ_write

Parameters

data	const void *; fragment bytes borrowed for this call; required when len is nonzero.
len	int; nonnegative fragment length in bytes.

Returns: int: 0 when buffered/intermediate fragments were accepted; negative on failure. Call SharkMQ_pubflush with the destination to finish the message.

◆ wrtstr()

int SharkMQ::wrtstr ( const char * str )

Publish a message in chunks and request the broker to assemble the message before publishing to the subscriber(s).

See also: SharkMQ_wrtstr

Parameters

str	const char *; required NUL-terminated fragment, borrowed for the call. The terminator is not sent.

Returns: int: 0 when the fragment was accepted; negative on failure. Finish with SharkMQ_pubflush.

◆ ~SharkMQ()

SharkMQ::~SharkMQ ( )

Terminate an SMQ instance.

See also: SharkMQ_destructor

Detailed Description

Modules

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ SMQSTR

Typedef Documentation

◆ SharkMQ

Function Documentation

◆ connect()

◆ create()

◆ createsub()

◆ disconnect()

◆ getMessage()

◆ getMsgSize()

◆ init()

◆ observe()

◆ pubflush()

◆ publish()

◆ SharkMQ()

◆ subscribe()

◆ unobserve()

◆ unsubscribe()

◆ write()

◆ wrtstr()

◆ ~SharkMQ()