Detailed Description

Publish and subscribe from C or C++ using a non-TLS SMQ connection.

SMQ is an easy-to-use IoT (M2M) publish/subscribe protocol. This documentation is for the non-secure SMQ C client library. See SharkMQ for the secure version.

The code is not multithread-safe. However, you may use the SMQ stack in a two-thread environment, one thread for consuming data and one for producing data, if the code is compiled with the macro SMQ_ENABLE_SENDBUF. This macro separates the receiving and sending buffer management. Note that the buffer passed into the SMQ constructor should be twice the size when enabling SMQ_ENABLE_SENDBUF. The buffer is split in two, where one buffer is used for 'receiving' and the other buffer is used for 'sending' data.

The SMQ C library provides both a C API and C++ wrappers. Start with the SMQ constructor, SMQ_init(), and SMQ_connect(); receive broker acknowledgments and messages through SMQ_getMessage(). See C API for the C entry points.

Collaboration diagram for Native SMQ client:

Modules
	Error codes returned by function SMQ_getMessage


	Response codes returned by function SMQ_getMessage

	C API

Classes
struct	SMQ
	SimpleMQ structure. More...

Typedefs
typedef struct SMQ	SMQ
	SimpleMQ structure. More...

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

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

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

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

	SMQ::~SMQ ()
	Terminate a SimpleMQ instance. More...

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

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

int	SMQ::subscribe (const char *topic)
	The response to SMQ_subscribe is asynchronous and returned as status SMQ_SUBACK via SMQ_getMessage. More...

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

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

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

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

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

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

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

Typedef Documentation

◆ SMQ

typedef struct SMQ SMQ

SimpleMQ structure.

Function Documentation

◆ connect()

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

Connect/establish a persistent SimpleMQ connection.

See also: SMQ_connect

Parameters

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.
credentials	provide credentials if required by the broker instance.
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	length of info.

Returns: 0 on success, error code from TCP/IP stack, SimpleMQ error code , or one of the following error codes from the broker:

◆ create()

int SMQ::create ( const char * topic )

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

See also: SMQ_create

Parameters

topic the topic name where you plan on publishing messages.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ createsub()

int SMQ::createsub ( const char * subtopic )

Create a sub-topic and fetch the subtopic ID.

See also: SMQ:createsub

Parameters

subtopic the sub-topic name you want registered.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ disconnect()

void SMQ::disconnect ( )

Gracefully close the connection.

See also: SMQ_disconnect

◆ getMessage()

int SMQ::getMessage ( U8 ** msg )

Wait for messages sent from the broker.

See also: SMQ_getMessage

Parameters

msg	a pointer to the response data (out param)

Returns: a negative value signals an error code or an asynchronous response code . zero signals timeout. 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 SimpleMQ protocol is frame based, but the function can return a fragment before the complete SimpleMQ frame is received if the frame sent by the peer is larger than the provided buffer. The frame length is returned in SMQ::frameLen and the data consumed thus far is returned in SMQ::bytesRead . The complete frame is consumed when frameLen == bytesRead.

◆ getMsgSize()

int SMQ::getMsgSize ( )

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

See also: SMQ_getMsgSize

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

◆ init()

int SMQ::init	(	const char *	url,
		U32 *	rnd
	)

Initiate the SMQ server connection.

See also: SMQ_init

Parameters

url	is a URL that starts with http:// and this URL must be to a server resource that initiates a SimpleMQ connection.
rnd	(out param) a random number created by the server. This number can be used for securing hash based password encryption.

Returns: 0 on success, error code from TCP/IP stack, or SimpleMQ error code . SMQ::buf is set to the IP address of the client as seen by the broker.

◆ observe()

int SMQ::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.

See also: SMQ_observe for details

Parameters

tid	the Topic ID you which to observe.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ pubflush()

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

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

See also: SMQ_pubflush

Parameters

tid	the topic ID (created with SMQ_create).
subtid	optional sub-topic ID preferably created with SMQ_createsub.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ publish()

int SMQ::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 SMQ_create and sub-topic should preferably have been created by SMQ_createsub.

See also: SMQ_publish

Parameters

data	message payload.
len	payload length.
tid	the topic ID (created with SMQ_create).
subtid	optional sub-topic ID preferably created with SMQ_createsub.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ SMQ()

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

Create a SimpleMQ client instance.

See also: SMQ_constructor

Parameters

buf	is used for internal management and must not be less than 127 bytes and not smaller than the largest control frame. Function SMQ_getMessage will return SMQE_BUF_OVERFLOW if the buffer is not sufficiently large.
bufLen	buffer length.

◆ subscribe()

int SMQ::subscribe ( const char * topic )

The response to SMQ_subscribe is asynchronous and returned as status SMQ_SUBACK via SMQ_getMessage.

See also: SMQ_subscribe

Parameters

topic the topic name to subscribe to.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ unobserve()

int SMQ::unobserve ( U32 tid )

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

See also: SMQ_unobserve

Parameters

tid	the Topic ID you no longer want to observe.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ unsubscribe()

int SMQ::unsubscribe ( U32 tid )

Requests the broker to unsubscribe the server from a topic.

See also: SMQ_unsubscribe

Parameters

tid	the topic name's Topic ID.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ write()

int SMQ::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: SMQ_write

Parameters

data	message payload.
len	payload length.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ wrtstr()

int SMQ::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: SMQ_wrtstr

Parameters

str a string.

Returns: 0 when the operation is sent/buffered successfully, or a negative protocol, buffer, or transport error. Broker acknowledgments, where applicable, arrive through SMQ_getMessage().

◆ ~SMQ()

SMQ::~SMQ ( )

Terminate a SimpleMQ instance.

See also: SMQ_destructor

Detailed Description

Modules

Classes

Typedefs

Functions

Typedef Documentation

◆ SMQ

Function Documentation

◆ connect()

◆ create()

◆ createsub()

◆ disconnect()

◆ getMessage()

◆ getMsgSize()

◆ init()

◆ observe()

◆ pubflush()

◆ publish()

◆ SMQ()

◆ subscribe()

◆ unobserve()

◆ unsubscribe()

◆ write()

◆ wrtstr()

◆ ~SMQ()