Class: Client

.MQTT.Client(host, port, path, clientId)

new Client(host, port, path, clientId)

The JavaScript application communicates to the server using a Paho.MQTT.Client object.

Most applications will create just one Client object and then call its connect() method, however applications can create more than one Client object if they wish. In this case the combination of host, port and clientId attributes must be different for each Client object.

The send, subscribe and unsubscribe methods are implemented as asynchronous JavaScript methods (even though the underlying protocol exchange might be synchronous in nature). This means they signal their completion by calling back to the application, via Success or Failure callback functions provided by the application on the method in question. Such callbacks are called at most once per method invocation and do not persist beyond the lifetime of the script that made the invocation.

In contrast there are some callback functions, most notably onMessageArrived, that are defined on the Paho.MQTT.Client object. These may get called multiple times, and aren't directly related to specific method invocations made by the client.

Parameters:
Name Type Description
host string the address of the messaging server, as a fully qualified WebSocket URI, as a DNS name or dotted decimal IP address.
port number the port number to connect to - only required if host is not a URI
path string the path on the host to connect to - only used if host is not a URI. Default: '/mqtt'.
clientId string the Messaging client identifier, between 1 and 23 characters in length.
Properties:
Name Type Description
host string read only the server's DNS hostname or dotted decimal IP address.
port number read only the server's port.
path string read only the server's path.
clientId string read only used when connecting to the server.
onConnectionLost function called when a connection has been lost. after a connect() method has succeeded. Establish the call back used when a connection has been lost. The connection may be lost because the client initiates a disconnect or because the server or network cause the client to be disconnected. The disconnect call back may be called without the connectionComplete call back being invoked if, for example the client fails to connect. A single response object parameter is passed to the onConnectionLost callback containing the following fields:
  1. errorCode
  2. errorMessage
onMessageDelivered function called when a message has been delivered. All processing that this Client will ever do has been completed. So, for example, in the case of a Qos=2 message sent by this client, the PubComp flow has been received from the server and the message has been removed from persistent storage before this callback is invoked. Parameters passed to the onMessageDelivered callback are:
  1. Paho.MQTT.Message that was delivered.
onMessageArrived function called when a message has arrived in this Paho.MQTT.client. Parameters passed to the onMessageArrived callback are:
  1. Paho.MQTT.Message that has arrived.
onConnected function called when a connection is successfully made to the server. after a connect() method. Parameters passed to the onConnected callback are:
  1. reconnect (boolean) - If true, the connection was the result of a reconnect.
  2. URI (string) - The URI used to connect to the server.
disconnectedPublishing boolean if set, will enable disconnected publishing in in the event that the connection to the server is lost.
disconnectedBufferSize number Used to set the maximum number of messages that the disconnected buffer will hold before rejecting new messages. Default size: 5000 messages
trace function called whenever trace is called. TODO
Source:

Methods

connect(connectOptions)

Connect this Messaging client to its server.
Parameters:
Name Type Description
connectOptions object Attributes used with the connection.
Properties
Name Type Description
timeout number If the connect has not succeeded within this number of seconds, it is deemed to have failed. The default is 30 seconds.
userName string Authentication username for this connection.
password string Authentication password for this connection.
willMessage Paho.MQTT.Message sent by the server when the client disconnects abnormally.
keepAliveInterval number the server disconnects this client if there is no activity for this number of seconds. The default value of 60 seconds is assumed if not set.
cleanSession boolean if true(default) the client and server persistent state is deleted on successful connect.
useSSL boolean if present and true, use an SSL Websocket connection.
invocationContext object passed to the onSuccess callback or onFailure callback.
onSuccess function called when the connect acknowledgement has been received from the server. A single response object parameter is passed to the onSuccess callback containing the following fields:
  1. invocationContext as passed in to the onSuccess method in the connectOptions.
onFailure function called when the connect request has failed or timed out. A single response object parameter is passed to the onFailure callback containing the following fields:
  1. invocationContext as passed in to the onFailure method in the connectOptions.
  2. errorCode a number indicating the nature of the error.
  3. errorMessage text describing the error.
hosts array If present this contains either a set of hostnames or fully qualified WebSocket URIs (ws://mqtt.eclipse.org:80/mqtt), that are tried in order in place of the host and port paramater on the construtor. The hosts are tried one at at time in order until one of then succeeds.
ports array If present the set of ports matching the hosts. If hosts contains URIs, this property is not used.
reconnect boolean Sets whether the client will automatically attempt to reconnect to the server if the connection is lost.
  • If set to false, the client will not attempt to automatically reconnect to the server in the event that the connection is lost.
  • If set to true, in the event that the connection is lost, the client will attempt to reconnect to the server. It will initially wait 1 second before it attempts to reconnect, for every failed reconnect attempt, the delay will double until it is at 2 minutes at which point the delay will stay at 2 minutes.
mqttVersion number The version of MQTT to use to connect to the MQTT Broker.
  • 3 - MQTT V3.1
  • 4 - MQTT V3.1.1
mqttVersionExplicit boolean If set to true, will force the connection to use the selected MQTT Version or will fail to connect.
uris array If present, should contain a list of fully qualified WebSocket uris (e.g. ws://mqtt.eclipse.org:80/mqtt), that are tried in order in place of the host and port parameter of the construtor. The uris are tried one at a time in order until one of them succeeds. Do not use this in conjunction with hosts as the hosts array will be converted to uris and will overwrite this property.
Source:
Throws:
If the client is not in disconnected state. The client must have received connectionLost or disconnected before calling connect for a second or subsequent time.
Type
InvalidState

disconnect()

Normal disconnect of this Messaging client from its server.
Source:
Throws:
if the client is already disconnected.
Type
InvalidState

getTraceLog() → {Array.<Object>}

Get the contents of the trace log.
Source:
Returns:
tracebuffer containing the time ordered trace records.
Type
Array.<Object>

publish(topic, payload, qos, retained)

Publish a message to the consumers of the destination in the Message. Synonym for Paho.Mqtt.Client#send
Parameters:
Name Type Description
topic string | Paho.MQTT.Message mandatory The name of the topic to which the message is to be published. - If it is the only parameter, used as Paho.MQTT.Message object.
payload String | ArrayBuffer The message data to be published.
qos number The Quality of Service used to deliver the message.
0 Best effort (default).
1 At least once.
2 Exactly once.
retained Boolean If true, the message is to be retained by the server and delivered to both current and future subscriptions. If false the server only delivers the message to current subscribers, this is the default for new Messages. A received message has the retained boolean set to true if the message was published with the retained boolean set to true and the subscrption was made after the message has been published.
Source:
Throws:
if the client is not connected.
Type
InvalidState

send(topic, payload, qos, retained)

Send a message to the consumers of the destination in the Message.
Parameters:
Name Type Description
topic string | Paho.MQTT.Message mandatory The name of the destination to which the message is to be sent. - If it is the only parameter, used as Paho.MQTT.Message object.
payload String | ArrayBuffer The message data to be sent.
qos number The Quality of Service used to deliver the message.
0 Best effort (default).
1 At least once.
2 Exactly once.
retained Boolean If true, the message is to be retained by the server and delivered to both current and future subscriptions. If false the server only delivers the message to current subscribers, this is the default for new Messages. A received message has the retained boolean set to true if the message was published with the retained boolean set to true and the subscrption was made after the message has been published.
Source:
Throws:
if the client is not connected.
Type
InvalidState

startTrace()

Start tracing.
Source:

stopTrace()

Stop tracing.
Source:

subscribe(filter, subscribeOptions)

Subscribe for messages, request receipt of a copy of messages sent to the destinations described by the filter.
Parameters:
Name Type Description
filter string describing the destinations to receive messages from.
subscribeOptions object used to control the subscription
Properties
Name Type Description
qos number the maiximum qos of any publications sent as a result of making this subscription.
invocationContext object passed to the onSuccess callback or onFailure callback.
onSuccess function called when the subscribe acknowledgement has been received from the server. A single response object parameter is passed to the onSuccess callback containing the following fields:
  1. invocationContext if set in the subscribeOptions.
onFailure function called when the subscribe request has failed or timed out. A single response object parameter is passed to the onFailure callback containing the following fields:
  1. invocationContext - if set in the subscribeOptions.
  2. errorCode - a number indicating the nature of the error.
  3. errorMessage - text describing the error.
timeout number which, if present, determines the number of seconds after which the onFailure calback is called. The presence of a timeout does not prevent the onSuccess callback from being called when the subscribe completes.
Source:
Throws:
if the client is not in connected state.
Type
InvalidState

unsubscribe(filter, unsubscribeOptions)

Unsubscribe for messages, stop receiving messages sent to destinations described by the filter.
Parameters:
Name Type Description
filter string describing the destinations to receive messages from.
unsubscribeOptions object used to control the subscription
Properties
Name Type Description
invocationContext object passed to the onSuccess callback or onFailure callback.
onSuccess function called when the unsubscribe acknowledgement has been received from the server. A single response object parameter is passed to the onSuccess callback containing the following fields:
  1. invocationContext - if set in the unsubscribeOptions.
onFailure function called when the unsubscribe request has failed or timed out. A single response object parameter is passed to the onFailure callback containing the following fields:
  1. invocationContext - if set in the unsubscribeOptions.
  2. errorCode - a number indicating the nature of the error.
  3. errorMessage - text describing the error.
timeout number which, if present, determines the number of seconds after which the onFailure callback is called. The presence of a timeout does not prevent the onSuccess callback from being called when the unsubscribe completes
Source:
Throws:
if the client is not in connected state.
Type
InvalidState