class %Net.MQTT.Client
extends %RegisteredObject
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
and passwords.
• parameter DOMAIN = "%ObjectErrors";
Error Text Domain
• property ClientId
as %String [ ReadOnly ];
This holds the client id
• 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).
• method %OnClose()
as %Status
This callback method is invoked by the %Close method to
provide notification that the current object is being closed.
The return value of this method is ignored.
• method %OnNew(url As %String, clientid As %String = "", qos As %Integer = $$$QOSFireAndForget, keepaliveinterval As %Integer = $$$KeepAliveInterval, lwttopic As %String = "", lwtmessage As %String = "")
as %Status
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.
• final method Connect(username As %String = "", password As %String = "", cleansession As %Boolean = 1, timeout As %Integer = 1, sslconfig As %String = "")
as %Status
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.
• final method Disconnect()
as %Status
Disconnect from the broker. It's important to disconnect from the broker when a connection is
no longer required to free up system resources on both the broker and the client.
• method IsConnected(Output connected As %Boolean)
as %Status
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.
• final method Publish(topic As %String, message As %String, retain As %Boolean = 0, timeout As %Integer = 1000)
as %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.
• final method Receive(Output topic As %String, Output message As %String, timeout As %Integer = 1000)
as %Status
Listen for a message to be received for up to timeout milliseconds. If the timeout expires both the
topic and message will be set to the empty string. Additionally the TimedOut property will be set accordingly
• method Subscribe(topic As %String)
as %Status
Call this to subscribe to the named topic. The topic must be utf-8 encoded. You must call this method
before you attempt to Receive a message for the named topic.
• final method Unsubscribe(topic As %String)
as %Status
Unsubscribe from a topic. After calling this the client will stop receiving messages for the
specific topic. Topic must be utf-8 encoded.
