MQTT Class

Properties   Methods   Events   Config Settings   Errors  

A lightweight, fully-featured MQTT client implementation.

Syntax

MQTT

Remarks

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

Connecting

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

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

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

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

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

Topic Subscriptions

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

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

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

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

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

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

Publishing Messages

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

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

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

MQTT 5 Notes

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

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

Property List

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

Method List

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

Event List

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

Config Settings

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

CleanSession Property (MQTT Class)

Determines whether a clean session is used once connected.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetCleanSession();
int SetCleanSession(int bCleanSession);

Unicode (Windows)
BOOL GetCleanSession();
INT SetCleanSession(BOOL bCleanSession);

int ipworksiot_mqtt_getcleansession(void* lpObj);
int ipworksiot_mqtt_setcleansession(void* lpObj, int bCleanSession);

bool GetCleanSession();
int SetCleanSession(bool bCleanSession);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetClientId();
int SetClientId(const char* lpszClientId);

Unicode (Windows)
LPWSTR GetClientId();
INT SetClientId(LPCWSTR lpszClientId);

char* ipworksiot_mqtt_getclientid(void* lpObj);
int ipworksiot_mqtt_setclientid(void* lpObj, const char* lpszClientId);

QString GetClientId();
int SetClientId(QString qsClientId);

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 (MQTT Class)

Triggers a connection or disconnection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetConnected();
int SetConnected(int bConnected);

Unicode (Windows)
BOOL GetConnected();
INT SetConnected(BOOL bConnected);

int ipworksiot_mqtt_getconnected(void* lpObj);
int ipworksiot_mqtt_setconnected(void* lpObj, int bConnected);

bool GetConnected();
int SetConnected(bool bConnected);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFirewallAutoDetect();
int SetFirewallAutoDetect(int bFirewallAutoDetect);

Unicode (Windows)
BOOL GetFirewallAutoDetect();
INT SetFirewallAutoDetect(BOOL bFirewallAutoDetect);

int ipworksiot_mqtt_getfirewallautodetect(void* lpObj);
int ipworksiot_mqtt_setfirewallautodetect(void* lpObj, int bFirewallAutoDetect);

bool GetFirewallAutoDetect();
int SetFirewallAutoDetect(bool bFirewallAutoDetect);

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 (MQTT Class)

This property determines the type of firewall to connect through.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFirewallType();
int SetFirewallType(int iFirewallType);

Unicode (Windows)
INT GetFirewallType();
INT SetFirewallType(INT iFirewallType);

FW_NONE(0), 
FW_TUNNEL(1), 
FW_SOCKS4(2), 
FW_SOCKS5(3), 
FW_SOCKS4A(10)

int ipworksiot_mqtt_getfirewalltype(void* lpObj);
int ipworksiot_mqtt_setfirewalltype(void* lpObj, int iFirewallType);

int GetFirewallType();
int SetFirewallType(int iFirewallType);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFirewallHost();
int SetFirewallHost(const char* lpszFirewallHost);

Unicode (Windows)
LPWSTR GetFirewallHost();
INT SetFirewallHost(LPCWSTR lpszFirewallHost);

char* ipworksiot_mqtt_getfirewallhost(void* lpObj);
int ipworksiot_mqtt_setfirewallhost(void* lpObj, const char* lpszFirewallHost);

QString GetFirewallHost();
int SetFirewallHost(QString qsFirewallHost);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFirewallPassword();
int SetFirewallPassword(const char* lpszFirewallPassword);

Unicode (Windows)
LPWSTR GetFirewallPassword();
INT SetFirewallPassword(LPCWSTR lpszFirewallPassword);

char* ipworksiot_mqtt_getfirewallpassword(void* lpObj);
int ipworksiot_mqtt_setfirewallpassword(void* lpObj, const char* lpszFirewallPassword);

QString GetFirewallPassword();
int SetFirewallPassword(QString qsFirewallPassword);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFirewallPort();
int SetFirewallPort(int iFirewallPort);

Unicode (Windows)
INT GetFirewallPort();
INT SetFirewallPort(INT iFirewallPort);

int ipworksiot_mqtt_getfirewallport(void* lpObj);
int ipworksiot_mqtt_setfirewallport(void* lpObj, int iFirewallPort);

int GetFirewallPort();
int SetFirewallPort(int iFirewallPort);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFirewallUser();
int SetFirewallUser(const char* lpszFirewallUser);

Unicode (Windows)
LPWSTR GetFirewallUser();
INT SetFirewallUser(LPCWSTR lpszFirewallUser);

char* ipworksiot_mqtt_getfirewalluser(void* lpObj);
int ipworksiot_mqtt_setfirewalluser(void* lpObj, const char* lpszFirewallUser);

QString GetFirewallUser();
int SetFirewallUser(QString qsFirewallUser);

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 (MQTT Class)

The number of records in the IncomingMessage arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageCount();

Unicode (Windows)
INT GetIncomingMessageCount();

int ipworksiot_mqtt_getincomingmessagecount(void* lpObj);

int GetIncomingMessageCount();

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 (MQTT Class)

String describing the content of the message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncomingMessageContentType(int iIncomingMessageIndex);

Unicode (Windows)
LPWSTR GetIncomingMessageContentType(INT iIncomingMessageIndex);

char* ipworksiot_mqtt_getincomingmessagecontenttype(void* lpObj, int incomingmessageindex);

QString GetIncomingMessageContentType(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncomingMessageCorrelationData(int iIncomingMessageIndex);

Unicode (Windows)
LPWSTR GetIncomingMessageCorrelationData(INT iIncomingMessageIndex);

char* ipworksiot_mqtt_getincomingmessagecorrelationdata(void* lpObj, int incomingmessageindex);

QString GetIncomingMessageCorrelationData(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageDuplicate(int iIncomingMessageIndex);

Unicode (Windows)
BOOL GetIncomingMessageDuplicate(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessageduplicate(void* lpObj, int incomingmessageindex);

bool GetIncomingMessageDuplicate(int iIncomingMessageIndex);

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 (MQTT Class)

This message's raw data payload.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageMessage(int iIncomingMessageIndex, char* &lpIncomingMessageMessage, int &lenIncomingMessageMessage);

Unicode (Windows)
INT GetIncomingMessageMessage(INT iIncomingMessageIndex, LPSTR &lpIncomingMessageMessage, INT &lenIncomingMessageMessage);

int ipworksiot_mqtt_getincomingmessagemessage(void* lpObj, int incomingmessageindex, char** lpIncomingMessageMessage, int* lenIncomingMessageMessage);

QByteArray GetIncomingMessageMessage(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageMessageExpInterval(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessageMessageExpInterval(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessagemessageexpinterval(void* lpObj, int incomingmessageindex);

int GetIncomingMessageMessageExpInterval(int iIncomingMessageIndex);

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 (MQTT Class)

This message's packet Id.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessagePacketId(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessagePacketId(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessagepacketid(void* lpObj, int incomingmessageindex);

int GetIncomingMessagePacketId(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessagePayloadFormatIndicator(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessagePayloadFormatIndicator(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessagepayloadformatindicator(void* lpObj, int incomingmessageindex);

int GetIncomingMessagePayloadFormatIndicator(int iIncomingMessageIndex);

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 (MQTT Class)

This message's QoS level.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageQoS(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessageQoS(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessageqos(void* lpObj, int incomingmessageindex);

int GetIncomingMessageQoS(int iIncomingMessageIndex);

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 (MQTT Class)

String used as the topic name for a response message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncomingMessageResponseTopic(int iIncomingMessageIndex);

Unicode (Windows)
LPWSTR GetIncomingMessageResponseTopic(INT iIncomingMessageIndex);

char* ipworksiot_mqtt_getincomingmessageresponsetopic(void* lpObj, int incomingmessageindex);

QString GetIncomingMessageResponseTopic(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageRetained(int iIncomingMessageIndex);

Unicode (Windows)
BOOL GetIncomingMessageRetained(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessageretained(void* lpObj, int incomingmessageindex);

bool GetIncomingMessageRetained(int iIncomingMessageIndex);

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 (MQTT Class)

This message's current state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageState(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessageState(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessagestate(void* lpObj, int incomingmessageindex);

int GetIncomingMessageState(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncomingMessageSubscriptionIdentifiers(int iIncomingMessageIndex);

Unicode (Windows)
LPWSTR GetIncomingMessageSubscriptionIdentifiers(INT iIncomingMessageIndex);

char* ipworksiot_mqtt_getincomingmessagesubscriptionidentifiers(void* lpObj, int incomingmessageindex);

QString GetIncomingMessageSubscriptionIdentifiers(int iIncomingMessageIndex);

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 (MQTT Class)

This message's topic.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncomingMessageTopic(int iIncomingMessageIndex);

Unicode (Windows)
LPWSTR GetIncomingMessageTopic(INT iIncomingMessageIndex);

char* ipworksiot_mqtt_getincomingmessagetopic(void* lpObj, int incomingmessageindex);

QString GetIncomingMessageTopic(int iIncomingMessageIndex);

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 (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.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncomingMessageTopicAlias(int iIncomingMessageIndex);

Unicode (Windows)
INT GetIncomingMessageTopicAlias(INT iIncomingMessageIndex);

int ipworksiot_mqtt_getincomingmessagetopicalias(void* lpObj, int incomingmessageindex);

int GetIncomingMessageTopicAlias(int iIncomingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetKeepAliveInterval();
int SetKeepAliveInterval(int iKeepAliveInterval);

Unicode (Windows)
INT GetKeepAliveInterval();
INT SetKeepAliveInterval(INT iKeepAliveInterval);

int ipworksiot_mqtt_getkeepaliveinterval(void* lpObj);
int ipworksiot_mqtt_setkeepaliveinterval(void* lpObj, int iKeepAliveInterval);

int GetKeepAliveInterval();
int SetKeepAliveInterval(int iKeepAliveInterval);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLocalHost();
int SetLocalHost(const char* lpszLocalHost);

Unicode (Windows)
LPWSTR GetLocalHost();
INT SetLocalHost(LPCWSTR lpszLocalHost);

char* ipworksiot_mqtt_getlocalhost(void* lpObj);
int ipworksiot_mqtt_setlocalhost(void* lpObj, const char* lpszLocalHost);

QString GetLocalHost();
int SetLocalHost(QString qsLocalHost);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetLocalPort();
int SetLocalPort(int iLocalPort);

Unicode (Windows)
INT GetLocalPort();
INT SetLocalPort(INT iLocalPort);

int ipworksiot_mqtt_getlocalport(void* lpObj);
int ipworksiot_mqtt_setlocalport(void* lpObj, int iLocalPort);

int GetLocalPort();
int SetLocalPort(int iLocalPort);

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 (MQTT Class)

The number of records in the OutgoingMessage arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageCount();

Unicode (Windows)
INT GetOutgoingMessageCount();

int ipworksiot_mqtt_getoutgoingmessagecount(void* lpObj);

int GetOutgoingMessageCount();

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 (MQTT Class)

String describing the content of the message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutgoingMessageContentType(int iOutgoingMessageIndex);

Unicode (Windows)
LPWSTR GetOutgoingMessageContentType(INT iOutgoingMessageIndex);

char* ipworksiot_mqtt_getoutgoingmessagecontenttype(void* lpObj, int outgoingmessageindex);

QString GetOutgoingMessageContentType(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutgoingMessageCorrelationData(int iOutgoingMessageIndex);

Unicode (Windows)
LPWSTR GetOutgoingMessageCorrelationData(INT iOutgoingMessageIndex);

char* ipworksiot_mqtt_getoutgoingmessagecorrelationdata(void* lpObj, int outgoingmessageindex);

QString GetOutgoingMessageCorrelationData(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageDuplicate(int iOutgoingMessageIndex);

Unicode (Windows)
BOOL GetOutgoingMessageDuplicate(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessageduplicate(void* lpObj, int outgoingmessageindex);

bool GetOutgoingMessageDuplicate(int iOutgoingMessageIndex);

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 (MQTT Class)

This message's raw data payload.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageMessage(int iOutgoingMessageIndex, char* &lpOutgoingMessageMessage, int &lenOutgoingMessageMessage);

Unicode (Windows)
INT GetOutgoingMessageMessage(INT iOutgoingMessageIndex, LPSTR &lpOutgoingMessageMessage, INT &lenOutgoingMessageMessage);

int ipworksiot_mqtt_getoutgoingmessagemessage(void* lpObj, int outgoingmessageindex, char** lpOutgoingMessageMessage, int* lenOutgoingMessageMessage);

QByteArray GetOutgoingMessageMessage(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageMessageExpInterval(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessageMessageExpInterval(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessagemessageexpinterval(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessageMessageExpInterval(int iOutgoingMessageIndex);

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 (MQTT Class)

This message's packet Id.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessagePacketId(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessagePacketId(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessagepacketid(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessagePacketId(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessagePayloadFormatIndicator(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessagePayloadFormatIndicator(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessagepayloadformatindicator(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessagePayloadFormatIndicator(int iOutgoingMessageIndex);

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 (MQTT Class)

This message's QoS level.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageQoS(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessageQoS(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessageqos(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessageQoS(int iOutgoingMessageIndex);

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 (MQTT Class)

String used as the topic name for a response message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutgoingMessageResponseTopic(int iOutgoingMessageIndex);

Unicode (Windows)
LPWSTR GetOutgoingMessageResponseTopic(INT iOutgoingMessageIndex);

char* ipworksiot_mqtt_getoutgoingmessageresponsetopic(void* lpObj, int outgoingmessageindex);

QString GetOutgoingMessageResponseTopic(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageRetained(int iOutgoingMessageIndex);

Unicode (Windows)
BOOL GetOutgoingMessageRetained(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessageretained(void* lpObj, int outgoingmessageindex);

bool GetOutgoingMessageRetained(int iOutgoingMessageIndex);

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 (MQTT Class)

This message's current state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageState(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessageState(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessagestate(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessageState(int iOutgoingMessageIndex);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutgoingMessageSubscriptionIdentifiers(int iOutgoingMessageIndex);

Unicode (Windows)
LPWSTR GetOutgoingMessageSubscriptionIdentifiers(INT iOutgoingMessageIndex);

char* ipworksiot_mqtt_getoutgoingmessagesubscriptionidentifiers(void* lpObj, int outgoingmessageindex);

QString GetOutgoingMessageSubscriptionIdentifiers(int iOutgoingMessageIndex);

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 (MQTT Class)

This message's topic.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutgoingMessageTopic(int iOutgoingMessageIndex);

Unicode (Windows)
LPWSTR GetOutgoingMessageTopic(INT iOutgoingMessageIndex);

char* ipworksiot_mqtt_getoutgoingmessagetopic(void* lpObj, int outgoingmessageindex);

QString GetOutgoingMessageTopic(int iOutgoingMessageIndex);

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 (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.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutgoingMessageTopicAlias(int iOutgoingMessageIndex);

Unicode (Windows)
INT GetOutgoingMessageTopicAlias(INT iOutgoingMessageIndex);

int ipworksiot_mqtt_getoutgoingmessagetopicalias(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessageTopicAlias(int iOutgoingMessageIndex);

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 (MQTT Class)

A password if authentication is to be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPassword();
int SetPassword(const char* lpszPassword);

Unicode (Windows)
LPWSTR GetPassword();
INT SetPassword(LPCWSTR lpszPassword);

char* ipworksiot_mqtt_getpassword(void* lpObj);
int ipworksiot_mqtt_setpassword(void* lpObj, const char* lpszPassword);

QString GetPassword();
int SetPassword(QString qsPassword);

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 (MQTT Class)

Indicates whether the class is ready to send data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetReadyToSend();

Unicode (Windows)
BOOL GetReadyToSend();

int ipworksiot_mqtt_getreadytosend(void* lpObj);

bool GetReadyToSend();

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRemoteHost();
int SetRemoteHost(const char* lpszRemoteHost);

Unicode (Windows)
LPWSTR GetRemoteHost();
INT SetRemoteHost(LPCWSTR lpszRemoteHost);

char* ipworksiot_mqtt_getremotehost(void* lpObj);
int ipworksiot_mqtt_setremotehost(void* lpObj, const char* lpszRemoteHost);

QString GetRemoteHost();
int SetRemoteHost(QString qsRemoteHost);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRemotePort();
int SetRemotePort(int iRemotePort);

Unicode (Windows)
INT GetRemotePort();
INT SetRemotePort(INT iRemotePort);

int ipworksiot_mqtt_getremoteport(void* lpObj);
int ipworksiot_mqtt_setremoteport(void* lpObj, int iRemotePort);

int GetRemotePort();
int SetRemotePort(int iRemotePort);

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 (MQTT Class)

This is the certificate (PEM/base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLAcceptServerCertEncoded(char* &lpSSLAcceptServerCertEncoded, int &lenSSLAcceptServerCertEncoded);
int SetSSLAcceptServerCertEncoded(const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

Unicode (Windows)
INT GetSSLAcceptServerCertEncoded(LPSTR &lpSSLAcceptServerCertEncoded, INT &lenSSLAcceptServerCertEncoded);
INT SetSSLAcceptServerCertEncoded(LPCSTR lpSSLAcceptServerCertEncoded, INT lenSSLAcceptServerCertEncoded);

int ipworksiot_mqtt_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int ipworksiot_mqtt_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QByteArray GetSSLAcceptServerCertEncoded();
int SetSSLAcceptServerCertEncoded(QByteArray qbaSSLAcceptServerCertEncoded);

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 (MQTT Class)

This is the certificate (PEM/base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertEncoded(char* &lpSSLCertEncoded, int &lenSSLCertEncoded);
int SetSSLCertEncoded(const char* lpSSLCertEncoded, int lenSSLCertEncoded);

Unicode (Windows)
INT GetSSLCertEncoded(LPSTR &lpSSLCertEncoded, INT &lenSSLCertEncoded);
INT SetSSLCertEncoded(LPCSTR lpSSLCertEncoded, INT lenSSLCertEncoded);

int ipworksiot_mqtt_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int ipworksiot_mqtt_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertStore(char* &lpSSLCertStore, int &lenSSLCertStore);
int SetSSLCertStore(const char* lpSSLCertStore, int lenSSLCertStore);

Unicode (Windows)
INT GetSSLCertStore(LPSTR &lpSSLCertStore, INT &lenSSLCertStore);
INT SetSSLCertStore(LPCSTR lpSSLCertStore, INT lenSSLCertStore);

int ipworksiot_mqtt_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int ipworksiot_mqtt_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

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 (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.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSSLCertStorePassword();
int SetSSLCertStorePassword(const char* lpszSSLCertStorePassword);

Unicode (Windows)
LPWSTR GetSSLCertStorePassword();
INT SetSSLCertStorePassword(LPCWSTR lpszSSLCertStorePassword);

char* ipworksiot_mqtt_getsslcertstorepassword(void* lpObj);
int ipworksiot_mqtt_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

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 (MQTT Class)

This is the type of certificate store for this certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

Unicode (Windows)
INT GetSSLCertStoreType();
INT SetSSLCertStoreType(INT iSSLCertStoreType);

CST_USER(0), 
CST_MACHINE(1), 
CST_PFXFILE(2), 
CST_PFXBLOB(3), 
CST_JKSFILE(4), 
CST_JKSBLOB(5), 
CST_PEMKEY_FILE(6), 
CST_PEMKEY_BLOB(7), 
CST_PUBLIC_KEY_FILE(8), 
CST_PUBLIC_KEY_BLOB(9), 
CST_SSHPUBLIC_KEY_BLOB(10), 
CST_P7BFILE(11), 
CST_P7BBLOB(12), 
CST_SSHPUBLIC_KEY_FILE(13), 
CST_PPKFILE(14), 
CST_PPKBLOB(15), 
CST_XMLFILE(16), 
CST_XMLBLOB(17), 
CST_JWKFILE(18), 
CST_JWKBLOB(19), 
CST_SECURITY_KEY(20), 
CST_BCFKSFILE(21), 
CST_BCFKSBLOB(22), 
CST_PKCS11(23), 
CST_AUTO(99)

int ipworksiot_mqtt_getsslcertstoretype(void* lpObj);
int ipworksiot_mqtt_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSSLCertSubject();
int SetSSLCertSubject(const char* lpszSSLCertSubject);

Unicode (Windows)
LPWSTR GetSSLCertSubject();
INT SetSSLCertSubject(LPCWSTR lpszSSLCertSubject);

char* ipworksiot_mqtt_getsslcertsubject(void* lpObj);
int ipworksiot_mqtt_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

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 (MQTT Class)

Whether TLS/SSL is enabled.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLEnabled();
int SetSSLEnabled(int bSSLEnabled);

Unicode (Windows)
BOOL GetSSLEnabled();
INT SetSSLEnabled(BOOL bSSLEnabled);

int ipworksiot_mqtt_getsslenabled(void* lpObj);
int ipworksiot_mqtt_setsslenabled(void* lpObj, int bSSLEnabled);

bool GetSSLEnabled();
int SetSSLEnabled(bool bSSLEnabled);

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 (MQTT Class)

This specifies the SSL/TLS implementation to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

Unicode (Windows)
INT GetSSLProvider();
INT SetSSLProvider(INT iSSLProvider);

SSLP_AUTOMATIC(0), 
SSLP_PLATFORM(1), 
SSLP_INTERNAL(2)

int ipworksiot_mqtt_getsslprovider(void* lpObj);
int ipworksiot_mqtt_setsslprovider(void* lpObj, int iSSLProvider);

int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

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 (MQTT Class)

This is the certificate (PEM/base64 encoded).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLServerCertEncoded(char* &lpSSLServerCertEncoded, int &lenSSLServerCertEncoded);

Unicode (Windows)
INT GetSSLServerCertEncoded(LPSTR &lpSSLServerCertEncoded, INT &lenSSLServerCertEncoded);

int ipworksiot_mqtt_getsslservercertencoded(void* lpObj, char** lpSSLServerCertEncoded, int* lenSSLServerCertEncoded);

QByteArray GetSSLServerCertEncoded();

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 (MQTT Class)

A timeout for the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int ipworksiot_mqtt_gettimeout(void* lpObj);
int ipworksiot_mqtt_settimeout(void* lpObj, int iTimeout);

int GetTimeout();
int SetTimeout(int iTimeout);

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 (MQTT Class)

A username if authentication is to be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetUser();
int SetUser(const char* lpszUser);

Unicode (Windows)
LPWSTR GetUser();
INT SetUser(LPCWSTR lpszUser);

char* ipworksiot_mqtt_getuser(void* lpObj);
int ipworksiot_mqtt_setuser(void* lpObj, const char* lpszUser);

QString GetUser();
int SetUser(QString qsUser);

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 (MQTT Class)

The MQTT protocol version that the class will conform to.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetVersion();
int SetVersion(int iVersion);

Unicode (Windows)
INT GetVersion();
INT SetVersion(INT iVersion);

MV_V3(0), 
MV_V5(1)

int ipworksiot_mqtt_getversion(void* lpObj);
int ipworksiot_mqtt_setversion(void* lpObj, int iVersion);

int GetVersion();
int SetVersion(int iVersion);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetWillMessage();
int SetWillMessage(const char* lpszWillMessage);

Unicode (Windows)
LPWSTR GetWillMessage();
INT SetWillMessage(LPCWSTR lpszWillMessage);

char* ipworksiot_mqtt_getwillmessage(void* lpObj);
int ipworksiot_mqtt_setwillmessage(void* lpObj, const char* lpszWillMessage);

QString GetWillMessage();
int SetWillMessage(QString qsWillMessage);

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetWillTopic();
int SetWillTopic(const char* lpszWillTopic);

Unicode (Windows)
LPWSTR GetWillTopic();
INT SetWillTopic(LPCWSTR lpszWillTopic);

char* ipworksiot_mqtt_getwilltopic(void* lpObj);
int ipworksiot_mqtt_setwilltopic(void* lpObj, const char* lpszWillTopic);

QString GetWillTopic();
int SetWillTopic(QString qsWillTopic);

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 (MQTT Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksiot_mqtt_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Connect Method (MQTT Class)

Connects to the remote host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Connect();

Unicode (Windows)
INT Connect();

int ipworksiot_mqtt_connect(void* lpObj);

int Connect();

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ConnectTo Method (MQTT Class)

Connects to the remote host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ConnectTo(const char* lpszHost, int iPort);

Unicode (Windows)
INT ConnectTo(LPCWSTR lpszHost, INT iPort);

int ipworksiot_mqtt_connectto(void* lpObj, const char* lpszHost, int iPort);

int ConnectTo(const QString& qsHost, int iPort);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Disconnect Method (MQTT Class)

This method disconnects from the remote host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Disconnect();

Unicode (Windows)
INT Disconnect();

int ipworksiot_mqtt_disconnect(void* lpObj);

int Disconnect();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DoEvents Method (MQTT Class)

Processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int ipworksiot_mqtt_doevents(void* lpObj);

int DoEvents();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Interrupt Method (MQTT Class)

Interrupt the current action and disconnects from the remote host.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Interrupt();

Unicode (Windows)
INT Interrupt();

int ipworksiot_mqtt_interrupt(void* lpObj);

int Interrupt();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PublishData Method (MQTT Class)

Publishes a message with a raw data payload.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PublishData(const char* lpszTopic, int iQOS, const char* lpData, int lenData);

Unicode (Windows)
INT PublishData(LPCWSTR lpszTopic, INT iQOS, LPCSTR lpData, INT lenData);

int ipworksiot_mqtt_publishdata(void* lpObj, const char* lpszTopic, int iQOS, const char* lpData, int lenData);

int PublishData(const QString& qsTopic, int iQOS, QByteArray qbaData);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PublishMessage Method (MQTT Class)

Publishes a message with a string payload.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PublishMessage(const char* lpszTopic, int iQOS, const char* lpszMessage);

Unicode (Windows)
INT PublishMessage(LPCWSTR lpszTopic, INT iQOS, LPCWSTR lpszMessage);

int ipworksiot_mqtt_publishmessage(void* lpObj, const char* lpszTopic, int iQOS, const char* lpszMessage);

int PublishMessage(const QString& qsTopic, int iQOS, const QString& qsMessage);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (MQTT Class)

Reset the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksiot_mqtt_reset(void* lpObj);

int Reset();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

RestoreSession Method (MQTT Class)

Restores session state data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RestoreSession(const char* lpszStateData);

Unicode (Windows)
INT RestoreSession(LPCWSTR lpszStateData);

int ipworksiot_mqtt_restoresession(void* lpObj, const char* lpszStateData);

int RestoreSession(const QString& qsStateData);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SaveSession Method (MQTT Class)

Saves session state data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* SaveSession();

Unicode (Windows)
LPWSTR SaveSession();

char* ipworksiot_mqtt_savesession(void* lpObj);

QString SaveSession();

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Subscribe Method (MQTT Class)

Subscribes the class to one or more topic filters.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Subscribe(const char* lpszTopicFilter, int iQOS);

Unicode (Windows)
INT Subscribe(LPCWSTR lpszTopicFilter, INT iQOS);

int ipworksiot_mqtt_subscribe(void* lpObj, const char* lpszTopicFilter, int iQOS);

int Subscribe(const QString& qsTopicFilter, int iQOS);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Unsubscribe Method (MQTT Class)

Unsubscribes the class from one or more topic filters.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Unsubscribe(const char* lpszTopicFilter);

Unicode (Windows)
INT Unsubscribe(LPCWSTR lpszTopicFilter);

int ipworksiot_mqtt_unsubscribe(void* lpObj, const char* lpszTopicFilter);

int Unsubscribe(const QString& qsTopicFilter);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Connected Event (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireConnected(MQTTConnectedEventParams *e);

typedef struct {
  int StatusCode;
  const char *Description;
  int reserved;
} MQTTConnectedEventParams;


Unicode (Windows)
virtual INT FireConnected(MQTTConnectedEventParams *e);

typedef struct {
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} MQTTConnectedEventParams;

#define EID_MQTT_CONNECTED 1

virtual INT IPWORKSIOT_CALL FireConnected(INT &iStatusCode, LPSTR &lpszDescription);

class MQTTConnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Connected(MQTTConnectedEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireConnected(MQTTConnectedEventParams *e) {...}

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireConnectionStatus(MQTTConnectionStatusEventParams *e);

typedef struct {
  const char *ConnectionEvent;
  int StatusCode;
  const char *Description;
  int reserved;
} MQTTConnectionStatusEventParams;


Unicode (Windows)
virtual INT FireConnectionStatus(MQTTConnectionStatusEventParams *e);

typedef struct {
  LPCWSTR ConnectionEvent;
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} MQTTConnectionStatusEventParams;

#define EID_MQTT_CONNECTIONSTATUS 2

virtual INT IPWORKSIOT_CALL FireConnectionStatus(LPSTR &lpszConnectionEvent, INT &iStatusCode, LPSTR &lpszDescription);

class MQTTConnectionStatusEventParams {
public:
  const QString &ConnectionEvent();

  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ConnectionStatus(MQTTConnectionStatusEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireConnectionStatus(MQTTConnectionStatusEventParams *e) {...}

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 (MQTT Class)

This event is fired when a connection is closed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDisconnected(MQTTDisconnectedEventParams *e);

typedef struct {
  int StatusCode;
  const char *Description;
  int reserved;
} MQTTDisconnectedEventParams;


Unicode (Windows)
virtual INT FireDisconnected(MQTTDisconnectedEventParams *e);

typedef struct {
  INT StatusCode;
  LPCWSTR Description;
  INT reserved;
} MQTTDisconnectedEventParams;

#define EID_MQTT_DISCONNECTED 3

virtual INT IPWORKSIOT_CALL FireDisconnected(INT &iStatusCode, LPSTR &lpszDescription);

class MQTTDisconnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Disconnected(MQTTDisconnectedEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireDisconnected(MQTTDisconnectedEventParams *e) {...}

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 (MQTT Class)

Information about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(MQTTErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} MQTTErrorEventParams;


Unicode (Windows)
virtual INT FireError(MQTTErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} MQTTErrorEventParams;

#define EID_MQTT_ERROR 4

virtual INT IPWORKSIOT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class MQTTErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(MQTTErrorEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireError(MQTTErrorEventParams *e) {...}

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 (MQTT Class)

Fires once for each log message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireLog(MQTTLogEventParams *e);

typedef struct {
  int LogLevel;
  const char *Message;
  const char *LogType;
  int reserved;
} MQTTLogEventParams;


Unicode (Windows)
virtual INT FireLog(MQTTLogEventParams *e);

typedef struct {
  INT LogLevel;
  LPCWSTR Message;
  LPCWSTR LogType;
  INT reserved;
} MQTTLogEventParams;

#define EID_MQTT_LOG 5

virtual INT IPWORKSIOT_CALL FireLog(INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);

class MQTTLogEventParams {
public:
  int LogLevel();

  const QString &Message();

  const QString &LogType();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Log(MQTTLogEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireLog(MQTTLogEventParams *e) {...}

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireMessageAck(MQTTMessageAckEventParams *e);

typedef struct {
  int PacketId;
  int Direction;
  int Index;
  int ResponseCode;
  int reserved;
} MQTTMessageAckEventParams;


Unicode (Windows)
virtual INT FireMessageAck(MQTTMessageAckEventParams *e);

typedef struct {
  INT PacketId;
  INT Direction;
  INT Index;
  INT ResponseCode;
  INT reserved;
} MQTTMessageAckEventParams;

#define EID_MQTT_MESSAGEACK 6

virtual INT IPWORKSIOT_CALL FireMessageAck(INT &iPacketId, INT &iDirection, INT &iIndex, INT &iResponseCode);

class MQTTMessageAckEventParams {
public:
  int PacketId();

  int Direction();

  int Index();

  int ResponseCode();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void MessageAck(MQTTMessageAckEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireMessageAck(MQTTMessageAckEventParams *e) {...}

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireMessageIn(MQTTMessageInEventParams *e);

typedef struct {
  int PacketId;
  const char *Topic;
  int QOS;
  const char *Message;
  int lenMessage;
  int Retained;
  int Duplicate;
  int reserved;
} MQTTMessageInEventParams;


Unicode (Windows)
virtual INT FireMessageIn(MQTTMessageInEventParams *e);

typedef struct {
  INT PacketId;
  LPCWSTR Topic;
  INT QOS;
  LPCSTR Message;
  INT lenMessage;
  BOOL Retained;
  BOOL Duplicate;
  INT reserved;
} MQTTMessageInEventParams;

#define EID_MQTT_MESSAGEIN 7

virtual INT IPWORKSIOT_CALL FireMessageIn(INT &iPacketId, LPSTR &lpszTopic, INT &iQOS, LPSTR &lpMessage, INT &lenMessage, BOOL &bRetained, BOOL &bDuplicate);

class MQTTMessageInEventParams {
public:
  int PacketId();

  const QString &Topic();

  int QOS();

  const QByteArray &Message();

  bool Retained();

  bool Duplicate();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void MessageIn(MQTTMessageInEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireMessageIn(MQTTMessageInEventParams *e) {...}

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 (MQTT Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireMessageOut(MQTTMessageOutEventParams *e);

typedef struct {
  int PacketId;
  const char *Topic;
  int QOS;
  const char *Message;
  int lenMessage;
  int Retained;
  int Duplicate;
  int reserved;
} MQTTMessageOutEventParams;


Unicode (Windows)
virtual INT FireMessageOut(MQTTMessageOutEventParams *e);

typedef struct {
  INT PacketId;
  LPCWSTR Topic;
  INT QOS;
  LPCSTR Message;
  INT lenMessage;
  BOOL Retained;
  BOOL Duplicate;
  INT reserved;
} MQTTMessageOutEventParams;

#define EID_MQTT_MESSAGEOUT 8

virtual INT IPWORKSIOT_CALL FireMessageOut(INT &iPacketId, LPSTR &lpszTopic, INT &iQOS, LPSTR &lpMessage, INT &lenMessage, BOOL &bRetained, BOOL &bDuplicate);

class MQTTMessageOutEventParams {
public:
  int PacketId();

  const QString &Topic();

  int QOS();

  const QByteArray &Message();

  bool Retained();

  bool Duplicate();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void MessageOut(MQTTMessageOutEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireMessageOut(MQTTMessageOutEventParams *e) {...}

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 (MQTT Class)

Fired when the class is ready to send data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireReadyToSend(MQTTReadyToSendEventParams *e);

typedef struct {
  int reserved;
} MQTTReadyToSendEventParams;


Unicode (Windows)
virtual INT FireReadyToSend(MQTTReadyToSendEventParams *e);

typedef struct {
  INT reserved;
} MQTTReadyToSendEventParams;

#define EID_MQTT_READYTOSEND 9

virtual INT IPWORKSIOT_CALL FireReadyToSend();

class MQTTReadyToSendEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ReadyToSend(MQTTReadyToSendEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireReadyToSend(MQTTReadyToSendEventParams *e) {...}

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 (MQTT Class)

Fired after the server presents its certificate to the client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLServerAuthentication(MQTTSSLServerAuthenticationEventParams *e);

typedef struct {
  const char *CertEncoded;
  int lenCertEncoded;
  const char *CertSubject;
  const char *CertIssuer;
  const char *Status;
  int Accept;
  int reserved;
} MQTTSSLServerAuthenticationEventParams;


Unicode (Windows)
virtual INT FireSSLServerAuthentication(MQTTSSLServerAuthenticationEventParams *e);

typedef struct {
  LPCSTR CertEncoded;
  INT lenCertEncoded;
  LPCWSTR CertSubject;
  LPCWSTR CertIssuer;
  LPCWSTR Status;
  BOOL Accept;
  INT reserved;
} MQTTSSLServerAuthenticationEventParams;

#define EID_MQTT_SSLSERVERAUTHENTICATION 10

virtual INT IPWORKSIOT_CALL FireSSLServerAuthentication(LPSTR &lpCertEncoded, INT &lenCertEncoded, LPSTR &lpszCertSubject, LPSTR &lpszCertIssuer, LPSTR &lpszStatus, BOOL &bAccept);

class MQTTSSLServerAuthenticationEventParams {
public:
  const QByteArray &CertEncoded();

  const QString &CertSubject();

  const QString &CertIssuer();

  const QString &Status();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLServerAuthentication(MQTTSSLServerAuthenticationEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireSSLServerAuthentication(MQTTSSLServerAuthenticationEventParams *e) {...}

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 (MQTT Class)

Shows the progress of the secure connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLStatus(MQTTSSLStatusEventParams *e);

typedef struct {
  const char *Message;
  int reserved;
} MQTTSSLStatusEventParams;


Unicode (Windows)
virtual INT FireSSLStatus(MQTTSSLStatusEventParams *e);

typedef struct {
  LPCWSTR Message;
  INT reserved;
} MQTTSSLStatusEventParams;

#define EID_MQTT_SSLSTATUS 11

virtual INT IPWORKSIOT_CALL FireSSLStatus(LPSTR &lpszMessage);

class MQTTSSLStatusEventParams {
public:
  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLStatus(MQTTSSLStatusEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireSSLStatus(MQTTSSLStatusEventParams *e) {...}

Remarks

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

Subscribed Event (MQTT Class)

Fires for each topic filter subscription the server acknowledges.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSubscribed(MQTTSubscribedEventParams *e);

typedef struct {
  const char *TopicFilter;
  int QOS;
  int ResponseCode;
  int reserved;
} MQTTSubscribedEventParams;


Unicode (Windows)
virtual INT FireSubscribed(MQTTSubscribedEventParams *e);

typedef struct {
  LPCWSTR TopicFilter;
  INT QOS;
  INT ResponseCode;
  INT reserved;
} MQTTSubscribedEventParams;

#define EID_MQTT_SUBSCRIBED 12

virtual INT IPWORKSIOT_CALL FireSubscribed(LPSTR &lpszTopicFilter, INT &iQOS, INT &iResponseCode);

class MQTTSubscribedEventParams {
public:
  const QString &TopicFilter();

  int QOS();

  int ResponseCode();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Subscribed(MQTTSubscribedEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireSubscribed(MQTTSubscribedEventParams *e) {...}

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 (MQTT Class)

Fires when the server has acknowledged an unsubscribe request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireUnsubscribed(MQTTUnsubscribedEventParams *e);

typedef struct {
  const char *TopicFilters;
  int ResponseCode;
  int reserved;
} MQTTUnsubscribedEventParams;


Unicode (Windows)
virtual INT FireUnsubscribed(MQTTUnsubscribedEventParams *e);

typedef struct {
  LPCWSTR TopicFilters;
  INT ResponseCode;
  INT reserved;
} MQTTUnsubscribedEventParams;

#define EID_MQTT_UNSUBSCRIBED 13

virtual INT IPWORKSIOT_CALL FireUnsubscribed(LPSTR &lpszTopicFilters, INT &iResponseCode);

class MQTTUnsubscribedEventParams {
public:
  const QString &TopicFilters();

  int ResponseCode();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Unsubscribed(MQTTUnsubscribedEventParams *e);

// Or, subclass MQTT and override this emitter function.
virtual int FireUnsubscribed(MQTTUnsubscribedEventParams *e) {...}

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