MQTT Class

Properties   Methods   Events   Config Settings   Errors  

A lightweight, fully-featured MQTT client implementation.

Syntax

ipworksmq.mqtt()

Remarks

The MQTT class provides a lightweight, fully-featured MQTT client implementation with support for versions 3.1.1 and 5.0. The class supports plaintext and TLS-enabled connections over both standard TCP and WebSockets.

Connecting

When connecting to an MQTT server, the class sends the following information:

• The values of the ClientId, CleanSession, and KeepAliveInterval properties.
• The value of the User property (if non-empty).
• The value of the Password property (if non-empty).
• The values of the WillTopic and WillMessage properties and the WillQOS and WillRetain configuration settings.
• MQTT 5 specific values from ClientTopicAliasMax, SessionExpInterval, ConnectProperties and WillProperties.

If CleanSession is True, check the SessionPresent configuration setting once connected to determine whether the server actually had any session state saved.

Refer to CleanSession, SaveSession, and RestoreSession for more information about MQTT sessions and session state persistence; refer to WillTopic, WillMessage, WillQOS, and WillRetain for more information about MQTT Wills.

Basic Connection Example mqtt1.ClientId = "testClient"; mqtt1.CleanSession = true; mqtt1.KeepAliveInterval = 30; mqtt1.WillTopic = "wills/" + mqtt1.ClientId; mqtt1.WillMessage = mqtt1.ClientId + " was disconnected ungracefully!"; mqtt1.ConnectTo("mqtt.test-server.com", 1883);

Topic Subscriptions

When subscribing, pass one or more topic filters and QoS levels to indicate the topics to subscribe to and the desired QoS level(s). Topic filters may contain wildcards in order to match multiple topics on the server.

Subscribe Examples // Subscribed event handler. mqtt1.OnSubscribed += (s, e) => { if (e.ResponseCode <= 2) Console.WriteLine("Subscribed to " + e.TopicFilter + " at QoS " + e.QOS + "."); else Console.WriteLine("Failed to subscribe to " + e.TopicFilter + "."); }; // Basic, subscribe to some topic filters, all at the same QoS level. mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 2); // A bit more advanced, subscribe to the same topic filters, but at different QoS levels. mqtt1.Config("TopicQOSArray=1,2,2"); // The 0 is ignored here since we've specified individual QoS values explicitly. mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 0);

After subscribing to topics, any messages received will cause the MessageIn, and potentially also the MessageAck, events to fire. Refer to those events for more information about processing steps for inbound messages.

When unsubscribing, pass the exact same topic filter that was used to subscribe.

Unsubscribe Example // Unsubscribe from topic filters; have to use the exact same strings as before. If this // was to be called after calling the code example shown for the Subscribe() method, we // would still be subscribed to the "home" topic filter. mqtt1.Unsubscribe("home/floor1/+/temperature,home/floor2/#");

Refer to Subscribe and Unsubscribe for more information about subscriptions and topic filters.

Publishing Messages

PublishMessage is used to publish a message with a string payload, while PublishData is used to publish a message with a raw data payload. Both also accept the name of a topic to publish to, and a QoS level at which to publish.

Publish Examples // Publish a simple string-based message. mqtt1.PublishMessage("/home/floor1/security/camera2", 1, "Cat detected!"); // Publish a raw data message. byte[] catPicture = ...; mqtt1.PublishData("/home/floor1/security/camera2", 1, catPicture);

Refer to PublishData and PublishMessage for more information about message publishing and processing steps for outbound messages, as well as topic naming.

MQTT 5 Notes

MQTT 5 is similar to v3.1.1, with a few changes and several new features. Major differences include:

• The Clean Session flag functionality is divided into two properties to allow for finer control over session state data: the Clean Start flag (see CleanSession) and the new SessionExpInterval.
• All response packets (CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT) now contain a reason code describing why operations succeeded or failed. See MessageAck, Subscribed, Unsubscribed, and DisconnectReasonCode for details.
• The Request / Response pattern is formalized by the addition of the ResponseTopic. Additional properties such as correlation data and be specified via OutgoingMessageProperties and ConnectProperties.
• New subscription features: Shared Subscriptions, Subscription Options, and SubscriptionIdentifier (see Subscribe for details).
• Topic Aliases can be sent by both client and server to refer to topic filters by shorter numerical identifiers in order to save bandwidth (see TopicAlias, ServerTopicAliasMax and ClientTopicAliasMax).
• Servers can communicate what features it supports in ConnAckProperties.
• More: message expiration (OutgoingMessageProperties), Receive Maximums and Maximum Packet Sizes (ConnectProperties and ConnAckProperties), and a Will Delay interval (WillProperties) are all supported.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

MQTT.CleanSession Property

Determines whether a clean session is used once connected.

Syntax

isCleanSession(): boolean;
setCleanSession(cleanSession: boolean): void;

Default Value

TRUE

Remarks

This property determines whether or not the class should instruct the server to use a clean session when it connects. (Note that this property must be set to the desired value before calling Connect.)

By default, CleanSession is true, so the server will discard any state data previously associated with the current ClientId once the class has connected successfully. In addition, the server will not save any state data when the class disconnects.

Setting CleanSession to False before connecting will cause the server to re-associate any previously stored state data for the current ClientId. The server will also save any state data that exists when the class is disconnected.

The server-side session state consists of:

• whether a session is present (see SessionPresent),
• client subscriptions (including subscription identifiers in MQTT 5),
• QoS 1 and 2 messages sent to the client pending transmission or completed acknowledgment (and optionally pending QoS 0 messages),
• QoS 2 messages received from the client but not completely acknowledged, and
• the SessionExpInterval (in MQTT 5).

Note that retained messages are not deleted as a result of a session ending, but are not part of the session state.

Client-Side Session State

When setting CleanSession to False, it is important that the RestoreSession method be used to load any previously saved (client-side) session data from a previous session before calling Connect. (Successful calls to RestoreSession will automatically set CleanSession to False.)

Similarly, once disconnected, save the string returned by SaveSession for later use. The saved session information may be used when connecting with CleanSession set to False at a later time.

The client-side session state consists of:

• QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely acknowledged, and
• QoS 2 messages which have been received from the Server, but have not been completely acknowledged.

Refer to SaveSession and RestoreSession for more information.

MQTT 5 Notes

In MQTT 5, the "Clean Session" flag from v3.1.1 is split into a "Clean Start" flag indicating that the server should discard previously saved session data from this connection, and a SessionExpInterval controlling the length of time the server should preserve the session data after disconnection.

In MQTT 5, this property acts only as the "Clean Start" flag. It determines whether or not the class should instruct the server to discard any previously stored session data associated with the current ClientId and start a new clean session.

For more information on session expiration in MQTT 5, see the SessionExpInterval config. Setting CleanSession to True in v3.1.1 is equivalent to setting CleanSession to True AND setting SessionExpInterval to 0 in MQTT 5.

As with MQTT 3.1.1, it is important for the client to save and restore its own session data on connection and disconnection depending on the value of CleanSession, and to manage its preservation depending on SessionExpInterval.

This property is not available at design time.

MQTT.ClientId Property

A string that uniquely identifies this instance of the class to the server.

Syntax

getClientId(): string;
setClientId(clientId: string): void;

Default Value

""

Remarks

The ClientId string is used by the server to uniquely identify each client that is connected to it. In MQTT 5, when the SessionExpInterval config is set to a positive value, the server will also associate it with any session state data that needs to be saved for the length of time specified when the class is disconnected.

If ClientId is empty when Connect is called, the class's behavior depends on value of CleanSession. If CleanSession is True, the class will automatically generate a unique value for ClientId before connecting. If CleanSession is False, the class .

This property is not available at design time.

MQTT.Connected Property

Triggers a connection or disconnection.

Syntax

isConnected(): boolean;

Default Value

FALSE

Remarks

This property triggers a connection or disconnection. Setting this property to True makes the class attempt to connect to the host identified by the RemoteHost property. If successful, after the connection is achieved the value of the property changes to True and the Connected event is fired.

Setting this property to False closes the connection.

By default the class will connect in plaintext. To enable SSL set SSLEnabled to True.

In addition, WebSocket connections are supported. To connect using WebSockets specify a hostname beginning with ws:// (plaintext) or wss:// (SSL). For instance, ws://test.mosquitto.org.

When connecting to an MQTT server, the class sends the following information:

• The values of the ClientId, CleanSession, and KeepAliveInterval properties.
• The value of the User property (if non-empty).
• The value of the Password property (if non-empty).
• The values of the WillTopic and WillMessage properties and the WillQOS and WillRetain configuration settings.
• MQTT 5 specific values from ClientTopicAliasMax, SessionExpInterval, ConnectProperties and WillProperties.

If CleanSession is True, check the SessionPresent configuration setting once connected to determine whether the server actually had any session state saved.

Refer to CleanSession, SaveSession, and RestoreSession for more information about MQTT sessions and session state persistence; refer to WillTopic, WillMessage, WillQOS, and WillRetain for more information about MQTT Wills.

Basic Connection Example mqtt1.ClientId = "testClient"; mqtt1.CleanSession = true; mqtt1.KeepAliveInterval = 30; mqtt1.WillTopic = "wills/" + mqtt1.ClientId; mqtt1.WillMessage = mqtt1.ClientId + " was disconnected ungracefully!"; mqtt1.RemoteHost = "mqtt.test-server.com"; mqtt1.RemotePort = 1883; mqtt1.Connect();

This property is not available at design time.

MQTT.Firewall Property

A set of properties related to firewall access.

Syntax

getFirewall(): Firewall;
setFirewall(firewall: Firewall): void;

Default Value

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the class will attempt to connect.

MQTT.IncomingMessages Property

Collection of incoming messages with QoS > 0 that have not been fully acknowledged.

Syntax

getIncomingMessages(): MQTTMessageList;

Default Value

Remarks

Each time the class receives a message with a QoS of 1 or 2, it adds it to the IncomingMessage* properties. A message remains in the IncomingMessage* properties until the class has completed all of the acknowledgment steps required for it based on its QoS level.

Incoming messages with a QoS of 1 follow these steps:

1. The message is added to IncomingMessage* when the class receives the PUBLISH packet.
2. The class sends a PUBACK (publish acknowledgment) packet in response.
3. The MessageAck event is fired.
4. The message is removed from IncomingMessage*.
5. The MessageIn event is fired.

Incoming messages with a QoS of 2 follow these steps:

1. The message is added to IncomingMessage* when the class receives the PUBLISH packet.
2. The class sends a PUBREC (publish received) packet in response.
3. The class waits to receive a PUBREL (publish release) packet.
4. The class sends a PUBCOMP (publish complete) packet in response.
5. The MessageAck event is fired.
6. The message is removed from IncomingMessage*.
7. The MessageIn event is fired.

The class processes messages anytime DoEvents is called. In applications with a GUI, the DoEvents method is also typically called automatically when the class is idle. In all other situations however, it is best practice to call DoEvents in a loop when possible to ensure timely processing of messages.

Note that incoming messages with a QoS of 0 are not added to IncomingMessage* since they do not require acknowledgment. Upon receipt, they are added to an internal queue, and are fired through the MessageIn event as soon as DoEvents is called.

This property is read-only and not available at design time.

MQTT.KeepAliveInterval Property

The maximum period of inactivity the class will allow before sending a keep-alive packet.

Syntax

getKeepAliveInterval(): number;
setKeepAliveInterval(keepAliveInterval: number): void;

Default Value

0

Remarks

The KeepAliveInterval, if set to a non-zero value, is the maximum number of seconds that the class will allow the connection to be idle before sending a PINGREQ (ping request) packet to the server. The value of KeepAliveInterval is sent to the server when Connect is called; it cannot be changed when the class is already connected.

MQTT servers are required to measure periods of inactivity for all clients who specify a non-zero KeepAliveInterval, and must disconnect them if they have not communicated within 1.5 times KeepAliveInterval.

Similarly, if the class doesn't receive a PINGRESP (ping response) packet within KeepAliveInterval seconds after sending a PINGREQ packet, it will disconnect from the server.

If KeepAliveInterval is set to 0 (default), keep-alive functionality is disabled entirely. In this case, the class will not send any PINGREQ packets, and the server is not required to close the connection due to inactivity.

Note that, regardless of keep-alive settings, the server is always free to disconnect clients it deems "unresponsive".

This property is not available at design time.

MQTT.LocalHost Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

getLocalHost(): string;
setLocalHost(localHost: string): void;

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

MQTT.LocalPort Property

The TCP port in the local host where the class binds.

Syntax

getLocalPort(): number;
setLocalPort(localPort: number): void;

Default Value

0

Remarks

This property must be set before a connection is attempted. It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting this property to 0 (default) enables the system to choose an open port at random. The chosen port will be returned by the LocalPort property after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set this property when a connection is active will generate an error.

This property is useful when trying to connect to services that require a trusted port in the client side.

MQTT.OutgoingMessages Property

Collection of outgoing messages with QoS > 0 that have not been fully acknowledged.

Syntax

getOutgoingMessages(): MQTTMessageList;

Default Value

Remarks

Each time the class publishes a message with a QoS of 1 or 2, it adds it to the OutgoingMessage* properties after the initial PUBLISH packet is sent (this does not occur for messages publish with a QoS of 0). A message remains in the OutgoingMessage* properties until the class has completed all of the acknowledgment steps required for it based on its QoS level.

Outgoing messages with a QoS of 1 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessage*.
5. The MessageOut event is fired.

Outgoing messages with a QoS of 2 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBREC (publish received) packet.
3. The class sends a PUBREL (publish release) packet in response.
4. The class waits to receive a PUBCOMP (publish complete) packet.
5. The MessageAck event is fired.
6. The message is removed from OutgoingMessage*.
7. The MessageOut event is fired.

In MQTT 3.1.1, the RepublishInterval configuration setting, if set to a non-zero value (default), controls how long the class will wait to receive a PUBACK (for QoS 1) or PUBREC (for QoS 2) before automatically republishing an outgoing message. In MQTT 5, messages are only republished if the client is disconnected before receiving a PUBACK or PUBREC.

The class processes messages anytime DoEvents is called. In applications with a GUI, the DoEvents method is also typically called automatically when the class is idle. In all other situations however, it is best practice to call DoEvents in a loop when possible to ensure timely processing of messages.

This property is read-only and not available at design time.

MQTT.Password Property

A password if authentication is to be used.

Syntax

getPassword(): string;
setPassword(password: string): void;

Default Value

""

Remarks

This property can be set to a password if authentication is to be used.

In MQTT 3.1.1, while a User may be specified without a Password, setting a Password without a User is not supported; attempting to do so will cause the server to reject the connection attempt.

In MQTT 5, a Password may be set without a User, allowing the field to be used for credentials other than a password.

This property is not available at design time.

MQTT.ReadyToSend Property

Indicates whether the class is ready to send data.

Syntax

isReadyToSend(): boolean;

Default Value

FALSE

Remarks

This property indicates that the underlying TCP/IP subsystem is ready to accept data. This is True after connecting to the remote host, and will become False if a call to PublishData or PublishMessage fails due to a WOULDBLOCK condition.

Once data can be sent again, the ReadyToSend event will fire and this property will be True.

If a WOULDBLOCK error occurs while sending a message the class will automatically complete the transmission when sending is possible. No action needs to be taken to re-send the message. ReadyToSend will fire after the class completes any partially sent messages.

This property is read-only and not available at design time.

MQTT.RemoteHost Property

The address of the remote host. Domain names are resolved to IP addresses.

Syntax

getRemoteHost(): string;
setRemoteHost(remoteHost: string): void;

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host. It is set before a connection is attempted and cannot be changed once a connection is established.

If this property is set to a Domain Name, a DNS request is initiated, and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.

If the class is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

By default the class will connect in plaintext. To enable SSL set SSLEnabled to True.

In addition, WebSocket connections are supported. To connect using WebSockets specify a hostname beginning with ws:// (plaintext) or wss:// (SSL). For instance, ws://test.mosquitto.org.

MQTT.RemotePort Property

The port of the MQTT server (default is 1883). The default port for SSL is 8883.

Syntax

getRemotePort(): number;
setRemotePort(remotePort: number): void;

Default Value

1883

Remarks

This property specifies a service port on the remote host to connect to.

A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.

This property is not available at design time.

MQTT.SSLAcceptServerCert Property

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

getSSLAcceptServerCert(): Certificate;
setSSLAcceptServerCert(SSLAcceptServerCert: Certificate): void;

Default Value

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

MQTT.SSLCert Property

The certificate to be used during SSL negotiation.

Syntax

getSSLCert(): Certificate;
setSSLCert(SSLCert: Certificate): void;

Default Value

Remarks

The digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the field to the encoded certificate. To select a certificate, use the store and subject fields.

MQTT.SSLEnabled Property

Whether TLS/SSL is enabled.

Syntax

isSSLEnabled(): boolean;
setSSLEnabled(SSLEnabled: boolean): void;

Default Value

FALSE

Remarks

This setting specifies whether TLS/SSL is enabled in the class. When False (default) the class operates in plaintext mode. When True TLS/SSL is enabled.

TLS/SSL may also be enabled by setting SSLStartMode. Setting SSLStartMode will automatically update this property value.

This property is not available at design time.

MQTT.SSLProvider Property

This specifies the SSL/TLS implementation to use.

Syntax

getSSLProvider(): MqttSSLProviders;
setSSLProvider(SSLProvider: MqttSSLProviders): void;

enum MqttSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected the platform implementation will be used by default in all cases in the JavaScript edition.

Note: The Internal provider is not support at this time.

MQTT.SSLServerCert Property

The server certificate for the last established connection.

Syntax

getSSLServerCert(): Certificate;

Default Value

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

MQTT.Timeout Property

A timeout for the class.

Syntax

getTimeout(): number;
setTimeout(timeout: number): void;

Default Value

60

Remarks

If the Timeout property is set to 0, all operations return immediately, potentially failing with a WOULDBLOCK error if data cannot be sent immediately.

If Timeout is set to a positive value, data is sent in a blocking manner and the class will wait for the operation to complete before returning control. The class will handle any potential WOULDBLOCK errors internally and automatically retry the operation for a maximum of Timeout seconds.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the class .

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

MQTT.User Property

A username if authentication is to be used.

Syntax

getUser(): string;
setUser(user: string): void;

Default Value

""

Remarks

This property can be set to a username if authentication is to be used.

In MQTT 3.1.1, while a User may be specified without a Password, setting a Password without a User is not supported; attempting to do so will cause the server to reject the connection attempt.

In MQTT 5, a Password may be set without a User, allowing the field to be used for credentials other than a password.

This property is not available at design time.

MQTT.Version Property

The MQTT protocol version that the class will conform to.

Syntax

getVersion(): MqttVersions;
setVersion(version: MqttVersions): void;

enum MqttVersions {
  mvV3,
  mvV5
}

Default Value

0

Remarks

This property specifies the version of the MQTT protocol to use. Possible values are:

This property is not available at design time.

MQTT.WillMessage Property

The message that the server should publish in the event of an ungraceful disconnection.

Syntax

getWillMessage(): string;
setWillMessage(willMessage: string): void;

Default Value

""

Remarks

This property may be set before calling Connect to specify to the server a message that should be published on WillTopic if the connection is closed ungracefully. Since it is sent to the server when Connect is called, this property's value cannot be changed when already connected.

Note that the WillMessage will only be sent to the server when Connect is called if WillTopic is set.

Refer to WillTopic for more information about MQTT Will functionality.

This property is not available at design time.

MQTT.WillTopic Property

The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection.

Syntax

getWillTopic(): string;
setWillTopic(willTopic: string): void;

Default Value

""

Remarks

This property may be set before calling Connect to specify the topic name that the server should publish the WillMessage on if the connection is closed ungracefully. Since it is sent to the server when Connect is called, this property's value cannot be changed when already connected.

MQTT Wills

The Will feature of MQTT allows a client to specify to the server a WillMessage to publish (as well as a WillTopic to publish it on) in the event of an ungraceful disconnection.

An "ungraceful disconnection" is any disconnection other than one triggered by calling Disconnect (in which case the server discards the Will message without publishing it). Note that in MQTT 5, the client can set a DisconnectReasonCode of 0x04 before calling Disconnect to instruct the server to publish the Will message anyway.

In addition to the WillTopic and WillMessage properties, the WillQOS setting may be used to specify the Will message's QoS level, and the WillRetain setting to set the Will message's Retain flag. Refer to those settings for more information.

If WillTopic is set to empty string (default) when Connect is called, the class will not send a Will to the server.

In MQTT 5, the "WillDelayInterval" value in the WillProperties config can specify a delay between the ending of the connection and sending the will message, so that the WillMessage will not be sent if a connection is re-established within a certain period of time.

This property is not available at design time.

MQTT.config Method

Sets or retrieves a configuration setting.

Syntax

async mqtt.config(configurationString : string): Promise<string>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

MQTT.connect Method

Connects to the remote host.

Syntax

async mqtt.connect(): Promise<void>

Remarks

This method connects to the remote host specified by RemoteHost and RemotePort. Calling this method is equivalent to setting the Connected property to True.

By default the class will connect in plaintext. To enable SSL set SSLEnabled to True.

In addition, WebSocket connections are supported. To connect using WebSockets specify a hostname beginning with ws:// (plaintext) or wss:// (SSL). For instance, ws://test.mosquitto.org.

When connecting to an MQTT server, the class sends the following information:

• The values of the ClientId, CleanSession, and KeepAliveInterval properties.
• The value of the User property (if non-empty).
• The value of the Password property (if non-empty).
• The values of the WillTopic and WillMessage properties and the WillQOS and WillRetain configuration settings.
• MQTT 5 specific values from ClientTopicAliasMax, SessionExpInterval, ConnectProperties and WillProperties.

If CleanSession is True, check the SessionPresent configuration setting once connected to determine whether the server actually had any session state saved.

Refer to CleanSession, SaveSession, and RestoreSession for more information about MQTT sessions and session state persistence; refer to WillTopic, WillMessage, WillQOS, and WillRetain for more information about MQTT Wills.

Basic Connection Example mqtt1.ClientId = "testClient"; mqtt1.CleanSession = true; mqtt1.KeepAliveInterval = 30; mqtt1.WillTopic = "wills/" + mqtt1.ClientId; mqtt1.WillMessage = mqtt1.ClientId + " was disconnected ungracefully!"; mqtt1.RemoteHost = "mqtt.test-server.com"; mqtt1.RemotePort = 1883; mqtt1.Connect();

MQTT.connectTo Method

Connects to the remote host.

Syntax

async mqtt.connectTo(host : string, port : number): Promise<void>

Remarks

This method connects to the remote host specified by the Host and Port parameters. Calling this method is equivalent to setting the RemoteHost property to Host, setting RemotePort to Port, and then setting the Connected property to True.

By default the class will connect in plaintext. To enable SSL set SSLEnabled to True.

In addition, WebSocket connections are supported. To connect using WebSockets specify a hostname beginning with ws:// (plaintext) or wss:// (SSL). For instance, ws://test.mosquitto.org.

When connecting to an MQTT server, the class sends the following information:

• The values of the ClientId, CleanSession, and KeepAliveInterval properties.
• The value of the User property (if non-empty).
• The value of the Password property (if non-empty).
• The values of the WillTopic and WillMessage properties and the WillQOS and WillRetain configuration settings.
• MQTT 5 specific values from ClientTopicAliasMax, SessionExpInterval, ConnectProperties and WillProperties.

If CleanSession is True, check the SessionPresent configuration setting once connected to determine whether the server actually had any session state saved.

Refer to CleanSession, SaveSession, and RestoreSession for more information about MQTT sessions and session state persistence; refer to WillTopic, WillMessage, WillQOS, and WillRetain for more information about MQTT Wills.

Basic Connection Example mqtt1.ClientId = "testClient"; mqtt1.CleanSession = true; mqtt1.KeepAliveInterval = 30; mqtt1.WillTopic = "wills/" + mqtt1.ClientId; mqtt1.WillMessage = mqtt1.ClientId + " was disconnected ungracefully!"; mqtt1.ConnectTo("mqtt.test-server.com", 1883);

MQTT.disconnect Method

This method disconnects from the remote host.

Syntax

async mqtt.disconnect(): Promise<void>

Remarks

This method disconnects from the remote host. Calling this method is equivalent to setting the Connected property to False.

Refer to the Connected property for more information about MQTT-specific behavior.

MQTT.doEvents Method

Processes events from the internal message queue.

Syntax

async mqtt.doEvents(): Promise<void>

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

MQTT.interrupt Method

Interrupt the current action and disconnects from the remote host.

Syntax

async mqtt.interrupt(): Promise<void>

Remarks

This method will interrupt the current method (if applicable) and cause the class to disconnect from the remote host.

MQTT.publishData Method

Publishes a message with a raw data payload.

Syntax

async mqtt.publishData(topic : string, QOS : number, data : Uint8Array): Promise<void>

Remarks

This method publishes an MQTT message with a raw data payload to the specified Topic at a given QOS level.

Publish Examples // Publish a simple string-based message. mqtt1.PublishMessage("/home/floor1/security/camera2", 1, "Cat detected!"); // Publish a raw data message. byte[] catPicture = ...; mqtt1.PublishData("/home/floor1/security/camera2", 1, catPicture);

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

For example, topic names that begin with $share are reserved for Shared Subscriptions (see Subscribe).

QoS Values

QoS values set the service level for delivery of a message. Values range from 0 to 2 and have the following meanings:

QoS is not guaranteed to be end-to-end in MQTT. The server must downgrade a message's QoS level when delivering it to clients who specified a lower "maximum acceptable" QoS when they subscribed. For example, if Client X subscribes to a topic at QoS 1, and Client Y publishes a message to that topic at QoS 2, the server will downgrade the message to QoS 1 when attempting to deliver it to Client X.

Outbound Message Processing

Outgoing messages with a QoS of 1 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessage*.
5. The MessageOut event is fired.

Outgoing messages with a QoS of 2 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBREC (publish received) packet.
3. The class sends a PUBREL (publish release) packet in response.
4. The class waits to receive a PUBCOMP (publish complete) packet.
5. The MessageAck event is fired.
6. The message is removed from OutgoingMessage*.
7. The MessageOut event is fired.

In MQTT 3.1.1, the RepublishInterval configuration setting, if set to a non-zero value (default), controls how long the class will wait to receive a PUBACK (for QoS 1) or PUBREC (for QoS 2) before automatically republishing an outgoing message. In MQTT 5, messages are only republished if the client is disconnected before receiving a PUBACK or PUBREC.

MQTT 5 Notes

MQTT 5 makes a number of new features available when publishing messages, including:

• TopicAlias - Set an integer alias along with the topic name when first publishing a message. When publishing additional messages to the same topic if TopicAlias is set the Topic parameter does not need to be set. This reduces the size of the message sent to the server.
• Request / Response - Set a ResponseTopic which identifies the topic to which a receiver should respond.

Some of these features require configuration settings to be set prior to publishing. In these cases, note that these configuration settings will continue to be applicable to any future PUBLISH packets sent with the method unless they are updated or reset. To prevent clear a previously set configuration setting, set it to "", or -1 (for integers).

See the OutgoingMessageProperties configuration setting for additional details.

MQTT.publishMessage Method

Publishes a message with a string payload.

Syntax

async mqtt.publishMessage(topic : string, QOS : number, message : string): Promise<void>

Remarks

This method publishes an MQTT message with a string payload to the specified Topic at a given QOS level.

Publish Examples // Publish a simple string-based message. mqtt1.PublishMessage("/home/floor1/security/camera2", 1, "Cat detected!"); // Publish a raw data message. byte[] catPicture = ...; mqtt1.PublishData("/home/floor1/security/camera2", 1, catPicture);

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

For example, topic names that begin with $share are reserved for Shared Subscriptions (see Subscribe).

QoS Values

QoS values set the service level for delivery of a message. Values range from 0 to 2 and have the following meanings:

QoS is not guaranteed to be end-to-end in MQTT. The server must downgrade a message's QoS level when delivering it to clients who specified a lower "maximum acceptable" QoS when they subscribed. For example, if Client X subscribes to a topic at QoS 1, and Client Y publishes a message to that topic at QoS 2, the server will downgrade the message to QoS 1 when attempting to deliver it to Client X.

Outbound Message Processing

Outgoing messages with a QoS of 1 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessage*.
5. The MessageOut event is fired.

Outgoing messages with a QoS of 2 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBREC (publish received) packet.
3. The class sends a PUBREL (publish release) packet in response.
4. The class waits to receive a PUBCOMP (publish complete) packet.
5. The MessageAck event is fired.
6. The message is removed from OutgoingMessage*.
7. The MessageOut event is fired.

In MQTT 3.1.1, the RepublishInterval configuration setting, if set to a non-zero value (default), controls how long the class will wait to receive a PUBACK (for QoS 1) or PUBREC (for QoS 2) before automatically republishing an outgoing message. In MQTT 5, messages are only republished if the client is disconnected before receiving a PUBACK or PUBREC.

MQTT 5 Notes

MQTT 5 makes a number of new features available when publishing messages, including:

• TopicAlias - Set an integer alias along with the topic name when first publishing a message. When publishing additional messages to the same topic if TopicAlias is set the Topic parameter does not need to be set. This reduces the size of the message sent to the server.
• Request / Response - Set a ResponseTopic which identifies the topic to which a receiver should respond.

Some of these features require configuration settings to be set prior to publishing. In these cases, note that these configuration settings will continue to be applicable to any future PUBLISH packets sent with the method unless they are updated or reset. To prevent clear a previously set configuration setting, set it to "", or -1 (for integers).

See the OutgoingMessageProperties configuration setting for additional details.

MQTT.reset Method

Reset the class.

Syntax

async mqtt.reset(): Promise<void>

Remarks

This method will reset the class's properties to their default values.

MQTT.restoreSession Method

Restores session state data.

Syntax

async mqtt.restoreSession(stateData : string): Promise<void>

Remarks

This method restores previously-saved session state data and sets CleanSession to False. If the SessionStateFile configuration setting is set, the class will use the contents of that file to restore the session state data, ignoring the string passed to this method.

Depending on the elapsed time between connections the server may discard any previously saved session data on its side.

In MQTT 3.1.1, the time after which the server discards saved session data is not defined in the protocol specification and may vary between implementations. As a result, when re-connecting it may not be known if the server is capable of restoring a previous session.

To determine if a session can be restored on connection, set CleanSession to False, ClientId to the same value used in the initial connection, and call ConnectTo.

When the Connected event fires, query the SessionPresent configuration setting. If SessionPresent is True the session should be restored by calling RestoreSession. If SessionPresent is False the session should not be restored so that the connection proceeds as a clean session.

Note: Not all servers support the use of SessionPresent.

Restore Session Example (Query SessionPresent) mqtt1.CleanSession = false; mqtt1.ClientId = clientId; mqtt1.OnConnected += (s, e) => { if (mqtt1.Config("SessionPresent").ToLower() == "true") mqtt1.RestoreSession(sessionStr); }; mqtt1.ConnectTo(host,port);

If it is known that the server has not discarded the session state, for instance from familiarity with the server implementation and its behavior, then a simplified procedure can be performed. Simply set ClientId to the value used in the initial connection, call RestoreSession, and then call ConnectTo.

Restore Session Example (Server Status Known) mqtt1.ClientId = clientId; mqtt1.RestoreSession(sessionStr); mqtt1.ConnectTo(host,port);

Refer to CleanSession and SaveSession for more information.

MQTT 5 Notes

In MQTT 5, the time after which the server discards saved session data is controlled by the SessionExpInterval. The server is required to store state data for the amount of time specified by this value, at which point it is required to delete it.

This feature allows the client to use its own time-based logic to determine whether it is necessary to call RestoreSession.

MQTT.saveSession Method

Saves session state data.

Syntax

async mqtt.saveSession(): Promise<string>

Remarks

This method saves session state data currently held by the class, returning it as a string that can later be used to restore it. If the SessionStateFile configuration setting is set, the class will also write the session state data to that file (creating and/or overwriting it, as necessary).

Refer to CleanSession and RestoreSession for more information.

MQTT.subscribe Method

Subscribes the class to one or more topic filters.

Syntax

async mqtt.subscribe(topicFilter : string, QOS : number): Promise<void>

Remarks

This method subscribes the class to one or more topic filters using one or more QoS levels.

The Subscribed event will fire once for each topic filter given once the server acknowledges the subscription request(s). Keep in mind that the server is allowed to start publishing messages before it sends the acknowledgment.

It is legal to call Subscribe again for the same topic filter at any time, and pass a different QoS value at that time if desired. The Subscribed event will fire as normal when doing this.

Subscribe Examples // Subscribed event handler. mqtt1.OnSubscribed += (s, e) => { if (e.ResponseCode <= 2) Console.WriteLine("Subscribed to " + e.TopicFilter + " at QoS " + e.QOS + "."); else Console.WriteLine("Failed to subscribe to " + e.TopicFilter + "."); }; // Basic, subscribe to some topic filters, all at the same QoS level. mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 2); // A bit more advanced, subscribe to the same topic filters, but at different QoS levels. mqtt1.Config("TopicQOSArray=1,2,2"); // The 0 is ignored here since we've specified individual QoS values explicitly. mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 0);

Topic Filters

The string passed for TopicFilter must contain one or more valid topic filter strings, separated by the delimiter string specified by the TopicDelimiter configuration setting (, by default).

A topic filter is a case-sensitive string between 1 and 65535 characters long (per topic filter), and can include any character other than the null character. Certain characters have special meanings:

• / - The topic level separator
• # - The multi-level wildcard (zero or more levels)
• + - The single-level wildcard (exactly one level)
• Leading $ - Denotes a "system topic"

Note that both types of wildcards may be used in the same topic filter.

Topic Level Separators

The topic level separator, as its name implies, is used to separate a topic name (or in this case, filter) into "levels". This concept of topic names having levels is what allows topic filters to match multiple topics through the use of wildcards. For the examples in the next sections, assume the following topics exist:

• home/floor1
• home/floor1/livingRoom
• home/floor1/livingRoom/temperature
• home/floor1/kitchen/temperature
• home/floor1/kitchen/fridge/temperature
• home/floor2/bedroom1
• home/floor2/bedroom1/temperature

Multi-level Wildcards

The multi-level wildcard character is used at the end of a topic filter to make it match an arbitrary number of successive levels. For example, the topic filter home/floor1/# would match the following topics:

• home/floor1 (because it can match zero levels)
• home/floor1/livingRoom
• home/floor1/livingRoom/temperature
• home/floor1/kitchen/temperature
• home/floor1/kitchen/fridge/temperature

Here are some things to keep in mind when using a multi-level wildcard:

• # must always be the last character in the topic filter (e.g., home/floor1/#/livingRoom is not valid)
• # must always be preceded by a / (e.g., home/floor1# is not valid)
• # by itself is a valid topic filter, and will match all topics except system topics

Single-level Wildcards

The single-level wildcard character is used between two /s in a topic filter to make it any single level. For example, the topic filter home/floor1/+/temperature would match the following topics:

• home/floor1/livingRoom/temperature
• home/floor1/kitchen/temperature

Any number of single-level wildcards are supported in a topic filter. For example, the topic filter home/+/+/temperature would match the following topics:

• home/floor1/livingRoom/temperature
• home/floor1/kitchen/temperature
• home/floor2/bedroom1/temperature

Here are some things to keep in mind when using single-level wildcards:

• + must always be separated from other levels using /s (e.g., home/floor1+ is invalid, but +/floor1/+ is valid)
• + by itself is a valid topic filter, and will match all topics with exactly one level in their name except system topics
• Remember, topic names with a leading / have a zero-length string as their first level. So a topic named /people would be matched by the topic filter +/+, but not by +
• + must match exactly one level. So for example, the topic filter home/floor1/kitchen/+/temperature would match /home/floor1/kitchen/fridge/temperature, but not home/floor1/kitchen/temperature

System Topics

Topic names which begin with a $ are "system topics". Typically, the server prohibits clients from publishing to such topics, but permits subscribing to them. As described above, wildcards will never match the first level of a topic if it begins with a $.

Note that MQTT 5 defines shared subscriptions, a special type of system topic. See the MQTT 5 notes below for more.

Requested QoS Values

The QoS value passed for QOS will be used to subscribe to all given topic filters, unless the TopicQOSArray configuration setting is used to specify explicit QoS values for each individual topic filter.

QoS values range from 0 to 2 and have the following meanings:

QoS is not guaranteed to be end-to-end in MQTT. The server must downgrade a message's QoS level when delivering it to clients who specified a lower "maximum acceptable" QoS when they subscribed. For example, if Client X subscribes to a topic at QoS 1, and Client Y publishes a message to that topic at QoS 2, the server will downgrade the message to QoS 1 when attempting to deliver it to Client X.

MQTT 5 Notes

MQTT 5 defines several new features that apply to subscriptions, including Shared Subscriptions, Subscription Options and Subscription Identifiers. Some of these features require configuration settings to be set prior to calling Subscribe. In these cases, note that thee configuration settings will continue to be applied to any future SUBSCRIBE packets sent with the method unless they are updated or reset. To prevent a value from being included in packets after it has been set previously, set it to "", or -1 (for integers).

Shared Subscriptions

Shared subscriptions allow a client to subscribe to a topic as a part of a group of clients, where each client in the group is subscribing to the same topic. Each message published to such a group will be delivered to only one client in the group, making shared subscriptions useful when several clients share the processing of the publications in parallel.

Subscribing to a topic as part of a shared subscription is similar to a normal subscription, the only difference being the syntax of the topic filter passed to the Subscribe method.

The format of this filter is $share/{ShareName}/{filter}, where

• $share is a string literal identifying the subscription as a shared subscriptions.
• {ShareName} is a string at least one character long that must not include /, + or #.
• {filter} is a full topic filter formatted just as in a non-shared subscription.

Unsubscribing is done by passing the same value to the Unsubscribe method.

A shared subscription behaves the same way as a non-shared subscription, except that the $share/{ShareName} portion of the topic filter is ignored when filtering publication topics, and that the server will distribute delivery of messages amongst the group, with each message delivered to only one client per group per topic.

Shared subscriptions can be implemented without any additional properties or methods, simply by using the Subscribe and Unsubscribe methods. However, if it is necessary to verify that the feature is supported by the server, check the "SharedSubscriptionAvailable" value of the ConnAckProperties config.

Shared Subscription Example mqtt1.Subscribe("$share/myShareGroup/myTopicFilter/subTopic", 2);

Subscription Options

MQTT 5 defines three subscription options which can be configured on a per-subscription basis and are useful for message bridge applications:

• No Local flag - indicates that messages must not be forwarded to a connection with a ClientId equal to the ClientId of the publishing connection (cannot be set on a shared subscription).
• Retain As Published flag - indicates that messages forwarded using this subscription keep the retain flag they were published with (as opposed to always being set to False).
• Retain Handling option - specifies whether retained messages are sent when the subscription is established. Possible values are:

  0	Send retained messages at the time of the subscribe
  1	Send retained messages at subscribe only if the subscription does not currently exist
  2	Do not send retained messages at the time of the subscribe

To specify these options in the subscribe method, the class has three corresponding configuration settings (TopicNLArray, TopicRAPArray and TopicRHArray) which each take a string value in the form of a comma-separated list. Each element in the list corresponds to a topic filter passed to the Subscribe method, as with TopicQOSArray.

If the subscription is only for one topic, these lists would have only one value. If the number of elements in the string is less than the number of topic filters in the subscription, the final element will be applied to all remaining topics.

Subscription Options Example mqtt1.Connected = true; mqtt1.Config("TopicNLArray=true, false, true"); // TestTopic1 = true, TestTopic2 = false, TestTopic3 = true mqtt1.Config("TopicRAPArray=false"); // TestTopic1 = false, TestTopic2 = false, TestTopic3 = false mqtt1.Config("TopicRHArray=1, 0"); // // TestTopic1 = 1, TestTopic2 = 0, TestTopic3 = 0 mqtt1.Subscribe("TestTopic1, TestTopic2, TestTopic3", 1);

Subscription Identifiers

MQTT 5 allows clients to specify a numeric subscription identifier which will be returned with messages delivered for that subscription.

To do so with the class, set the SubscriptionIdentifier configuration setting before calling Subscribe. To update the identifier, call Subscribe with a new SubscriptionIdentifier.

To verify that a server supports subscription identifiers, check the "SubscriptionIdentifiersAvailable" value in the ConnAckProperties configuration setting. See the SubscriptionIdentifiers property of the MQTTMessage type for details on returning the ids associated with messages.

Note that a topic may have multiple identifiers associated with it (due to wildcards), and the same identifier may be associated with multiple topics.

Subscription Options Example mqtt1.Connected = true; mqtt1.OnMessageAck += (o, e) => { String ids = mqtt1.IncomingMessages[e.Index].SubscriptionIdentifiers; // ids = "123,321" }; mqtt1.Config("SubscriptionIdentifier=123"); mqtt1.Subscribe("test_topic/subtopic", 1); mqtt1.Config("SubscriptionIdentifier=321"); mqtt1.Subscribe("test_topic/+", 1); mqtt2.Connected = true; mqtt2.PublishMessage("test_topic/subtopic", 1, "hello world");

MQTT.unsubscribe Method

Unsubscribes the class from one or more topic filters.

Syntax

async mqtt.unsubscribe(topicFilter : string): Promise<void>

Remarks

This method unsubscribes the class from one or more topic filters. The string passed for TopicFilter must contain one or more valid topic filter strings, separated by the delimiter string specified by the TopicDelimiter configuration setting (, by default).

The Unsubscribed event will fire when the server has acknowledged the unsubscribe request. However, note that the server's acknowledgment doesn't specify which topics a client was unsubscribed from. Please refer to the Unsubscribed event for more information.

To successfully unsubscribe from a topic filter, the exact filter must be passed to Unsubscribe, regardless of whether or not if contains wildcards. The server ignores any topic filters in an unsubscribe request which do not exactly match that of an existing subscription.

It is impossible to partially unsubscribe from a topic filter with wildcards (that is, if a client is subscribed to a topic filter home/floor1/+/#, requesting to unsubscribe from a topic filter home/floor1/livingRoom/temperature does nothing).

Similarly, because topic filters in an unsubscribe request are simply compared character-by-character with existing subscriptions rather than being interpreted, it is not possible to perform an action such as unsubscribing from all currently subscribed topics by passing "#" for TopicFilter.

Unsubscribe Example // Unsubscribe from topic filters; have to use the exact same strings as before. If this // was to be called after calling the code example shown for the Subscribe() method, we // would still be subscribed to the "home" topic filter. mqtt1.Unsubscribe("home/floor1/+/temperature,home/floor2/#");

MQTT.Connected Event

This event is fired immediately after a connection completes (or fails).

Syntax

mqtt.on('Connected', listener: (e: {readonly statusCode: number, readonly description: string}) => void )

Remarks

If the connection is made normally, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

Please refer to the Error Codes section for more information.

MQTT.ConnectionStatus Event

This event is fired to indicate changes in the connection state.

Syntax

mqtt.on('ConnectionStatus', listener: (e: {readonly connectionEvent: string, readonly statusCode: number, readonly description: string}) => void )

Remarks

The ConnectionStatus event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:

MQTT.Disconnected Event

This event is fired when a connection is closed.

Syntax

mqtt.on('Disconnected', listener: (e: {readonly statusCode: number, readonly description: string}) => void )

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Transmission Control Protocol (TCP/IP) subsystem. Description contains a description of this code. The value of StatusCode is equal to the value of the TCP/IP error.

Please refer to the Error Codes section for more information.

MQTT.Error Event

Fired when information is available about errors during data delivery.

Syntax

mqtt.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

MQTT.Log Event

Fires once for each log message.

Syntax

mqtt.on('Log', listener: (e: {readonly logLevel: number, readonly message: string, readonly logType: string}) => void )

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:

LogType identifies the type of log entry. Possible values are:

• Info: General information about the class.
• Packet: Packet content logging.
• Reconnect: Reconnection status messages.
• Session: Session status messages.

MQTT.MessageAck Event

Fired when an incoming or outgoing message has completed all acknowledgment steps.

Syntax

mqtt.on('MessageAck', listener: (e: {readonly packetId: number, readonly direction: number, readonly index: number, readonly responseCode: number}) => void )

Remarks

The MessageAck event fires once an incoming or outgoing message with a QoS of 1 or 2 has successfully completed all acknowledgment steps as required by its QoS level. (Note that this event does not fire for messages with a QoS of 0 since they do not require acknowledgment.)

• PacketId: The Id of the original PUBLISH packet for the message.
• Direction: Shows whether the client (0) or the server (1) is sending the data.
• Index: The index at which the message resides in either the IncomingMessage* properties or OutgoingMessage* properties.
• ResponseCode: In MQTT 5, all response packets contain Reason Codes. This argument contains any code encountered in message acknowledgment packets (PUBACK, PUBREC, PUBREL, PUBCOMP).

Possible MQTT-specific values for ResponseCode are:

Inbound Message Processing

Incoming messages with a QoS of 1 follow these steps:

1. The message is added to IncomingMessage* when the class receives the PUBLISH packet.
2. The class sends a PUBACK (publish acknowledgment) packet in response.
3. The MessageAck event is fired.
4. The message is removed from IncomingMessage*.
5. The MessageIn event is fired.

Incoming messages with a QoS of 2 follow these steps:

1. The message is added to IncomingMessage* when the class receives the PUBLISH packet.
2. The class sends a PUBREC (publish received) packet in response.
3. The class waits to receive a PUBREL (publish release) packet.
4. The class sends a PUBCOMP (publish complete) packet in response.
5. The MessageAck event is fired.
6. The message is removed from IncomingMessage*.
7. The MessageIn event is fired.

Outbound Message Processing

Outgoing messages with a QoS of 1 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessage*.
5. The MessageOut event is fired.

Outgoing messages with a QoS of 2 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessage*.
2. The class waits to receive a PUBREC (publish received) packet.
3. The class sends a PUBREL (publish release) packet in response.
4. The class waits to receive a PUBCOMP (publish complete) packet.
5. The MessageAck event is fired.
6. The message is removed from OutgoingMessage*.
7. The MessageOut event is fired.

In MQTT 3.1.1, the RepublishInterval configuration setting, if set to a non-zero value (default), controls how long the class will wait to receive a PUBACK (for QoS 1) or PUBREC (for QoS 2) before automatically republishing an outgoing message. In MQTT 5, messages are only republished if the client is disconnected before receiving a PUBACK or PUBREC.

MQTT.MessageIn Event

Fired when an incoming message has been received and/or fully acknowledged.

Syntax

mqtt.on('MessageIn', listener: (e: {readonly packetId: number, readonly topic: string, readonly QOS: number, readonly message: string, readonly messageB: Uint8Array, readonly retained: boolean, readonly duplicate: boolean}) => void )

Remarks

The MessageIn event fires once for each incoming message either immediately after it is received (QoS 0), or after it has been fully acknowledged (QoS 1 and 2).

• PacketId: The message packet Id. This will always be -1 if QOS is 0.
• Topic: The message's topic string.
• QOS: The message's QoS level.
• Message: The message data.
• Retained: Whether or not this message was received as a result of subscribing to a topic.
• Duplicate: Whether or not the server has indicated that this message is a duplicate of another message sent previously.

Refer to MessageAck for more information about QoS 1 and 2 message processing steps.

// MessageIn event handler. mqtt1.OnMessageIn += (s, e) => { Console.WriteLine("Received message from topic '" + e.Topic + "' with QoS " + e.QOS + ":"); Console.WriteLine(e.Message); };

MQTT.MessageOut Event

Fired when an outgoing message has been sent and/or fully acknowledged.

Syntax

mqtt.on('MessageOut', listener: (e: {readonly packetId: number, readonly topic: string, readonly QOS: number, readonly message: string, readonly messageB: Uint8Array, readonly retained: boolean, readonly duplicate: boolean}) => void )

Remarks

The MessageOut event fires once for each outgoing message either immediately after it is sent (QoS 0), or after it has been fully acknowledged by the receiver (QoS 1 and 2).

• PacketId: The message packet Id. This will always be -1 if QOS is 0.
• Topic: The message's topic string.
• QOS: The message's QoS level.
• Message: The message data.
• Retained: Whether or not this message was sent with the "Retain" flag set.
• Duplicate: Whether or not this message was sent with the "Duplicate" flag set.

Refer to MessageAck for more information about QoS 1 and 2 message processing steps.

// MessageOut event handler. mqtt1.OnMessageOut += (s, e) => { Console.WriteLine("Send message to topic '" + e.Topic + "' with QoS " + e.QOS + ":"); Console.WriteLine(e.Message); };

MQTT.ReadyToSend Event

Fired when the class is ready to send data.

Syntax

mqtt.on('ReadyToSend', listener: (e: {}) => void )

Remarks

The ReadyToSend event indicates that the underlying TCP/IP subsystem is ready to accept data after a call to PublishData or PublishMessage fails due to a WOULDBLOCK condition. The event is also fired immediately after a connection to the remote host is established.

MQTT.SSLServerAuthentication Event

Fired after the server presents its certificate to the client.

Syntax

mqtt.on('SSLServerAuthentication', listener: (e: {readonly certEncoded: string, readonly certEncodedB: Uint8Array, readonly certSubject: string, readonly certIssuer: string, readonly status: string, accept: boolean}) => void )

Remarks

This event fires with information about the server certificate. The Status property shows why verification failed (otherwise, Status contains the string OK). To manually accept an untrusted certificate, the SSLAcceptAnyServerCert setting must be set to True before initiating the connection.

MQTT.SSLStatus Event

Fired when secure connection progress messages are available.

Syntax

mqtt.on('SSLStatus', listener: (e: {readonly message: string}) => void )

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

MQTT.Subscribed Event

Fires for each topic filter subscription the server acknowledges.

Syntax

mqtt.on('Subscribed', listener: (e: {readonly topicFilter: string, readonly QOS: number, readonly responseCode: number}) => void )

Remarks

This event fires each time the server has acknowledged a topic filter subscription request (that is, calling Subscribe with multiple topic filters will cause this to fire multiple times).

• TopicFilter: The topic filter subscription request being acknowledged.
• QOS: The QoS level the server has granted for the subscription.
• ResponseCode: Indicates the result of the subscription request.

Possible values for ResponseCode are:

• 0: Success, QoS 0 granted
• 1: Success, QoS 1 granted
• 2: Success, QoS 2 granted
• 128: Unspecified error
• 131: Implementation specific error; The SUBSCRIBE is valid but the Server does not accept it.
• 135: Not authorized; The Client is not authorized to make this subscription.
• 143: Topic Filter invalid; The Topic Filter is correctly formed but is not allowed for this Client.
• 145: Packet Identifier in use
• 151: Quota exceeded; An implementation or administrative imposed limit has been exceeded.
• 158: Shared Subscriptions not supported
• 161: Shared Subscriptions not supported
• 162: Wildcard Subscriptions not supported

Keep in mind that the server may have chosen to grant a lower QoS than was requested under certain circumstances (e.g., if the server doesn't support the requested QoS).

Note: the server is not required to acknowledge a subscription before it begins delivering messages for that subscription.

MQTT.Unsubscribed Event

Fires when the server has acknowledged an unsubscribe request.

Syntax

mqtt.on('Unsubscribed', listener: (e: {readonly topicFilters: string, readonly responseCode: number}) => void )

Remarks

This event fires when the server has acknowledged an unsubscribe request sent with Unsubscribe (that is, unlike the Subscribed event, this event fires only once for each call to Unsubscribe, regardless of how many topic filters are passed to it).

Note that in MQTT 3.1.1, servers do not specify which topic filters a client has been successfully unsubscribed in their acknowledgments. In fact, they will still acknowledge an unsubscribe request even if none of the topic filters included matched existing subscriptions. It is up to the client to keep track of what topics it is subscribed to; the TopicFilters parameter is provided as a convenience, its value simply a copy of the value passed to Unsubscribe originally.

Possible values for ResponseCode are:

• 0: Success; The subscription is deleted.
• 17: No subscription existed; No matching Topic Filter is being used by the Client.
• 128: Unspecified error; The unsubscribe could not be completed and the Server either does not wish to reveal the reason or none of the other Reason Codes apply.
• 131: Implementation specific error; The UNSUBSCRIBE is valid but the Server does not accept it.
• 135: Not authorized; The Client is not authorized to unsubscribe.
• 143: Topic Filter invalid; The Topic Filter is correctly formed but is not allowed for this Client.
• 145: Packet Identifier in use; The specified Packet Identifier is already in use.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

public Certificate();

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public Certificate(String certificateFile);

Opens CertificateFile and reads out the contents as an X.509 public key.

public Certificate(byte[] certificateData);

Parses CertificateData as an X.509 public key.

public Certificate(int certStoreType, String store, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

Firewall Type

The firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall and the .

Fields

Constructors

public Firewall();

MQTTMessage Type

An MQTT message.

Remarks

This type represents an MQTT message.

Fields

Config Settings (class ipworksmq.mqtt)

MQTT Config Settings

{ 
  "ClientTopicAliasMax":"20",
  "MaximumPacketSize":"128000",
  "ReceiveMaximum":"12",
  "RequestResponseInformation":"false",
  "RequestProblemInformation":"true",
  "SessionExpInterval":"1234"
}

{
  "ContentType":"plain/text",
  "CorrelationData":"00000000",
  "MessageExpInterval":"1000",
  "PayloadFormatIndicator":"1",
  "ResponseTopic": "ResponseTopic",
  "TopicAlias":"1",
  "UserProperty":"prp1:val1",
  "UserProperty":"prp2:val2"
}

{
"ContentType":"text/plain",
"CorrelationData":"00000000",
"MessageExpInterval":"3600",
"PayloadFormatIndicator":"1",
"ResponseTopic": "ResponseTopic",
"WillDelayInterval":"10"
}

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Trappable Errors (class ipworksmq.mqtt)

MQTT Errors

WebSocket Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors