MQTT Class

Properties   Methods   Events   Config Settings   Errors  

A lightweight, fully-featured MQTT client implementation.

Class Name

IPWorksIoT_MQTT

Procedural Interface

 ipworksiot_mqtt_open();
 ipworksiot_mqtt_close($res);
 ipworksiot_mqtt_register_callback($res, $id, $function);
 ipworksiot_mqtt_get_last_error($res);
 ipworksiot_mqtt_get_last_error_code($res);
 ipworksiot_mqtt_set($res, $id, $index, $value);
 ipworksiot_mqtt_get($res, $id, $index);
 ipworksiot_mqtt_do_config($res, $configurationstring);
 ipworksiot_mqtt_do_connect($res);
 ipworksiot_mqtt_do_connectto($res, $host, $port);
 ipworksiot_mqtt_do_disconnect($res);
 ipworksiot_mqtt_do_doevents($res);
 ipworksiot_mqtt_do_interrupt($res);
 ipworksiot_mqtt_do_publishdata($res, $topic, $qos, $data);
 ipworksiot_mqtt_do_publishmessage($res, $topic, $qos, $message);
 ipworksiot_mqtt_do_reset($res);
 ipworksiot_mqtt_do_restoresession($res, $statedata);
 ipworksiot_mqtt_do_savesession($res);
 ipworksiot_mqtt_do_subscribe($res, $topicfilter, $qos);
 ipworksiot_mqtt_do_unsubscribe($res, $topicfilter);

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.

CleanSession Property (IPWorksIoT_MQTT Class)

Determines whether a clean session is used once connected.

Object Oriented Interface

public function getCleanSession();


public function setCleanSession($value);

Procedural Interface

ipworksiot_mqtt_get($res, 1 );


ipworksiot_mqtt_set($res, 1, $value );

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.

Data Type

Boolean

ClientId Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getClientId();


public function setClientId($value);

Procedural Interface

ipworksiot_mqtt_get($res, 2 );


ipworksiot_mqtt_set($res, 2, $value );

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 fails with an error.

This property is not available at design time.

Data Type

String

Connected Property (IPWorksIoT_MQTT Class)

Triggers a connection or disconnection.

Object Oriented Interface

public function getConnected();


public function setConnected($value);

Procedural Interface

ipworksiot_mqtt_get($res, 3 );


ipworksiot_mqtt_set($res, 3, $value );

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.

Data Type

Boolean

FirewallAutoDetect Property (IPWorksIoT_MQTT Class)

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Object Oriented Interface

public function getFirewallAutoDetect();


public function setFirewallAutoDetect($value);

Procedural Interface

ipworksiot_mqtt_get($res, 4 );


ipworksiot_mqtt_set($res, 4, $value );

Default Value

false

Remarks

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Data Type

Boolean

FirewallType Property (IPWorksIoT_MQTT Class)

This property determines the type of firewall to connect through.

Object Oriented Interface

public function getFirewallType();


public function setFirewallType($value);

Procedural Interface

ipworksiot_mqtt_get($res, 5 );


ipworksiot_mqtt_set($res, 5, $value );

Default Value

0

Remarks

This property determines the type of firewall to connect through. The applicable values are as follows:

Data Type

Integer

FirewallHost Property (IPWorksIoT_MQTT Class)

This property contains the name or IP address of firewall (optional).

Object Oriented Interface

public function getFirewallHost();


public function setFirewallHost($value);

Procedural Interface

ipworksiot_mqtt_get($res, 6 );


ipworksiot_mqtt_set($res, 6, $value );

Default Value

''

Remarks

This property contains the name or IP address of firewall (optional). If a FirewallHost is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

Data Type

String

FirewallPassword Property (IPWorksIoT_MQTT Class)

This property contains a password if authentication is to be used when connecting through the firewall.

Object Oriented Interface

public function getFirewallPassword();


public function setFirewallPassword($value);

Procedural Interface

ipworksiot_mqtt_get($res, 7 );


ipworksiot_mqtt_set($res, 7, $value );

Default Value

''

Remarks

This property contains a password if authentication is to be used when connecting through the firewall. If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

Data Type

String

FirewallPort Property (IPWorksIoT_MQTT Class)

This property contains the transmission control protocol (TCP) port for the firewall Host .

Object Oriented Interface

public function getFirewallPort();


public function setFirewallPort($value);

Procedural Interface

ipworksiot_mqtt_get($res, 8 );


ipworksiot_mqtt_set($res, 8, $value );

Default Value

0

Remarks

This property contains the transmission control protocol (TCP) port for the firewall FirewallHost. See the description of the FirewallHost property for details.

Note: This property is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

Data Type

Integer

FirewallUser Property (IPWorksIoT_MQTT Class)

This property contains a user name if authentication is to be used connecting through a firewall.

Object Oriented Interface

public function getFirewallUser();


public function setFirewallUser($value);

Procedural Interface

ipworksiot_mqtt_get($res, 9 );


ipworksiot_mqtt_set($res, 9, $value );

Default Value

''

Remarks

This property contains a user name if authentication is to be used connecting through a firewall. If the FirewallHost is specified, this property and FirewallPassword properties are used to connect and authenticate to the given Firewall. If the authentication fails, the class fails with an error.

Data Type

String

IncomingMessageCount Property (IPWorksIoT_MQTT Class)

The number of records in the IncomingMessage arrays.

Object Oriented Interface

public function getIncomingMessageCount();

Procedural Interface

ipworksiot_mqtt_get($res, 10 );

Default Value

0

Remarks

This property controls the size of the following arrays:

• IncomingMessageContentType
• IncomingMessageCorrelationData
• IncomingMessageDuplicate
• IncomingMessageMessage
• IncomingMessageMessageExpInterval
• IncomingMessagePacketId
• IncomingMessagePayloadFormatIndicator
• IncomingMessageQoS
• IncomingMessageResponseTopic
• IncomingMessageRetained
• IncomingMessageState
• IncomingMessageSubscriptionIdentifiers
• IncomingMessageTopic
• IncomingMessageTopicAlias

The array indices start at 0 and end at IncomingMessageCount - 1.

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

Data Type

Integer

IncomingMessageContentType Property (IPWorksIoT_MQTT Class)

String describing the content of the message.

Object Oriented Interface

public function getIncomingMessageContentType($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 11 , $incomingmessageindex);

Default Value

''

Remarks

String describing the content of the message. Defined by the sending and receiving application.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

String

IncomingMessageCorrelationData Property (IPWorksIoT_MQTT Class)

Used by the sender of the request message to identify which request the response message is for when it is received.

Object Oriented Interface

public function getIncomingMessageCorrelationData($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 12 , $incomingmessageindex);

Default Value

''

Remarks

Used by the sender of the request message to identify which request the response message is for when it is received.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

String

IncomingMessageDuplicate Property (IPWorksIoT_MQTT Class)

Whether or not this message's Duplicate flag is set.

Object Oriented Interface

public function getIncomingMessageDuplicate($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 13 , $incomingmessageindex);

Default Value

false

Remarks

Whether or not this message's Duplicate flag is set.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Boolean

IncomingMessageMessage Property (IPWorksIoT_MQTT Class)

This message's raw data payload.

Object Oriented Interface

public function getIncomingMessageMessage($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 14 , $incomingmessageindex);

Default Value

''

Remarks

This message's raw data payload.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Binary String

IncomingMessageMessageExpInterval Property (IPWorksIoT_MQTT Class)

The lifetime of the message in seconds specified by the sender.

Object Oriented Interface

public function getIncomingMessageMessageExpInterval($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 15 , $incomingmessageindex);

Default Value

0

Remarks

The lifetime of the message in seconds specified by the sender.

For outgoing messages, the value is useful for instructing the server to delete its copies of the message for any subscribers it has not been able to start delivery to.

For incoming messages, the value sent by the server is the lifetime specified by the sender minus the time the message has been waiting in the server.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

IncomingMessagePacketId Property (IPWorksIoT_MQTT Class)

This message's packet Id.

Object Oriented Interface

public function getIncomingMessagePacketId($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 16 , $incomingmessageindex);

Default Value

0

Remarks

This message's packet Id.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

IncomingMessagePayloadFormatIndicator Property (IPWorksIoT_MQTT Class)

Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data.

Object Oriented Interface

public function getIncomingMessagePayloadFormatIndicator($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 17 , $incomingmessageindex);

Default Value

0

Remarks

Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data. Possible values are:

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

IncomingMessageQoS Property (IPWorksIoT_MQTT Class)

This message's QoS level.

Object Oriented Interface

public function getIncomingMessageQoS($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 18 , $incomingmessageindex);

Default Value

0

Remarks

This message's QoS level. Possible values are:

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

IncomingMessageResponseTopic Property (IPWorksIoT_MQTT Class)

String used as the topic name for a response message.

Object Oriented Interface

public function getIncomingMessageResponseTopic($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 19 , $incomingmessageindex);

Default Value

''

Remarks

String used as the topic name for a response message.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

String

IncomingMessageRetained Property (IPWorksIoT_MQTT Class)

Whether or not this message's Retain flag is set.

Object Oriented Interface

public function getIncomingMessageRetained($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 20 , $incomingmessageindex);

Default Value

false

Remarks

Whether or not this message's Retain flag is set.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Boolean

IncomingMessageState Property (IPWorksIoT_MQTT Class)

This message's current state.

Object Oriented Interface

public function getIncomingMessageState($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 21 , $incomingmessageindex);

Default Value

0

Remarks

This message's current state.

Possible Outgoing Message States:

Possible Incoming Message States:

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

IncomingMessageSubscriptionIdentifiers Property (IPWorksIoT_MQTT Class)

A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered.

Object Oriented Interface

public function getIncomingMessageSubscriptionIdentifiers($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 22 , $incomingmessageindex);

Default Value

''

Remarks

A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered.

This property is only applicable to incoming messages.

If SubscriptionIdentifier is set when subscribing, it will be included in any messages delivered by the broker for the topics specified in that packet.

See the Subscribe method for more details.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

String

IncomingMessageTopic Property (IPWorksIoT_MQTT Class)

This message's topic.

Object Oriented Interface

public function getIncomingMessageTopic($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 23 , $incomingmessageindex);

Default Value

''

Remarks

This message's topic.

MQTT 5 Notes:

If this value is empty, the IncomingMessageTopicAlias property holds the assigned alias for the topic.

If this value is not empty and IncomingMessageTopicAlias is non-zero,

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

String

IncomingMessageTopicAlias Property (IPWorksIoT_MQTT Class)

An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet.

Object Oriented Interface

public function getIncomingMessageTopicAlias($incomingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 24 , $incomingmessageindex);

Default Value

0

Remarks

An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet.

If a non-zero topic alias is received, the client should establish a new topic alias mapping or use an existing mapping, depending on whether the IncomingMessageTopic string is empty.

For details on setting topic aliases for outgoing messages, see the TopicAlias configuration setting.

Valid only for MQTT 5.

The $incomingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the IncomingMessageCount property.

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

Data Type

Integer

KeepAliveInterval Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getKeepAliveInterval();


public function setKeepAliveInterval($value);

Procedural Interface

ipworksiot_mqtt_get($res, 25 );


ipworksiot_mqtt_set($res, 25, $value );

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.

Data Type

Integer

LocalHost Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getLocalHost();


public function setLocalHost($value);

Procedural Interface

ipworksiot_mqtt_get($res, 26 );


ipworksiot_mqtt_set($res, 26, $value );

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.

Data Type

String

LocalPort Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getLocalPort();


public function setLocalPort($value);

Procedural Interface

ipworksiot_mqtt_get($res, 27 );


ipworksiot_mqtt_set($res, 27, $value );

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.

Data Type

Integer

OutgoingMessageCount Property (IPWorksIoT_MQTT Class)

The number of records in the OutgoingMessage arrays.

Object Oriented Interface

public function getOutgoingMessageCount();

Procedural Interface

ipworksiot_mqtt_get($res, 28 );

Default Value

0

Remarks

This property controls the size of the following arrays:

• OutgoingMessageContentType
• OutgoingMessageCorrelationData
• OutgoingMessageDuplicate
• OutgoingMessageMessage
• OutgoingMessageMessageExpInterval
• OutgoingMessagePacketId
• OutgoingMessagePayloadFormatIndicator
• OutgoingMessageQoS
• OutgoingMessageResponseTopic
• OutgoingMessageRetained
• OutgoingMessageState
• OutgoingMessageSubscriptionIdentifiers
• OutgoingMessageTopic
• OutgoingMessageTopicAlias

The array indices start at 0 and end at OutgoingMessageCount - 1.

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

Data Type

Integer

OutgoingMessageContentType Property (IPWorksIoT_MQTT Class)

String describing the content of the message.

Object Oriented Interface

public function getOutgoingMessageContentType($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 29 , $outgoingmessageindex);

Default Value

''

Remarks

String describing the content of the message. Defined by the sending and receiving application.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

String

OutgoingMessageCorrelationData Property (IPWorksIoT_MQTT Class)

Used by the sender of the request message to identify which request the response message is for when it is received.

Object Oriented Interface

public function getOutgoingMessageCorrelationData($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 30 , $outgoingmessageindex);

Default Value

''

Remarks

Used by the sender of the request message to identify which request the response message is for when it is received.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

String

OutgoingMessageDuplicate Property (IPWorksIoT_MQTT Class)

Whether or not this message's Duplicate flag is set.

Object Oriented Interface

public function getOutgoingMessageDuplicate($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 31 , $outgoingmessageindex);

Default Value

false

Remarks

Whether or not this message's Duplicate flag is set.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Boolean

OutgoingMessageMessage Property (IPWorksIoT_MQTT Class)

This message's raw data payload.

Object Oriented Interface

public function getOutgoingMessageMessage($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 32 , $outgoingmessageindex);

Default Value

''

Remarks

This message's raw data payload.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Binary String

OutgoingMessageMessageExpInterval Property (IPWorksIoT_MQTT Class)

The lifetime of the message in seconds specified by the sender.

Object Oriented Interface

public function getOutgoingMessageMessageExpInterval($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 33 , $outgoingmessageindex);

Default Value

0

Remarks

The lifetime of the message in seconds specified by the sender.

For outgoing messages, the value is useful for instructing the server to delete its copies of the message for any subscribers it has not been able to start delivery to.

For incoming messages, the value sent by the server is the lifetime specified by the sender minus the time the message has been waiting in the server.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

OutgoingMessagePacketId Property (IPWorksIoT_MQTT Class)

This message's packet Id.

Object Oriented Interface

public function getOutgoingMessagePacketId($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 34 , $outgoingmessageindex);

Default Value

0

Remarks

This message's packet Id.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

OutgoingMessagePayloadFormatIndicator Property (IPWorksIoT_MQTT Class)

Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data.

Object Oriented Interface

public function getOutgoingMessagePayloadFormatIndicator($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 35 , $outgoingmessageindex);

Default Value

0

Remarks

Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data. Possible values are:

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

OutgoingMessageQoS Property (IPWorksIoT_MQTT Class)

This message's QoS level.

Object Oriented Interface

public function getOutgoingMessageQoS($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 36 , $outgoingmessageindex);

Default Value

0

Remarks

This message's QoS level. Possible values are:

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

OutgoingMessageResponseTopic Property (IPWorksIoT_MQTT Class)

String used as the topic name for a response message.

Object Oriented Interface

public function getOutgoingMessageResponseTopic($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 37 , $outgoingmessageindex);

Default Value

''

Remarks

String used as the topic name for a response message.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

String

OutgoingMessageRetained Property (IPWorksIoT_MQTT Class)

Whether or not this message's Retain flag is set.

Object Oriented Interface

public function getOutgoingMessageRetained($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 38 , $outgoingmessageindex);

Default Value

false

Remarks

Whether or not this message's Retain flag is set.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Boolean

OutgoingMessageState Property (IPWorksIoT_MQTT Class)

This message's current state.

Object Oriented Interface

public function getOutgoingMessageState($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 39 , $outgoingmessageindex);

Default Value

0

Remarks

This message's current state.

Possible Outgoing Message States:

Possible Incoming Message States:

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

OutgoingMessageSubscriptionIdentifiers Property (IPWorksIoT_MQTT Class)

A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered.

Object Oriented Interface

public function getOutgoingMessageSubscriptionIdentifiers($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 40 , $outgoingmessageindex);

Default Value

''

Remarks

A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered.

This property is only applicable to incoming messages.

If SubscriptionIdentifier is set when subscribing, it will be included in any messages delivered by the broker for the topics specified in that packet.

See the Subscribe method for more details.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

String

OutgoingMessageTopic Property (IPWorksIoT_MQTT Class)

This message's topic.

Object Oriented Interface

public function getOutgoingMessageTopic($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 41 , $outgoingmessageindex);

Default Value

''

Remarks

This message's topic.

MQTT 5 Notes:

If this value is empty, the OutgoingMessageTopicAlias property holds the assigned alias for the topic.

If this value is not empty and OutgoingMessageTopicAlias is non-zero,

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

String

OutgoingMessageTopicAlias Property (IPWorksIoT_MQTT Class)

An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet.

Object Oriented Interface

public function getOutgoingMessageTopicAlias($outgoingmessageindex);

Procedural Interface

ipworksiot_mqtt_get($res, 42 , $outgoingmessageindex);

Default Value

0

Remarks

An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet.

If a non-zero topic alias is received, the client should establish a new topic alias mapping or use an existing mapping, depending on whether the OutgoingMessageTopic string is empty.

For details on setting topic aliases for outgoing messages, see the TopicAlias configuration setting.

Valid only for MQTT 5.

The $outgoingmessageindex parameter specifies the index of the item in the array. The size of the array is controlled by the OutgoingMessageCount property.

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

Data Type

Integer

Password Property (IPWorksIoT_MQTT Class)

A password if authentication is to be used.

Object Oriented Interface

public function getPassword();


public function setPassword($value);

Procedural Interface

ipworksiot_mqtt_get($res, 43 );


ipworksiot_mqtt_set($res, 43, $value );

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.

Data Type

String

ReadyToSend Property (IPWorksIoT_MQTT Class)

Indicates whether the class is ready to send data.

Object Oriented Interface

public function getReadyToSend();

Procedural Interface

ipworksiot_mqtt_get($res, 44 );

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.

Data Type

Boolean

RemoteHost Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getRemoteHost();


public function setRemoteHost($value);

Procedural Interface

ipworksiot_mqtt_get($res, 45 );


ipworksiot_mqtt_set($res, 45, $value );

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.

Data Type

String

RemotePort Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getRemotePort();


public function setRemotePort($value);

Procedural Interface

ipworksiot_mqtt_get($res, 46 );


ipworksiot_mqtt_set($res, 46, $value );

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.

Data Type

Integer

SSLAcceptServerCertEncoded Property (IPWorksIoT_MQTT Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLAcceptServerCertEncoded();


public function setSSLAcceptServerCertEncoded($value);

Procedural Interface

ipworksiot_mqtt_get($res, 48 );


ipworksiot_mqtt_set($res, 48, $value );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

When SSLAcceptServerCertEncoded is set, a search is initiated in the current SSLAcceptServerCertStore for the private key of the certificate. If the key is found, SSLAcceptServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLAcceptServerCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertEncoded Property (IPWorksIoT_MQTT Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLCertEncoded();


public function setSSLCertEncoded($value);

Procedural Interface

ipworksiot_mqtt_get($res, 76 );


ipworksiot_mqtt_set($res, 76, $value );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertStore Property (IPWorksIoT_MQTT Class)

This is the name of the certificate store for the client certificate.

Object Oriented Interface

public function getSSLCertStore();


public function setSSLCertStore($value);

Procedural Interface

ipworksiot_mqtt_get($res, 92 );


ipworksiot_mqtt_set($res, 92, $value );

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password protected, specify the password in SSLCertStorePassword.

SSLCertStore is used in conjunction with the SSLCertSubject property to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please see the SSLCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Binary String

SSLCertStorePassword Property (IPWorksIoT_MQTT Class)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Object Oriented Interface

public function getSSLCertStorePassword();


public function setSSLCertStorePassword($value);

Procedural Interface

ipworksiot_mqtt_get($res, 93 );


ipworksiot_mqtt_set($res, 93, $value );

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLCertStoreType Property (IPWorksIoT_MQTT Class)

This is the type of certificate store for this certificate.

Object Oriented Interface

public function getSSLCertStoreType();


public function setSSLCertStoreType($value);

Procedural Interface

ipworksiot_mqtt_get($res, 94 );


ipworksiot_mqtt_set($res, 94, $value );

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLCertSubject Property (IPWorksIoT_MQTT Class)

This is the subject of the certificate used for client authentication.

Object Oriented Interface

public function getSSLCertSubject();


public function setSSLCertSubject($value);

Procedural Interface

ipworksiot_mqtt_get($res, 95 );


ipworksiot_mqtt_set($res, 95, $value );

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

SSLEnabled Property (IPWorksIoT_MQTT Class)

Whether TLS/SSL is enabled.

Object Oriented Interface

public function getSSLEnabled();


public function setSSLEnabled($value);

Procedural Interface

ipworksiot_mqtt_get($res, 103 );


ipworksiot_mqtt_set($res, 103, $value );

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.

Data Type

Boolean

SSLProvider Property (IPWorksIoT_MQTT Class)

This specifies the SSL/TLS implementation to use.

Object Oriented Interface

public function getSSLProvider();


public function setSSLProvider($value);

Procedural Interface

ipworksiot_mqtt_get($res, 104 );


ipworksiot_mqtt_set($res, 104, $value );

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, on Windows the class will use the platform implementation. On Linux/macOS the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

Data Type

Integer

SSLServerCertEncoded Property (IPWorksIoT_MQTT Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLServerCertEncoded();

Procedural Interface

ipworksiot_mqtt_get($res, 106 );

Default Value

''

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

When SSLServerCertEncoded is set, a search is initiated in the current SSLServerCertStore for the private key of the certificate. If the key is found, SSLServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLServerCertSubject is set to an empty string.

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

Data Type

Binary String

Timeout Property (IPWorksIoT_MQTT Class)

A timeout for the class.

Object Oriented Interface

public function getTimeout();


public function setTimeout($value);

Procedural Interface

ipworksiot_mqtt_get($res, 133 );


ipworksiot_mqtt_set($res, 133, $value );

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 fails with an error.

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.

Data Type

Integer

User Property (IPWorksIoT_MQTT Class)

A username if authentication is to be used.

Object Oriented Interface

public function getUser();


public function setUser($value);

Procedural Interface

ipworksiot_mqtt_get($res, 134 );


ipworksiot_mqtt_set($res, 134, $value );

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.

Data Type

String

Version Property (IPWorksIoT_MQTT Class)

The MQTT protocol version that the class will conform to.

Object Oriented Interface

public function getVersion();


public function setVersion($value);

Procedural Interface

ipworksiot_mqtt_get($res, 135 );


ipworksiot_mqtt_set($res, 135, $value );

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.

Data Type

Integer

WillMessage Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getWillMessage();


public function setWillMessage($value);

Procedural Interface

ipworksiot_mqtt_get($res, 136 );


ipworksiot_mqtt_set($res, 136, $value );

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.

Data Type

String

WillTopic Property (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function getWillTopic();


public function setWillTopic($value);

Procedural Interface

ipworksiot_mqtt_get($res, 137 );


ipworksiot_mqtt_set($res, 137, $value );

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.

Data Type

String

Config Method (IPWorksIoT_MQTT Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

ipworksiot_mqtt_do_config($res, $configurationstring);

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.

Connect Method (IPWorksIoT_MQTT Class)

Connects to the remote host.

Object Oriented Interface

public function doConnect();

Procedural Interface

ipworksiot_mqtt_do_connect($res);

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();

ConnectTo Method (IPWorksIoT_MQTT Class)

Connects to the remote host.

Object Oriented Interface

public function doConnectTo($host, $port);

Procedural Interface

ipworksiot_mqtt_do_connectto($res, $host, $port);

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);

Disconnect Method (IPWorksIoT_MQTT Class)

This method disconnects from the remote host.

Object Oriented Interface

public function doDisconnect();

Procedural Interface

ipworksiot_mqtt_do_disconnect($res);

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.

DoEvents Method (IPWorksIoT_MQTT Class)

Processes events from the internal message queue.

Object Oriented Interface

public function doEvents();

Procedural Interface

ipworksiot_mqtt_do_doevents($res);

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.

Interrupt Method (IPWorksIoT_MQTT Class)

Interrupt the current action and disconnects from the remote host.

Object Oriented Interface

public function doInterrupt();

Procedural Interface

ipworksiot_mqtt_do_interrupt($res);

Remarks

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

PublishData Method (IPWorksIoT_MQTT Class)

Publishes a message with a raw data payload.

Object Oriented Interface

public function doPublishData($topic, $qos, $data);

Procedural Interface

ipworksiot_mqtt_do_publishdata($res, $topic, $qos, $data);

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.

PublishMessage Method (IPWorksIoT_MQTT Class)

Publishes a message with a string payload.

Object Oriented Interface

public function doPublishMessage($topic, $qos, $message);

Procedural Interface

ipworksiot_mqtt_do_publishmessage($res, $topic, $qos, $message);

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.

Reset Method (IPWorksIoT_MQTT Class)

Reset the class.

Object Oriented Interface

public function doReset();

Procedural Interface

ipworksiot_mqtt_do_reset($res);

Remarks

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

RestoreSession Method (IPWorksIoT_MQTT Class)

Restores session state data.

Object Oriented Interface

public function doRestoreSession($statedata);

Procedural Interface

ipworksiot_mqtt_do_restoresession($res, $statedata);

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.

SaveSession Method (IPWorksIoT_MQTT Class)

Saves session state data.

Object Oriented Interface

public function doSaveSession();

Procedural Interface

ipworksiot_mqtt_do_savesession($res);

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.

Subscribe Method (IPWorksIoT_MQTT Class)

Subscribes the class to one or more topic filters.

Object Oriented Interface

public function doSubscribe($topicfilter, $qos);

Procedural Interface

ipworksiot_mqtt_do_subscribe($res, $topicfilter, $qos);

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");

Unsubscribe Method (IPWorksIoT_MQTT Class)

Unsubscribes the class from one or more topic filters.

Object Oriented Interface

public function doUnsubscribe($topicfilter);

Procedural Interface

ipworksiot_mqtt_do_unsubscribe($res, $topicfilter);

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/#");

Connected Event (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function fireConnected($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 1, array($this, 'fireConnected'));

Parameter List

 'statuscode'
 'description'

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.

ConnectionStatus Event (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function fireConnectionStatus($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 2, array($this, 'fireConnectionStatus'));

Parameter List

 'connectionevent'
 'statuscode'
 'description'

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:

Disconnected Event (IPWorksIoT_MQTT Class)

This event is fired when a connection is closed.

Object Oriented Interface

public function fireDisconnected($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 3, array($this, 'fireDisconnected'));

Parameter List

 'statuscode'
 'description'

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.

Error Event (IPWorksIoT_MQTT Class)

Information about errors during data delivery.

Object Oriented Interface

public function fireError($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 4, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

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

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.

Log Event (IPWorksIoT_MQTT Class)

Fires once for each log message.

Object Oriented Interface

public function fireLog($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 5, array($this, 'fireLog'));

Parameter List

 'loglevel'
 'message'
 'logtype'

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.

MessageAck Event (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function fireMessageAck($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 6, array($this, 'fireMessageAck'));

Parameter List

 'packetid'
 'direction'
 'index'
 'responsecode'

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.

MessageIn Event (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function fireMessageIn($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 7, array($this, 'fireMessageIn'));

Parameter List

 'packetid'
 'topic'
 'qos'
 'message'
 'retained'
 'duplicate'

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); };

MessageOut Event (IPWorksIoT_MQTT Class)

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

Object Oriented Interface

public function fireMessageOut($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 8, array($this, 'fireMessageOut'));

Parameter List

 'packetid'
 'topic'
 'qos'
 'message'
 'retained'
 'duplicate'

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); };

ReadyToSend Event (IPWorksIoT_MQTT Class)

Fired when the class is ready to send data.

Object Oriented Interface

public function fireReadyToSend($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 9, array($this, 'fireReadyToSend'));

Parameter List

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.

SSLServerAuthentication Event (IPWorksIoT_MQTT Class)

Fired after the server presents its certificate to the client.

Object Oriented Interface

public function fireSSLServerAuthentication($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 10, array($this, 'fireSSLServerAuthentication'));

Parameter List

 'certencoded'
 'certsubject'
 'certissuer'
 'status'
 'accept'

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (IPWorksIoT_MQTT Class)

Shows the progress of the secure connection.

Object Oriented Interface

public function fireSSLStatus($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 11, array($this, 'fireSSLStatus'));

Parameter List

 'message'

Remarks

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

Subscribed Event (IPWorksIoT_MQTT Class)

Fires for each topic filter subscription the server acknowledges.

Object Oriented Interface

public function fireSubscribed($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 12, array($this, 'fireSubscribed'));

Parameter List

 'topicfilter'
 'qos'
 'responsecode'

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.

Unsubscribed Event (IPWorksIoT_MQTT Class)

Fires when the server has acknowledged an unsubscribe request.

Object Oriented Interface

public function fireUnsubscribed($param);

Procedural Interface

ipworksiot_mqtt_register_callback($res, 13, array($this, 'fireUnsubscribed'));

Parameter List

 'topicfilters'
 'responsecode'

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.

Config Settings (MQTT Class)

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

Base Config Settings

Trappable Errors (MQTT Class)

MQTT Errors

WebSocket Errors

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors