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 ipworksmq_mqtt_getcleansession(void* lpObj);
int ipworksmq_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* ipworksmq_mqtt_getclientid(void* lpObj);
int ipworksmq_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 ipworksmq_mqtt_getconnected(void* lpObj);
int ipworksmq_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

Firewall Property (MQTT Class)

A set of properties related to firewall access.

Syntax

• C++
• C
• Qt

IPWorksMQFirewall* GetFirewall();
int SetFirewall(IPWorksMQFirewall* val);

int ipworksmq_mqtt_getfirewallautodetect(void* lpObj);
int ipworksmq_mqtt_setfirewallautodetect(void* lpObj, int bFirewallAutoDetect);

int ipworksmq_mqtt_getfirewalltype(void* lpObj);
int ipworksmq_mqtt_setfirewalltype(void* lpObj, int iFirewallType);

char* ipworksmq_mqtt_getfirewallhost(void* lpObj);
int ipworksmq_mqtt_setfirewallhost(void* lpObj, const char* lpszFirewallHost);

char* ipworksmq_mqtt_getfirewallpassword(void* lpObj);
int ipworksmq_mqtt_setfirewallpassword(void* lpObj, const char* lpszFirewallPassword);

int ipworksmq_mqtt_getfirewallport(void* lpObj);
int ipworksmq_mqtt_setfirewallport(void* lpObj, int iFirewallPort);

char* ipworksmq_mqtt_getfirewalluser(void* lpObj);
int ipworksmq_mqtt_setfirewalluser(void* lpObj, const char* lpszFirewallUser);

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

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

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

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

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

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

Remarks

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

Data Type

IPWorksMQFirewall

IncomingMessages Property (MQTT Class)

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

Syntax

• C++
• C
• Qt

IPWorksMQList<IPWorksMQMQTTMessage>* GetIncomingMessages();

int ipworksmq_mqtt_getincomingmessagecount(void* lpObj);

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

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

int ipworksmq_mqtt_getincomingmessageduplicate(void* lpObj, int incomingmessageindex);

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

int ipworksmq_mqtt_getincomingmessagemessageexpinterval(void* lpObj, int incomingmessageindex);

int ipworksmq_mqtt_getincomingmessagepacketid(void* lpObj, int incomingmessageindex);

int ipworksmq_mqtt_getincomingmessagepayloadformatindicator(void* lpObj, int incomingmessageindex);

int ipworksmq_mqtt_getincomingmessageqos(void* lpObj, int incomingmessageindex);

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

int ipworksmq_mqtt_getincomingmessageretained(void* lpObj, int incomingmessageindex);

int ipworksmq_mqtt_getincomingmessagestate(void* lpObj, int incomingmessageindex);

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

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

int ipworksmq_mqtt_getincomingmessagetopicalias(void* lpObj, int incomingmessageindex);

int GetIncomingMessageCount();

QString GetIncomingMessageContentType(int iIncomingMessageIndex);

QString GetIncomingMessageCorrelationData(int iIncomingMessageIndex);

bool GetIncomingMessageDuplicate(int iIncomingMessageIndex);

QByteArray GetIncomingMessageMessage(int iIncomingMessageIndex);

int GetIncomingMessageMessageExpInterval(int iIncomingMessageIndex);

int GetIncomingMessagePacketId(int iIncomingMessageIndex);

int GetIncomingMessagePayloadFormatIndicator(int iIncomingMessageIndex);

int GetIncomingMessageQoS(int iIncomingMessageIndex);

QString GetIncomingMessageResponseTopic(int iIncomingMessageIndex);

bool GetIncomingMessageRetained(int iIncomingMessageIndex);

int GetIncomingMessageState(int iIncomingMessageIndex);

QString GetIncomingMessageSubscriptionIdentifiers(int iIncomingMessageIndex);

QString GetIncomingMessageTopic(int iIncomingMessageIndex);

int GetIncomingMessageTopicAlias(int iIncomingMessageIndex);

Remarks

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

Incoming messages with a QoS of 1 follow these steps:

1. The message is added to IncomingMessages 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 IncomingMessages.
5. The MessageIn event is fired.

Incoming messages with a QoS of 2 follow these steps:

1. The message is added to IncomingMessages 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 IncomingMessages.
7. The MessageIn event is fired.

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

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

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

Data Type

IPWorksMQMQTTMessage

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 ipworksmq_mqtt_getkeepaliveinterval(void* lpObj);
int ipworksmq_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* ipworksmq_mqtt_getlocalhost(void* lpObj);
int ipworksmq_mqtt_setlocalhost(void* lpObj, const char* lpszLocalHost);

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

Default Value

""

Remarks

This 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 multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

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 multihomed 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 ipworksmq_mqtt_getlocalport(void* lpObj);
int ipworksmq_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 on the client side.

Data Type

Integer

OutgoingMessages Property (MQTT Class)

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

Syntax

• C++
• C
• Qt

IPWorksMQList<IPWorksMQMQTTMessage>* GetOutgoingMessages();

int ipworksmq_mqtt_getoutgoingmessagecount(void* lpObj);

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

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

int ipworksmq_mqtt_getoutgoingmessageduplicate(void* lpObj, int outgoingmessageindex);

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

int ipworksmq_mqtt_getoutgoingmessagemessageexpinterval(void* lpObj, int outgoingmessageindex);

int ipworksmq_mqtt_getoutgoingmessagepacketid(void* lpObj, int outgoingmessageindex);

int ipworksmq_mqtt_getoutgoingmessagepayloadformatindicator(void* lpObj, int outgoingmessageindex);

int ipworksmq_mqtt_getoutgoingmessageqos(void* lpObj, int outgoingmessageindex);

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

int ipworksmq_mqtt_getoutgoingmessageretained(void* lpObj, int outgoingmessageindex);

int ipworksmq_mqtt_getoutgoingmessagestate(void* lpObj, int outgoingmessageindex);

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

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

int ipworksmq_mqtt_getoutgoingmessagetopicalias(void* lpObj, int outgoingmessageindex);

int GetOutgoingMessageCount();

QString GetOutgoingMessageContentType(int iOutgoingMessageIndex);

QString GetOutgoingMessageCorrelationData(int iOutgoingMessageIndex);

bool GetOutgoingMessageDuplicate(int iOutgoingMessageIndex);

QByteArray GetOutgoingMessageMessage(int iOutgoingMessageIndex);

int GetOutgoingMessageMessageExpInterval(int iOutgoingMessageIndex);

int GetOutgoingMessagePacketId(int iOutgoingMessageIndex);

int GetOutgoingMessagePayloadFormatIndicator(int iOutgoingMessageIndex);

int GetOutgoingMessageQoS(int iOutgoingMessageIndex);

QString GetOutgoingMessageResponseTopic(int iOutgoingMessageIndex);

bool GetOutgoingMessageRetained(int iOutgoingMessageIndex);

int GetOutgoingMessageState(int iOutgoingMessageIndex);

QString GetOutgoingMessageSubscriptionIdentifiers(int iOutgoingMessageIndex);

QString GetOutgoingMessageTopic(int iOutgoingMessageIndex);

int GetOutgoingMessageTopicAlias(int iOutgoingMessageIndex);

Remarks

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

Outgoing messages with a QoS of 1 follow these steps:

1. The class sends the PUBLISH packet, then adds the message to OutgoingMessages.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessages.
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 OutgoingMessages.
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 OutgoingMessages.
7. The MessageOut event is fired.

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

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

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

Data Type

IPWorksMQMQTTMessage

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* ipworksmq_mqtt_getpassword(void* lpObj);
int ipworksmq_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 ipworksmq_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* ipworksmq_mqtt_getremotehost(void* lpObj);
int ipworksmq_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 ipworksmq_mqtt_getremoteport(void* lpObj);
int ipworksmq_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

SSLAcceptServerCert Property (MQTT Class)

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

Syntax

• C++
• C
• Qt

IPWorksMQCertificate* GetSSLAcceptServerCert();
int SetSSLAcceptServerCert(IPWorksMQCertificate* val);

char* ipworksmq_mqtt_getsslacceptservercerteffectivedate(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertexpirationdate(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertextendedkeyusage(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertfingerprint(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertfingerprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertfingerprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertissuer(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertprivatekey(void* lpObj);

int ipworksmq_mqtt_getsslacceptservercertprivatekeyavailable(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertprivatekeycontainer(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertpublickey(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertpublickeyalgorithm(void* lpObj);

int ipworksmq_mqtt_getsslacceptservercertpublickeylength(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertserialnumber(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertsignaturealgorithm(void* lpObj);

int ipworksmq_mqtt_getsslacceptservercertstore(void* lpObj, char** lpSSLAcceptServerCertStore, int* lenSSLAcceptServerCertStore);
int ipworksmq_mqtt_setsslacceptservercertstore(void* lpObj, const char* lpSSLAcceptServerCertStore, int lenSSLAcceptServerCertStore);

char* ipworksmq_mqtt_getsslacceptservercertstorepassword(void* lpObj);
int ipworksmq_mqtt_setsslacceptservercertstorepassword(void* lpObj, const char* lpszSSLAcceptServerCertStorePassword);

int ipworksmq_mqtt_getsslacceptservercertstoretype(void* lpObj);
int ipworksmq_mqtt_setsslacceptservercertstoretype(void* lpObj, int iSSLAcceptServerCertStoreType);

char* ipworksmq_mqtt_getsslacceptservercertsubjectaltnames(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertthumbprintmd5(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertthumbprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertthumbprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertusage(void* lpObj);

int ipworksmq_mqtt_getsslacceptservercertusageflags(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertversion(void* lpObj);

char* ipworksmq_mqtt_getsslacceptservercertsubject(void* lpObj);
int ipworksmq_mqtt_setsslacceptservercertsubject(void* lpObj, const char* lpszSSLAcceptServerCertSubject);

int ipworksmq_mqtt_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int ipworksmq_mqtt_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QString GetSSLAcceptServerCertEffectiveDate();

QString GetSSLAcceptServerCertExpirationDate();

QString GetSSLAcceptServerCertExtendedKeyUsage();

QString GetSSLAcceptServerCertFingerprint();

QString GetSSLAcceptServerCertFingerprintSHA1();

QString GetSSLAcceptServerCertFingerprintSHA256();

QString GetSSLAcceptServerCertIssuer();

QString GetSSLAcceptServerCertPrivateKey();

bool GetSSLAcceptServerCertPrivateKeyAvailable();

QString GetSSLAcceptServerCertPrivateKeyContainer();

QString GetSSLAcceptServerCertPublicKey();

QString GetSSLAcceptServerCertPublicKeyAlgorithm();

int GetSSLAcceptServerCertPublicKeyLength();

QString GetSSLAcceptServerCertSerialNumber();

QString GetSSLAcceptServerCertSignatureAlgorithm();

QByteArray GetSSLAcceptServerCertStore();
int SetSSLAcceptServerCertStore(QByteArray qbaSSLAcceptServerCertStore);

QString GetSSLAcceptServerCertStorePassword();
int SetSSLAcceptServerCertStorePassword(QString qsSSLAcceptServerCertStorePassword);

int GetSSLAcceptServerCertStoreType();
int SetSSLAcceptServerCertStoreType(int iSSLAcceptServerCertStoreType);

QString GetSSLAcceptServerCertSubjectAltNames();

QString GetSSLAcceptServerCertThumbprintMD5();

QString GetSSLAcceptServerCertThumbprintSHA1();

QString GetSSLAcceptServerCertThumbprintSHA256();

QString GetSSLAcceptServerCertUsage();

int GetSSLAcceptServerCertUsageFlags();

QString GetSSLAcceptServerCertVersion();

QString GetSSLAcceptServerCertSubject();
int SetSSLAcceptServerCertSubject(QString qsSSLAcceptServerCertSubject);

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

Remarks

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

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

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

Data Type

IPWorksMQCertificate

SSLCert Property (MQTT Class)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C++
• C
• Qt

IPWorksMQCertificate* GetSSLCert();
int SetSSLCert(IPWorksMQCertificate* val);

char* ipworksmq_mqtt_getsslcerteffectivedate(void* lpObj);

char* ipworksmq_mqtt_getsslcertexpirationdate(void* lpObj);

char* ipworksmq_mqtt_getsslcertextendedkeyusage(void* lpObj);

char* ipworksmq_mqtt_getsslcertfingerprint(void* lpObj);

char* ipworksmq_mqtt_getsslcertfingerprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslcertfingerprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslcertissuer(void* lpObj);

char* ipworksmq_mqtt_getsslcertprivatekey(void* lpObj);

int ipworksmq_mqtt_getsslcertprivatekeyavailable(void* lpObj);

char* ipworksmq_mqtt_getsslcertprivatekeycontainer(void* lpObj);

char* ipworksmq_mqtt_getsslcertpublickey(void* lpObj);

char* ipworksmq_mqtt_getsslcertpublickeyalgorithm(void* lpObj);

int ipworksmq_mqtt_getsslcertpublickeylength(void* lpObj);

char* ipworksmq_mqtt_getsslcertserialnumber(void* lpObj);

char* ipworksmq_mqtt_getsslcertsignaturealgorithm(void* lpObj);

int ipworksmq_mqtt_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int ipworksmq_mqtt_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* ipworksmq_mqtt_getsslcertstorepassword(void* lpObj);
int ipworksmq_mqtt_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int ipworksmq_mqtt_getsslcertstoretype(void* lpObj);
int ipworksmq_mqtt_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* ipworksmq_mqtt_getsslcertsubjectaltnames(void* lpObj);

char* ipworksmq_mqtt_getsslcertthumbprintmd5(void* lpObj);

char* ipworksmq_mqtt_getsslcertthumbprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslcertthumbprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslcertusage(void* lpObj);

int ipworksmq_mqtt_getsslcertusageflags(void* lpObj);

char* ipworksmq_mqtt_getsslcertversion(void* lpObj);

char* ipworksmq_mqtt_getsslcertsubject(void* lpObj);
int ipworksmq_mqtt_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int ipworksmq_mqtt_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int ipworksmq_mqtt_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

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

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

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

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

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

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

Remarks

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

Data Type

IPWorksMQCertificate

SSLEnabled Property (MQTT Class)

This property indicates whether Transport Layer Security/Secure Sockets Layer (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 ipworksmq_mqtt_getsslenabled(void* lpObj);
int ipworksmq_mqtt_setsslenabled(void* lpObj, int bSSLEnabled);

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

Default Value

FALSE

Remarks

This property 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)

The Secure Sockets Layer/Transport Layer Security (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 ipworksmq_mqtt_getsslprovider(void* lpObj);
int ipworksmq_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 as follows:

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

SSLServerCert Property (MQTT Class)

The server certificate for the last established connection.

Syntax

• C++
• C
• Qt

IPWorksMQCertificate* GetSSLServerCert();

char* ipworksmq_mqtt_getsslservercerteffectivedate(void* lpObj);

char* ipworksmq_mqtt_getsslservercertexpirationdate(void* lpObj);

char* ipworksmq_mqtt_getsslservercertextendedkeyusage(void* lpObj);

char* ipworksmq_mqtt_getsslservercertfingerprint(void* lpObj);

char* ipworksmq_mqtt_getsslservercertfingerprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslservercertfingerprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslservercertissuer(void* lpObj);

char* ipworksmq_mqtt_getsslservercertprivatekey(void* lpObj);

int ipworksmq_mqtt_getsslservercertprivatekeyavailable(void* lpObj);

char* ipworksmq_mqtt_getsslservercertprivatekeycontainer(void* lpObj);

char* ipworksmq_mqtt_getsslservercertpublickey(void* lpObj);

char* ipworksmq_mqtt_getsslservercertpublickeyalgorithm(void* lpObj);

int ipworksmq_mqtt_getsslservercertpublickeylength(void* lpObj);

char* ipworksmq_mqtt_getsslservercertserialnumber(void* lpObj);

char* ipworksmq_mqtt_getsslservercertsignaturealgorithm(void* lpObj);

int ipworksmq_mqtt_getsslservercertstore(void* lpObj, char** lpSSLServerCertStore, int* lenSSLServerCertStore);

char* ipworksmq_mqtt_getsslservercertstorepassword(void* lpObj);

int ipworksmq_mqtt_getsslservercertstoretype(void* lpObj);

char* ipworksmq_mqtt_getsslservercertsubjectaltnames(void* lpObj);

char* ipworksmq_mqtt_getsslservercertthumbprintmd5(void* lpObj);

char* ipworksmq_mqtt_getsslservercertthumbprintsha1(void* lpObj);

char* ipworksmq_mqtt_getsslservercertthumbprintsha256(void* lpObj);

char* ipworksmq_mqtt_getsslservercertusage(void* lpObj);

int ipworksmq_mqtt_getsslservercertusageflags(void* lpObj);

char* ipworksmq_mqtt_getsslservercertversion(void* lpObj);

char* ipworksmq_mqtt_getsslservercertsubject(void* lpObj);

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

QString GetSSLServerCertEffectiveDate();

QString GetSSLServerCertExpirationDate();

QString GetSSLServerCertExtendedKeyUsage();

QString GetSSLServerCertFingerprint();

QString GetSSLServerCertFingerprintSHA1();

QString GetSSLServerCertFingerprintSHA256();

QString GetSSLServerCertIssuer();

QString GetSSLServerCertPrivateKey();

bool GetSSLServerCertPrivateKeyAvailable();

QString GetSSLServerCertPrivateKeyContainer();

QString GetSSLServerCertPublicKey();

QString GetSSLServerCertPublicKeyAlgorithm();

int GetSSLServerCertPublicKeyLength();

QString GetSSLServerCertSerialNumber();

QString GetSSLServerCertSignatureAlgorithm();

QByteArray GetSSLServerCertStore();

QString GetSSLServerCertStorePassword();

int GetSSLServerCertStoreType();

QString GetSSLServerCertSubjectAltNames();

QString GetSSLServerCertThumbprintMD5();

QString GetSSLServerCertThumbprintSHA1();

QString GetSSLServerCertThumbprintSHA256();

QString GetSSLServerCertUsage();

int GetSSLServerCertUsageFlags();

QString GetSSLServerCertVersion();

QString GetSSLServerCertSubject();

QByteArray GetSSLServerCertEncoded();

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Data Type

IPWorksMQCertificate

Timeout Property (MQTT Class)

This property includes the 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 ipworksmq_mqtt_gettimeout(void* lpObj);
int ipworksmq_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.

Note: By default, all timeouts are inactivity timeouts, that is, 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* ipworksmq_mqtt_getuser(void* lpObj);
int ipworksmq_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 ipworksmq_mqtt_getversion(void* lpObj);
int ipworksmq_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* ipworksmq_mqtt_getwillmessage(void* lpObj);
int ipworksmq_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* ipworksmq_mqtt_getwilltopic(void* lpObj);
int ipworksmq_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* ipworksmq_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 ipworksmq_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 ipworksmq_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 ipworksmq_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)

This method processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int ipworksmq_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 ipworksmq_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 ipworksmq_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 OutgoingMessages.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessages.
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 OutgoingMessages.
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 OutgoingMessages.
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 ipworksmq_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 OutgoingMessages.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessages.
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 OutgoingMessages.
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 OutgoingMessages.
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)

This method will reset the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksmq_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 ipworksmq_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* ipworksmq_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 ipworksmq_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 ipworksmq_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)

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

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

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

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

Fired when information is available 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 IPWORKSMQ_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 IPWORKSMQ_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 IPWORKSMQ_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 IncomingMessages collection or OutgoingMessages collection.
• 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 IncomingMessages 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 IncomingMessages.
5. The MessageIn event is fired.

Incoming messages with a QoS of 2 follow these steps:

1. The message is added to IncomingMessages 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 IncomingMessages.
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 OutgoingMessages.
2. The class waits to receive a PUBACK (publish acknowledgment) packet.
3. The MessageAck event is fired.
4. The message is removed from OutgoingMessages.
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 OutgoingMessages.
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 OutgoingMessages.
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 IPWORKSMQ_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 IPWORKSMQ_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 IPWORKSMQ_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 IPWORKSMQ_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)

Fired when secure connection progress messages are available.

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

Certificate Type

This is the digital certificate being used.

Syntax

IPWorksMQCertificate (declared in ipworksmq.h)

Remarks

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

Fields

Constructors

Certificate()

Certificate(const char* lpEncoded, int lenEncoded)

Certificate(int iStoreType, const char* lpStore, int lenStore, const char* lpszStorePassword, const char* lpszSubject)

Firewall Type

The firewall the component will connect through.

Syntax

IPWorksMQFirewall (declared in ipworksmq.h)

Remarks

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

Fields

Constructors

Firewall()

MQTTMessage Type

An MQTT message.

Syntax

IPWorksMQMQTTMessage (declared in ipworksmq.h)

Remarks

This type represents an MQTT message.

Fields

IPWorksMQList Type

Syntax

IPWorksMQList<T> (declared in ipworksmq.h)

Remarks

IPWorksMQList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the MQTT class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

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
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

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

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

Socket Config Settings

Trappable Errors (MQTT Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

MQTT Errors

WebSocket Errors

HTTP Errors

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

TCPClient Errors

SSL Errors

TCP/IP Errors