This class implements an interface to the eclispse paho-c MQTT client library. Details of
of the library can be found here :- https://www.eclipse.org/paho/clients/c.
The client provides the ability to connect to a third-party MQTT broker and publish or
subscribe to topics and send/receive messages. MQTT is a light-weight protocol and
can provide superior performance to HTTP based messaging. There are many excellent tutorials
for MQTT to be found on the internet and one should take the time to become familiar with the
basics as although the interface to the client is relatively straight-forward, the behaviors can be
sophisticated depending upon which options are selected. All strings passed to the library have the
requirement to be utf-8 encoded which includes, but is not limited to, messages, topics, usernames
property TimedOut as %Boolean [ InitialExpression = 0 ];
Indicates if the last send or receive operation timed out. You can test this following
a successful call to determine if the operation timed out. The timeout on a send is only
relevant if you have selected a quality of service which indicates that the broker should
confirm receipt of the message ($$$QOSWaitForDelivery specified on the send).
When creating a new client instance at minimum the url to connect and a client id is required to be specified.
The client id must be a utf-8 string which is used to uniquely identify the client.
This takes the form "tcp://localhost:1883" where the scheme is tcp and the host and port are seperated by a colon. If
you are using ssl you should specify the url in the form "ssl://localhost:8883" where scheme is ssl.
The second parameter is a string which the broker can use to identify the client. The client will generate an id if not specified.
The third parameter defines the required quality of service, 'Fire and Forget' or 'Wait for Delivery'. The fourth parameter is the keepalive interval.
The client will send keepalive messages to the broker according to the specified interval. The final pair of parameters specifies the last will and testament topic and associated message.
The LWT (last will and testament) feature tells the broker to deliver the Last Will message to the Last Will topic, should the
client unexpectedly disconnect
Note, %New() can error so it's important to check that the return value with $IsObject() and examine the %objlasterror status value
should the %New() not return a valid object.
Connect to the broker specifying username and password if required. The cleansession argument
can be set to 1 if a persistent session is required. Timeout is a connection timeout in seconds. If a secure connection using
SSL is required then the name of an IRIS SSL configuration should be passed as the fifth argument. Please
consult the documentation for an explanation of what it means to use a persistent session.
Test to see if the client is connected. The library maintains a connection and it can be queried
to determine if the client is currently connected. Disconnects can occur at any time due to network
glitches so it's important to be able to determine the connection status.
Send a message to a specified topic. Note that both should be utf-8 encoded. You may pass
1 as the retain argument if you want the broker to retain the message. Additionally if the QOS has been set
to $$$QOSWaitForDelivery then the timeout argument will be used for the time to wait for an acknowledgement that
the broker has received the message. After calling send you can check the TimedOut property to determine it's status.