Create an SMQ client instance and initiate the connection with the broker.
Note: the Lua client is similar to the JavaScript client, but you cannot subscribe or publish before the "onconnect" callback is called. You must re-subscribe to topics should the connection go down.
The following provides a list of methods available in an SMQ Lua client instance. Most functions do not immediately return a value, but are instead reporting the return value in optional callback functions. Only methods that include a description for a return value are, in fact, returning a value.
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 creates a 32 bit number and persistently stores the topic name and number. The 'create' method is typically used prior to publishing a message on a specific topic if the server logic implements authorization. Otherwise, the publish method can be used directly with a topic string since the publish method takes care of first creating a topic if you publish to a topic unknown to the client stack.
Create a sub-topic and fetch the subtopic ID. The createsub method is typically used prior to publishing a message on a specific topic, and sub-topic, (if) the server logic implements "authorization". Alternatively, the publish method may be used directly with topic and sub-topic strings, respectively. The publish method will manage the sequence and creation of a topic, then sub-topic, if you publish to a topic and/or sub-topic that is unknown to the client stack.
Gracefully close the connection. You cannot publish any messages after calling this method.
Get the client's ephemeral topic ID. Each client is assigned a unique topic ID, and this topic ID is included when publishing a message. All subscribers receiving the message published by a client can use this (tid) for identification purposes or for sending messages directly to the "publisher" of the message. See the subscribe onmsg for example code.
Publish messages to a topic and optionally to a sub-topic. Topics may be topic names (strings), topic IDs (numbers), or ephemeral topic IDs (numbers). Messages publishing unresolved topic names are temporarily queued. Pending topic names are resolved by calling create and/or createsub and result in the message being de-queued and published, (if) create and/or createsub reports are "accepted" by the server. Once the server denies a create and/or createsub report request, all messages sent to (unresolved) topic names are de-queued and silently discarded. You may consider using create and/or createsub prior to calling "publish" if the server solution implements topic authorization. Note: max payload size is 0xFFF0.
Subscribe to a topic and optionally to a sub-topic. You can subscribe multiple times to the same topic if you use sub-topics. Subscribing to a topic without providing a sub-topic introduces a "catch all" for sub-topics that do not correspond to any subscribed sub-topics.
The topic name "self" is interpreted as subscribing to the client's own Ephemeral Topic ID -- in other words, it means subscribing to the (tid) returned by method gettid. Subscribing to your own Topic ID makes it possible for other connected clients to send a message directly to this client.
Subscription requests are stored in an internal queue and later processed if the server connection is not established. Subscription requests are also stored temporarily if the sub-topic name must be resolved prior to subscribing.
Requests the server to unsubscribe the client from a topic. All registered onmsg callback functions, including all callbacks for sub-topics, will be removed from the client stack.
Requests 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. The client stack automatically "unobserves" observed ephemeral topic IDs when it receives a change notification.
Stop receiving change notifications for a topic or ephemeral topic ID.
Translates topic ID to topic name.
Translates topic name to topic ID.
Translates sub-topic ID to sub-topic name.
Translates sub-topic name to sub-topic ID.
You can set the following event callback functions on an SMQ instance.
The onauth function must be set if the server requires authentication. The event function is called during the SMQ handshaking phase and just before the client SMQ stack sends the CONNECT event to the broker.
The onconnect function is called after a successful connection sequence and if the server accepted the credentials. If the connection was unsuccessful or if the connection was not accepted by the broker, the onclose function is called instead.
The onmsg function is called if you subscribe to a topic and do not provide a callback function when subscribing. The onmsg function is also called if a "topic" callback function fails to decode the data as specified in the datatype.
The onclose function is called if the connection cannot be established, the server denied access, the server gracefully closed the connection, or if the connection unexpectedly closed.
The onclose function can request the SMQ client to attempt to reconnect. Function onreconnect is called if the re-connect attempt is successful. The onclose function is called again if the re-connection attempt is unsuccessful.
The onreconnect function is called if the connection closed, the onclose function requested the SMQ client to reconnect, and if the re-connect was successful. Function onconnect is called if you do not provide an onreconnect.