This package includes the SharkSSL lite library and header files.
Dependents: WebSocket-Client-Example SharkMQ-LED-Demo
SMQLib
Data Structures | |
struct | SharkMQ |
SharkMQ structure. More... | |
Modules | |
Error codes returned by function SharkMQ_getMessage | |
Response codes returned by function SharkMQ_getMessage | |
Functions | |
void | SharkMQ_constructor (SharkMQ *o, U8 *buf, U16 bufLen) |
Create a SimpleMQ client instance. | |
int | SharkMQ_init (SharkMQ *o, SharkSslCon *scon, const char *url, U32 *rnd) |
Initiate the SharkMQ server connection. | |
int | SharkMQ_connect (SharkMQ *o, const char *uid, int uidLen, const char *credentials, U8 credLen, const char *info, int infoLen) |
Connect/establish a persistent SimpleMQ connection. | |
void | SharkMQ_disconnect (SharkMQ *o) |
Gracefully close the connection. | |
void | SharkMQ_destructor (SharkMQ *o) |
Terminate a SimpleMQ instance. | |
int | SharkMQ_create (SharkMQ *o, const char *topic) |
Create a topic an fetch the topic ID (tid). | |
int | SharkMQ_createsub (SharkMQ *o, const char *subtopic) |
Create a sub-topic and fetch the subtopic ID. | |
int | SharkMQ_subscribe (SharkMQ *o, const char *topic) |
Subscribe to topic. | |
int | SharkMQ_unsubscribe (SharkMQ *o, U32 tid) |
Requests the broker to unsubscribe the client from a topic. | |
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. | |
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). | |
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). | |
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. | |
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. | |
int | SharkMQ_unobserve (SharkMQ *o, U32 tid) |
Stop receiving change notifications for a topic ID or ephemeral topic ID. | |
int | SharkMQ_getMessage (SharkMQ *o, U8 **msg) |
Wait for messages sent from the broker. |
Function Documentation
int SharkMQ_connect | ( | SharkMQ * | 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 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. 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](SharkMQErrorCodes), 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.
void SharkMQ_constructor | ( | SharkMQ * | o, |
U8 * | buf, | ||
U16 | bufLen | ||
) |
Create a SimpleMQ 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.
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 the SharkMQ instance. topic the topic name where you plan on publishing messages.
int SharkMQ_createsub | ( | SharkMQ * | o, |
const char * | subtopic | ||
) |
Create a sub-topic and fetch the subtopic ID.
The response to SharkMQ_subscribe is asynchronous and returned as status SMQ_CREATESUBACK via SharkMQ_getMessage.
- Parameters:
-
o the SharkMQ instance. subtopic the sub-topic name you want registered.
void SharkMQ_destructor | ( | SharkMQ * | o ) |
Terminate a SimpleMQ instance.
- Parameters:
-
o the SharkMQ instance.
void SharkMQ_disconnect | ( | SharkMQ * | o ) |
Gracefully close the connection.
You cannot publish any messages after calling this method.
- Parameters:
-
o the SharkMQ instance.
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](SharkMQErrorCodes) or an [asynchronous response code](SharkMQRespCodes).
- 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.
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 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.
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 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:
- 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 [SimpleMQ error code](SharkMQErrorCodes).
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.
On success, SharkMQ::buf is set to the IP address of the client as seen by the broker.
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.
- Parameters:
-
o the SharkMQ instance. tid the Topic ID you which to observe.
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 the SharkMQ instance. tid the topic ID (created with SharkMQ_create). subtid optional sub-topic ID preferably created with SharkMQ_createsub.
Example:
SharkMQ_wrtstr(smq, "Hello"); SharkMQ_wrtstr(smq, " "); SharkMQ_wrtstr(smq, "World"); SharkMQ_pubflush(smq,tid,subtid);
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 the SharkMQ instance. data message payload. len payload length. tid the topic ID (created with SharkMQ_create). subtid optional sub-topic ID preferably created with SharkMQ_createsub.
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 the SharkMQ instance. topic the topic name to subscribe to.
int SharkMQ_unobserve | ( | SharkMQ * | o, |
U32 | tid | ||
) |
Stop receiving change notifications for a topic ID or ephemeral topic ID.
- Parameters:
-
o the SharkMQ instance. tid the Topic ID you no longer want to observe.
int SharkMQ_unsubscribe | ( | SharkMQ * | o, |
U32 | tid | ||
) |
Requests the broker to unsubscribe the client from a topic.
- Parameters:
-
o the SharkMQ instance. tid the topic name's Topic ID.
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 the SharkMQ instance. data message payload. len payload length.
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.
- Parameters:
-
o the SharkMQ instance. str a string.
Generated on Wed Jul 13 2022 10:54:53 by 1.7.2