Simple Message Queue (SMQ) More...

Modules

Error codes returned by function SMQ_getMessage
 
Response codes returned by function SMQ_getMessage
 

Data Structures

struct  SMQ
 SimpleMQ structure. More...
 

Macros

#define INFINITE_TMO   (~((U32)0))
 Infinite wait time option for socket read functions.
 
#define SOCKET   int
 The SOCKET object/handle is an 'int' when using a BSD compatible TCP/IP stack. More...
 
#define SMQ_setCtx(o, ctx)   SOCKET_constructor(&(o)->sock, ctx)
 Bare metal configuration. More...
 
#define SMQ_getMsgSize(o)
 Returns the message size, which is SMQ::frameLen - 15. More...
 

Functions

int se_connect (int *sock, const char *address, U16 port)
 Initializes a SOCKET object connected to a remote host/address at a given port. More...
 
int se_bind (int *sock, U16 port)
 Initializes a SOCKET object bound to a local port, ready to accept client connections. More...
 
int se_accept (int **listenSock, U32 timeout, int **outSock)
 Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection. More...
 
void se_close (int *sock)
 Close a connected socket connection.
 
int se_sockValid (int *sock)
 Returns TRUE if socket is valid (connected).
 
S32 se_send (int *sock, const void *buf, U32 len)
 Sends data to the connected peer.
 
S32 se_recv (int *sock, void *buf, U32 len, U32 timeout)
 Waits for data sent by peer. More...
 
void mainTask (void *ctx)
 Main entry for all example programs.
 
void SMQ_constructor (SMQ *o, U8 *buf, U16 bufLen)
 Create a SimpleMQ client instance. More...
 
int SMQ_init (SMQ *o, const char *url, U32 *rnd)
 Initiate the SMQ server connection. More...
 
int SMQ_connect (SMQ *o, 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 (SMQ *o)
 Gracefully close the connection. More...
 
void SMQ_destructor (SMQ *o)
 Terminate a SimpleMQ instance. More...
 
int SMQ_create (SMQ *o, const char *topic)
 Create a topic an fetch the topic ID (tid). More...
 
int SMQ_createsub (SMQ *o, const char *subtopic)
 Create a sub-topic and fetch the subtopic ID. More...
 
int SMQ_subscribe (SMQ *o, const char *topic)
 The response to SMQ_subscribe is asynchronous and returned as status SMQ_SUBACK via SMQ_getMessage. More...
 
int SMQ_unsubscribe (SMQ *o, U32 tid)
 Requests the broker to unsubscribe the server from a topic. More...
 
int SMQ_publish (SMQ *o, const void *data, int len, U32 tid, U32 subtid)
 Publish messages to a topic and optionally to a sub-topic. More...
 
int SMQ_wrtstr (SMQ *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 SMQ_write (SMQ *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 SMQ_pubflush (SMQ *o, U32 tid, U32 subtid)
 Flush the internal buffer and request the broker to assemble all stored fragments as one message. More...
 
int SMQ_observe (SMQ *o, U32 tid)
 Request the broker to provide change notification events when the number of subscribers to a specific topic changes. More...
 
int SMQ_unobserve (SMQ *o, U32 tid)
 Stop receiving change notifications for a topic ID or ephemeral topic ID. More...
 
int SMQ_getMessage (SMQ *o, U8 **msg)
 Wait for messages sent from the broker. More...
 

Detailed Description

Simple Message Queue (SMQ)

SMQ is an easy to use IoT (M2M) publish subscribe protocol designed and optimized for embedded systems providing instantaneous Edge Node connectivity. The solution allows resource contrained real-time control, analysis, and updates.

See SMQ Website for more information.

Macro Definition Documentation

#define SMQ_getMsgSize (   o)

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

Parameters
othe SMQ instance.
#define SMQ_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 SMQ instance.
ctxan SeCtx instance.
#define SOCKET   int

The SOCKET object/handle is an 'int' when using a BSD compatible TCP/IP stack.

Non BSD compatible TCP IP stacks must set the macro NO_BSD_SOCK and define the SOCKET object. See the header file selib.h for details.

Function Documentation

int se_accept ( int **  listenSock,
U32  timeout,
int **  outSock 
)

Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection.

Returns
  • 1 Success
  • 0 timeout
  • -1 error
int se_bind ( int *  sock,
U16  port 
)

Initializes a SOCKET object bound to a local port, ready to accept client connections.

Returns
Zero on success. Error codes returned:
  • -1 Cannot create socket: Fatal
  • -2 Cannot listen: Fatal
  • -3 Cannot bind: socket in use
int se_connect ( int *  sock,
const char *  address,
U16  port 
)

Initializes a SOCKET object connected to a remote host/address at a given port.

Returns
Zero on success. Error codes returned:
  • -1 Cannot create socket: Fatal
  • -2 Cannot resolve 'address'
  • -3 Cannot connect
S32 se_recv ( int *  sock,
void *  buf,
U32  len,
U32  timeout 
)

Waits for data sent by peer.

Parameters
sockthe SOCKET object.
bufis the data to send.
lenis the 'buf' length.
timeoutin milliseconds. The timeout can be set to INFINITE_TMO.
Returns
the length of the data read, zero on timeout, or a negative value on error.
int SMQ_connect ( SMQ o,
const char *  uid,
int  uidLen,
const char *  credentials,
U8  credLen,
const char *  info,
int  infoLen 
)

Connect/establish a persistent SimpleMQ connection.

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

Parameters
othe SMQ instance.
uida 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.
uidLenthe uid length.
credentialsprovide credentials if required by the broker instance.
credLencredentials length.
infoa 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.
infoLenlength 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:
  • 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 SMQ::buf.

void SMQ_constructor ( SMQ o,
U8 *  buf,
U16  bufLen 
)

Create a SimpleMQ client instance.

Parameters
oUninitialized data of size sizeof(SMQ).
bufis 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.
bufLenbuffer length.
int SMQ_create ( SMQ o,
const char *  topic 
)

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

The SMQ 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 SMQ_create is asynchronous and returned as status SMQ_CREATEACK via SMQ_getMessage.

Parameters
othe SMQ instance.
topicthe topic name where you plan on publishing messages.
int SMQ_createsub ( SMQ o,
const char *  subtopic 
)

Create a sub-topic and fetch the subtopic ID.

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

Parameters
othe SMQ instance.
subtopicthe sub-topic name you want registered.
void SMQ_destructor ( SMQ o)

Terminate a SimpleMQ instance.

Parameters
othe SMQ instance.
void SMQ_disconnect ( SMQ o)

Gracefully close the connection.

You cannot publish any messages after calling this method.

Parameters
othe SMQ instance.
int SMQ_getMessage ( SMQ o,
U8 **  msg 
)

Wait for messages sent from the broker.

Parameters
othe SMQ instance.
msga 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.

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.

int SMQ_init ( SMQ o,
const char *  url,
U32 *  rnd 
)

Initiate the SMQ server connection.

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

Parameters
othe SMQ instance.
urlis 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.
int SMQ_observe ( SMQ 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 SMQ_getMessage.

Parameters
othe SMQ instance.
tidthe Topic ID you which to observe.
int SMQ_pubflush ( SMQ 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
othe SMQ instance.
tidthe topic ID (created with SMQ_create).
subtidoptional sub-topic ID preferably created with SMQ_createsub.

Example:

1 SMQ_wrtstr(smq, "Hello");
2 SMQ_wrtstr(smq, " ");
3 SMQ_wrtstr(smq, "World");
4 SMQ_pubflush(smq,tid,subtid);
int SMQ_publish ( SMQ 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 SMQ_create and sub-topic should preferably have been created by SMQ_createsub.

Parameters
othe SMQ instance.
datamessage payload.
lenpayload length.
tidthe topic ID (created with SMQ_create).
subtidoptional sub-topic ID preferably created with SMQ_createsub.
int SMQ_subscribe ( SMQ o,
const char *  topic 
)

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

Parameters
othe SMQ instance.
topicthe topic name to subscribe to.
int SMQ_unobserve ( SMQ o,
U32  tid 
)

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

Parameters
othe SMQ instance.
tidthe Topic ID you no longer want to observe.
int SMQ_unsubscribe ( SMQ o,
U32  tid 
)

Requests the broker to unsubscribe the server from a topic.

Parameters
othe SMQ instance.
tidthe topic name's Topic ID.
int SMQ_write ( SMQ 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 buffer (SMQ::buf) 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 SMQ_pubflush.

Parameters
othe SMQ instance.
datamessage payload.
lenpayload length.
int SMQ_wrtstr ( SMQ 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 buffer (SMQ::buf) 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 SMQ_pubflush.

Parameters
othe SMQ instance.
stra string.