MQTTClient.subscribe()

Overview

Subscribes to a topic filter on a connected MQTT broker.

Added in version 2.1.13

Format

var mqttClient = new MQTTClient(options);

//...

mqttClient.subscribe(subscription, onComplete, onError);

Value Description Type Required Notes
subscription An object or a string describing the subscription. String or Object Required If a string then the string represents the filter. Subscription object properties are described below.
onComplete A callback function that is called asynchronously if the subscribe completes. Function Optional When called, the first parameter is a Complete object as described below.
onError A callback function that is called asynchronously if the subscribe errors. Function Optional When called, the first parameter is an Error object as described below.

Subscription object properties

Value Description Type Required Notes
filter The topic filter. String Required May contain + symbol to represent a single intermediate level wildcard. May end with the # symbol to indicate a match with any further levels.
qos The quality of service for the message. Integer Optional

Possible values:

0 – at most once, where messages are delivered according to the best efforts of the operating environment. Message loss can occur.

1 – at least once, where messages are assured to arrive but duplicates can occur.

2 – exactly once, where messages are assured to arrive exactly once.
callback A callback function that is called when a message matching this filter is received. Function Optional The onMessage callback for the MQTTClient is always called first if it exists, followed by any matching filter subscriptions specified here. When called, the first parameter is a Message object as described below.

Message object properties

Value Description Type Notes
topic The topic for the message. String  
payload An ArrayBuffer containing the payload for the message. ArrayBuffer  
qos The quality of service for the message. Integer

Possible values:

0 – at most once, where messages are delivered according to the best efforts of the operating environment. Message loss can occur.

1 – at least once, where messages are assured to arrive but duplicates can occur.

2 – exactly once, where messages are assured to arrive exactly once.
retain A flag indicating if this message is a retained message. Boolean  
payloadAsString The payload bytes decoded as a UTF-8 string. String  

Complete object properties

Value Description Type

Notes
result A result code. Integer

Possible values:

•0 – Granted QoS 0

•1 – Granted QoS 1

•2 – Granted QoS 2

•128 – Unspecified error

•131 – Implementation specific error

•135 – Not authorized

•143 – Topic filter invalid

•145 – Packet identifier in use

•151 – Quota exceeded

•158 – Shared subscriptions not supported

•161 – Subscription identifiers not supported

•162 – Wildcard subscriptions not supported

Error object properties

Value Description Type

Notes
message A message that describes the failure. String May be undefined.
type A category for the type of failure. String  

Example

Copy 
/* Connect, then subscribe. Decode the binary data as a 32 bit unsigned integer, and log it.
 */

mqttClient = new MQTTClient({
    broker: "mqtt://mymqtt.example.com"
});

mqttClient.connect(function() {
    if(mqttClient.connected) {
        mqttClient.subscribe({
            filter: "this/+/+/test",
            callback: function(message) {
                var uintBuffer = new Uint32Array(message.payload);
                var firstInt = uintBuffer[0];
                Logger.info("got the number: " + firstInt);
            }
        }, function (complete) {
            Logger.debug("successfully subscribed: " + complete.result);
        }, function (error) {
            Logger.warning("failed subscribing: " + (error.message || error.type));
        });
    }
});