Client

.MQTT. Client

new Client(host, port, path, clientId)

Source:
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.

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.

Methods

connect(connectOptions)

Source:

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

Source:

Normal disconnect of this Messaging client from its server.

Throws:

if the client is already disconnected.

Type
InvalidState

getTraceLog() → {Array.<Object>}

Source:

Get the contents of the trace log.

Returns:

tracebuffer containing the time ordered trace records.

Type
Array.<Object>

send(topic, payload, qos, retained)

Source:

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.
Throws:

if the client is not connected.

Type
InvalidState

startTrace()

Source:

Start tracing.

stopTrace()

Source:

Stop tracing.

subscribe(filter, subscribeOptions)

Source:

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.
Throws:

if the client is not in connected state.

Type
InvalidState

unsubscribe(filter, unsubscribeOptions)

Source:

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

if the client is not in connected state.

Type
InvalidState