Detailed Description

Macros
#define	SharkMQ_setProxy(o, proxyMA) (o)->proxy=proxyMA

#define	SharkMQ_setCtx(o, ctx) SOCKET_constructor(&(o)->sock, ctx)
	Bare metal configuration. More...

#define	SharkMQ_getSendBufPtr(o) (SharkSslCon_getEncBufPtr((o)->scon) + 15)
	Zero copy API: Get start of send buffer. More...

#define	SharkMQ_getSendBufSize(o) (SharkSslCon_getEncBufSize((o)->scon) - 15)
	Zero copy API: Get max buffer length. More...

#define	SharkMQ_getMsgSize(o) ((o)->frameLen-15)
	Returns the message size, which is SharkMQ::frameLen - 15. More...

Functions
void	SharkMQ_constructor (SharkMQ o, U8 buf, U16 bufLen)
	Create a secure SMQ client instance. More...

int	SharkMQ_init (SharkMQ o, SharkSslCon scon, const char url, U32 rnd)
	Initiate the SharkMQ server connection. More...

int	SharkMQ_connect (SharkMQ o, 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 (SharkMQ *o)
	Gracefully close the connection. More...

void	SharkMQ_destructor (SharkMQ *o)
	Terminate an SMQ instance. More...

int	SharkMQ_create (SharkMQ o, const char topic)
	Create a topic an fetch the topic ID (tid). More...

int	SharkMQ_createsub (SharkMQ o, const char subtopic)
	Create a sub-topic and fetch the subtopic ID. More...

int	SharkMQ_subscribe (SharkMQ o, const char topic)
	Subscribe to topic. More...

int	SharkMQ_unsubscribe (SharkMQ *o, U32 tid)
	Requests the broker to unsubscribe the client from a topic. More...

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

int	SharkMQ_wrtstr (SharkMQ o, 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 (SharkMQ o, 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 (SharkMQ *o, U32 tid, U32 subtid)
	Flush the internal buffer and request the broker to assemble all stored fragments as one message. More...

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

int	SharkMQ_unobserve (SharkMQ *o, U32 tid)
	Stop receiving change notifications for a topic ID or ephemeral topic ID. More...

int	SharkMQ_getMessage (SharkMQ o, U8 *msg)
	Wait for messages sent from the broker. More...

Macro Definition Documentation

◆ SharkMQ_getMsgSize

#define SharkMQ_getMsgSize ( o ) ((o)->frameLen-15)

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

Parameters

o	the SharkMQ instance.

◆ SharkMQ_getSendBufPtr

#define SharkMQ_getSendBufPtr ( o ) (SharkSslCon_getEncBufPtr((o)->scon) + 15)

Zero copy API: Get start of send buffer.

Returns SharkSslCon_getEncBufPtr() + 15. Use with SharkMQ_publish and set "data argument"=NULL.

Parameters

o	the SharkMQ instance.

Returns: pointer to start of SMQ buffer area

◆ SharkMQ_getSendBufSize

#define SharkMQ_getSendBufSize ( o ) (SharkSslCon_getEncBufSize((o)->scon) - 15)

Zero copy API: Get max buffer length.

Returns SharkSslCon_getEncBufSize - 15. Use with SharkMQ_getSendBufPtr.

Parameters

o	the SharkMQ instance.

Returns: SMQ send buffer size

◆ SharkMQ_setCtx

#define SharkMQ_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.

◆ SharkMQ_setProxy

#define SharkMQ_setProxy	(	o,
		proxyMA
	)	(o)->proxy=proxyMA

Function Documentation

◆ SharkMQ_connect()

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

Connect/establish a persistent SMQ connection.

The connection phase is divided into two steps: (1) initiating via SharkMQ_init and (2) connecting.

Parameters

o	the SharkMQ instance.
uid	a universally unique client identifier (uid) must be unique across all clients connecting to the same broker instance. The uid is preferably a stringified version of the client's Ethernet MAC address.
uidLen	the uid length, from 1 to 255 bytes.
credentials	provide credentials if required by the broker instance; required when credLen is nonzero.
credLen	credentials length.
info	a string that provides information to optional server code interacting with the broker. This string is also passed into the optional broker's authentication callback function.
infoLen	nonnegative length of info; use zero when info is NULL. The complete CONNECT frame (8+uidLen+credLen+infoLen bytes) must fit the TLS send buffer.
maxTlsFrameSize	Request server limits TLS frame size to this size. SMQ messages sent by server larger than this size is split up into smaller chunks. The value zero means don't care.

Returns: 0 only after acceptance. Returns SMQ_TIMEOUT while awaiting CONNACK; call again to continue waiting without resending CONNECT, using a bounded retry policy. Otherwise returns an error code from the TCP/IP stack, SimpleMQ error code, or one of the following error codes from the broker:

0x01 Connection Refused: unacceptable protocol version
0x02 Connection Refused: server unavailable
0x03 Connection Refused: Incorrect credentials
0x04 Connection Refused: Client certificate required
0x05 Connection Refused: Client certificate not accepted
0x06 Connection Refused: Access denied

The broker may optionally send a human readable string in addition to the above broker produced error codes. This string is avaiable via SharkMQ::buf. Handle SMQ_TIMEOUT explicitly. An incomplete transport write returns a negative error and closes the connection; do not retry plaintext on it.

◆ SharkMQ_constructor()

void SharkMQ_constructor	(	SharkMQ *	o,
		U8 *	buf,
		U16	bufLen
	)

Create a secure SMQ client instance.

Parameters

o	Uninitialized data of size sizeof(SharkMQ).
buf	is used for internal management and must not be less than 127 bytes and not smaller than the largest control frame. Function SharkMQ_getMessage will return SMQE_BUF_OVERFLOW if the buffer is not sufficiently large.
bufLen	buffer length.

◆ SharkMQ_create()

int SharkMQ_create	(	SharkMQ *	o,
		const char *	topic
	)

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

The SharkMQ protocol is optimized and does not directly use a string when publishing, but a number. The server randomly a creates 32 bit number and persistently stores the topic name and number.

The response to SharkMQ_create is asynchronous and returned as status SMQ_CREATEACK via SharkMQ_getMessage.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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.

◆ SharkMQ_createsub()

int SharkMQ_createsub	(	SharkMQ *	o,
		const char *	subtopic
	)

Create a sub-topic and fetch the subtopic ID.

The response to SharkMQ_createsub is asynchronous and returned as status SMQ_CREATESUBACK via SharkMQ_getMessage.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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.

◆ SharkMQ_destructor()

void SharkMQ_destructor ( SharkMQ * o )

Terminate an SMQ instance.

Parameters

o	the SharkMQ instance.

◆ SharkMQ_disconnect()

void SharkMQ_disconnect ( SharkMQ * o )

Gracefully close the connection.

You cannot publish any messages after calling this method.

Parameters

o	the SharkMQ instance.

◆ SharkMQ_getMessage()

int SharkMQ_getMessage	(	SharkMQ *	o,
		U8 **	msg
	)

Wait for messages sent from the broker.

Parameters

o	the SharkMQ instance.
msg	a pointer to the response data (out param)

Returns

a negative value signals an error code or an asynchronous response code.
zero signals a timeout while continuing a control frame or payload, or an empty PUBLISH payload. SMQ_TIMEOUT signals a timeout while waiting for a frame header. Check frameLen and bytesRead for message completion.
a value greater than zero signals the reception of a full message or a message fragment. See receiving large frames for details.

Receiving large frames:
The SMQ protocol is frame based, but the function can return a fragment before the complete SMQ frame is received if the frame sent by the peer is larger than the provided buffer. The frame length is returned in SharkMQ::frameLen and the data consumed thus far is returned in SharkMQ::bytesRead. The complete frame is consumed when frameLen == bytesRead.

Note: the default timeout value is set to one minute. You can set the timeout value by setting SharkMQ::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.

Returns

< 0: An error or a control message such as SMQ_SUBACK
>= 0: An SMQ message with this length

◆ SharkMQ_init()

int SharkMQ_init	(	SharkMQ *	o,
		SharkSslCon *	scon,
		const char *	url,
		U32 *	rnd
	)

Initiate the SharkMQ server connection.

The connection phase is divided into two steps: (1) initiating and (2) connecting via SharkMQ_connect.

Parameters

o	the SharkMQ instance.
scon	SharkSslCon instance created by calling SharkSsl_createCon.
url	is a URL using the HTTPS scheme and this URL must be to a server resource that initiates an SMQ connection.
rnd	(out param) a random number created by the server. This number can be used for securing hash based password encryption.

Returns

The return value is SharkSslConTrust for any return value greater than zero.
A negative return value is one of: an error code from se_connect, or a SMQ error code.

A return value greater than zero means that the TLS server certificate and reference name are trusted according to the SharkSSL configuration. Configure the SharkSsl object with a trusted CA list before calling this function. Enable SHARKSSL_CHECK_DATE with a trusted clock to validate certificate dates.

On success, SharkMQ::buf is set to the IP address of the client as seen by the broker.

◆ SharkMQ_observe()

int SharkMQ_observe	(	SharkMQ *	o,
		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. The number of connected subscribers for an ephemeral ID can only be one, which means the client is connected. Receiving a change notification for an ephemeral ID means the client has disconnected and that you no longer will get any change notifications for the observed topic ID.

Change notification events are received as SMQ_SUBCHANGE via SharkMQ_getMessage.

Read the subscriber count from the SMQ_SUBCHANGE result as described by SharkMQ_getMessage. Observing a topic does not subscribe to its data.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
tid	U32; broker topic ID to observe.

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

◆ SharkMQ_pubflush()

int SharkMQ_pubflush	(	SharkMQ *	o,
		U32	tid,
		U32	subtid
	)

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

This message is then published to topic 'tid', and sub-topic 'subtid'.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
tid	U32; destination topic ID obtained from the broker.
subtid	U32; subtopic ID, or zero when unused.

Example:

SharkMQ_wrtstr(smq, "Hello");
SharkMQ_wrtstr(smq, " ");
SharkMQ_wrtstr(smq, "World");
SharkMQ_pubflush(smq,tid,subtid);

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

◆ SharkMQ_publish()

int SharkMQ_publish	(	SharkMQ *	o,
		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.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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_subscribe()

int SharkMQ_subscribe	(	SharkMQ *	o,
		const char *	topic
	)

Subscribe to topic.

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

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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.

◆ SharkMQ_unobserve()

int SharkMQ_unobserve	(	SharkMQ *	o,
		U32	tid
	)

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

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
tid	U32; broker topic ID to unobserve.

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

◆ SharkMQ_unsubscribe()

int SharkMQ_unsubscribe	(	SharkMQ *	o,
		U32	tid
	)

Requests the broker to unsubscribe the client from a topic.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
tid	U32; broker topic ID to unsubscribe.

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

◆ SharkMQ_write()

int SharkMQ_write	(	SharkMQ *	o,
		const void *	data,
		int	len
	)

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

This method uses the internal SharkSSL send buffer and sends the message as a chunk when the internal buffer is full, thus sending the message as an incomplete message to the broker. The message is assembled by the broker when you flush the remaining bytes in the buffer by calling SharkMQ_pubflush.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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.

◆ SharkMQ_wrtstr()

int SharkMQ_wrtstr	(	SharkMQ *	o,
		const char *	str
	)

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

This method uses the internal SharkSSL send buffer and sends the message as a chunk when the internal buffer is full, thus sending the message as an incomplete message to the broker. The message is assembled by the broker when you flush the remaining bytes in the buffer by calling SharkMQ_pubflush.

Finish this message before calling another send operation such as SharkMQ_publish, SharkMQ_create, or SharkMQ_subscribe.

Parameters

o	SharkMQ *; required initialized, connected instance. Serialize calls and retain its application-supplied buffers and TLS connection.
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.

Detailed Description

Macros

Functions

Macro Definition Documentation

◆ SharkMQ_getMsgSize

◆ SharkMQ_getSendBufPtr

◆ SharkMQ_getSendBufSize

◆ SharkMQ_setCtx

◆ SharkMQ_setProxy

Function Documentation

◆ SharkMQ_connect()

◆ SharkMQ_constructor()

◆ SharkMQ_create()

◆ SharkMQ_createsub()

◆ SharkMQ_destructor()

◆ SharkMQ_disconnect()

◆ SharkMQ_getMessage()

◆ SharkMQ_init()

◆ SharkMQ_observe()

◆ SharkMQ_pubflush()

◆ SharkMQ_publish()

◆ SharkMQ_subscribe()

◆ SharkMQ_unobserve()

◆ SharkMQ_unsubscribe()

◆ SharkMQ_write()

◆ SharkMQ_wrtstr()