Global

Method Summary

openSession
Connects to the MQTT.Cool server specified by the provided address, to request the opening of a new session, which will be encapsulated into an MQTTCoolSession instance.

Method Detail

openSession(serverAddress, usernameopt, nullable, passwordopt, nullable, listenernon-null)

Connects to the MQTT.Cool server specified by the provided address, to request the opening of a new session, which will be encapsulated into an MQTTCoolSession instance.

Once the connection is established, a new instance of MQTTCoolSession will be provided through asynchronous invocation of the MQTTCoolListener#onConnectionSuccess method.

The method can be invoked multiple times to create distinct sessions against the same MQTT.Cool server if the same address is supplied.

Parameters:
Name Type Argument Description
serverAddress string The address of the MQTT.Cool server.
username string <optional>
<nullable>
 The username to be used for the authentication on MQTT.Cool.
password string <optional>
<nullable>
 The password to be used for the authentication on MQTT.Cool.

This argument can be passed only if username is supplied too; if it is not the case, an exception will be thrown.
listener MQTTCoolListener The listener that will receive the events related to creation of MQTTCoolSession. It is not mandatory that this parameter implements the MQTTCoolListener interface, but at least it should supply an implementation of the MQTTCoolListener#onConnectionSuccess method, otherwise it would be impossible to get the reference to the MQTTCoolSession instance.

Note that this parameter has to be passed as last argument; if it is not the case, an exception will be thrown.
Throws:
Example

Allowed invocation forms of openSession.

  // Passing all parameters (username and password might be also null)
  openSession('http://my.push.server', 'username', 'password', listener);

  // Passing only serveAddress, username (which might be null) and listener.
  openSession('http://my.push.server', 'username', listener);

  // Passing only serverAddress and listener.
  openSession('http://my.push.server', listener);

Type Definitions

ConnectOptions

Object containing the properties which specify the options to be used for controlling the connection to the target MQTT broker. If not supplied to the MqttClient#connect method, then the default values apply as specified below.

Note that if the provided properties are not of the expected type, then an exception will be thrown on MqttClient#connect invocation.

Type:
  • Object
Properties:
Name Type Argument Default Description
username string <optional>
 The username to be used for authenticating with the target MQTT broker.

Note that an empty string ('') is considered as a valid username.
password string <optional>
 The password to be used for authenticating with the target MQTT broker.

Note that an empty string ('') is considered a valid password.
willMessage Message <optional>
 The message to be stored to the target MQTT broker and that is to be published to the Will Topic if the end-to-end connection closes abruptly (or any other event mentioned in the MQTT Protocol Specifications).

Note that in the case of shared connection, which does not allow Will Message, the property must be left unset (or, at least, should be set to null), otherwise an exception will be thrown on MqttClient#connect invocation.
cleanSession boolean <optional>
 true If set to false, indicates that session persistence is required, otherwise any previous session will be discarded upon successful connection.

Note that in the case of shared connection, which does not allow a persistent session, the flag must be set to true or left unset, otherwise an exception will be thrown on MqttClient#connect invocation.
storage MqttStorage <optional>
 MqttStorage instance, which provides a custom implementation of the persistence layer, needed to store the session as required when the cleanSession flag is set to false. If no instance is provided (or null), then the default implementation based on the localStorage property supplied by the browser will be used.

Before using the MqttStorage (either the provided custom implementation or the default one), a preliminary compliance self-test is performed and an exception will be thrown on MqttClient#connect invocation if the observed functioning is not as expected (for example due to some implementation errors). In particular, in the case of default implementation, the self-test could fail because of issues related to the usage of the localStorage property, for example due to the switching to the Privacy Mode, which may affect the proper functioning of the local storage in some browsers.

Note that in the case of shared connection, which does not allow a persistent session, the property must be left unset (or, at least, should be set to null), otherwise an exception will be thrown on MqttClient#connect invocation.
onSuccess OnConnectionSuccess <optional>
 The callback function invoked upon a successful acknowledgement of the connection request to the target MQTT broker; afterwards, the MqttClient instance switches to the connected status.
onFailure OnConnectionFailure <optional>
 The callback function invoked in the case of any issue with either the target MQTT broker or the MQTT.Cool server.
onNotAuthorized OnConnectionNotAuthorized <optional>
 The callback function invoked when the plugged Hook denies the authorization to connect to the target MQTT broker, or raises an issue while performing its checking activities.
See:

OnConnectionFailure(responseObjectnon-null)

Callback function that is invoked in the case of connection failure to the target MQTT broker.
Parameters:
Name Type Description
responseObject Object The object whose properties contain the details about the connection failure.
Properties
Name Type Description
errorCode number The error code, which can be one of the values specified in the following sections:
  • The Connect Return codes as detailed in the MQTT Protocol Specification, sent by the target MQTT broker to MQTT.Cool (and from there forwarded to MqttClient):
    • 1 => Connection Refused: unacceptable protocol version
    • 2 => Connection Refused: identifier rejected
    • 3 => Connection Refused: server unavailable
    • 4 => Connection Refused: bad user name or password
    • 5 => Connection Refused: not authorized
  • Configuration and connection issues:
    • 9 => MQTT broker configuration not valid
    • 10 => Connection error to MQTT.Cool
      when the underlying MQTT.Cool connection has been interrupted just before issuing the connection request
    • 11 => Connection error to the MQTT broker
      when the broker connection cannot be established, due to any network issue or problem in the MQTT broker process
    • 12 => Disconnection from MQTT.Cool
      when the MQTTCoolSession#close method has been invoked on the MQTTCoolSession instance used to create the MqttClient instance, just before an acknowledgement of the connection request is received
  • Server error:
    • 100 => {'errorCode':<code>, 'errorMessage':<message>}
      when an MQTT.Cool specific issue occurs, whose details are formatted as a JSON string in responseObject.errorMessage: see SubscriptionListener#onSubscriptionError for all possible values of <code> (consider only the positive ones) and <message>.
errorMessage string The description of the error, as specified above.
See:

OnConnectionLost(responseObjectnon-null)

Callback function that is invoked when the end-to-end connection is lost.
Parameters:
Name Type Description
responseObject Object The object whose properties contain the details about the connection lost event.
Properties
Name Type Description
errorCode number The error code, which can be one of the following:
  • 0 => Successful disconnection
    when MqttClient has initiated a regular disconnection (without waiting for a response sent back by MQTT.Cool)
  • 10 = Connection error to MQTT.Cool
    when the underlying MQTT.Cool connection has been interrupted and the reconnection attempts that follow have been stopped
  • 11 => Connection error to the MQTT broker
    when the broker connection has been interrupted
  • 12 => Disconnection from MQTT.Cool
    when the MQTTCoolSession#close method has been invoked on the MQTTCoolSession instance used to create the MqttClient instance
errorMessage string The description of the error, as specified above.
See:

OnConnectionNotAuthorized(responseObjectopt)

Callback function that is invoked when the plugged Hook denies the authorization to connect to the target MQTT broker, or raises an issue while performing its checking activities.

The authorization phase is triggered once the connection request received by MQTT.Cool is passed to the Hook, before the actual broker connection is established. In the case of authorization failure, the request is rejected immediately and a specific error is sent back by MQTT.Cool to MqttClient. As consequence of this, neither OnConnectionSuccess nor OnConnectionFailure will be called for the requested connection.

Parameters:
Name Type Argument Description
responseObject Object <optional>
 The object whose properties contain the details about the authorization failure. Note that the object is supplied only if the plugged Hook raises an issue while checking the authorization to connect to the MQTT broker, whereas nothing is supplied when the Hook simply denies the request.
Properties
Name Type Description
errorCode number The error code, which is dependent on the specific plugged Hook.
errorMessage string The description of the error, which is dependent on the specific plugged Hook.
See:

OnConnectionSuccess()

Callback function that is invoked upon a successful acknowledgement of the connection request to the target MQTT broker.
See:

OnMessageArrived(messagenon-null)

Callback function that is invoked upon receiving an Application Message.
Parameters:
Name Type Description
message Message The incoming Application Message.
See:

OnMessageDelivered(messagenon-null)

Callback function that is invoked when the delivery process of an Application Message completes.
Parameters:
Name Type Description
message Message The delivered Application Message.
See:

OnMessageNotAuthorized(messagenon-null, responseObjectopt)

Callback function that is invoked when the plugged Hook denies the authorization for publishing the specified message, or raises an issue while performing its checking activities.
Parameters:
Name Type Argument Description
message Message The Application Message that failed to be authorized.
responseObject Object <optional>
 The object whose properties contain the details about the authorization failure. Note that the object is supplied only if the plugged Hook raises an issue while checking the authorization for the requested publishing, whereas nothing is supplied when the Hook simply denies the request.
Properties
Name Type Description
errorCode number The error code, which is dependent on the specific plugged Hook.
errorMessage string The description of the error, which is dependent on the specific plugged Hook.
See:

OnReconnectionComplete()

Callback function that is invoked upon a successful restoration of the end-to-end connection, which has been interrupted because of an issue between MqttClient and MQTT.Cool.
See:

OnReconnectionStart()

Callback function that is invoked when an attempt to re-establish the end-to-end connection, which has been interrupted because of an issue between MqttClient and MQTT.Cool, has started.
See:

OnSubscriptionFailure(responseObjectnon-null)

Callback function that is invoked in the case of failure of the requested subscription.
Parameters:
Name Type Description
responseObject Object The object whose properties contain the details about the connection failure.
Properties
Name Type Description
errorCode number The error code of the failure, as returned by the MQTT broker.
See:

OnSubscriptionNotAuthorized(responseObjectopt, non-null)

Callback function that is invoked when the plugged Hook denies the authorization for the requested subscription, or raises an issue while performing its checking activities.

The authorization phase is triggered once the subscription request received by MQTT.Cool is passed to the Hook, before being sent to the target MQTT broker. In the case of authorization failure, the request is rejected immediately and a specific error is sent back by MQTT.Cool to MqttClient. As consequence of this, the OnSubscriptionSuccess will never be called for the requested subscription.

Parameters:
Name Type Argument Description
responseObject Object <optional>
 The object whose properties contain the details about the authorization failure. Note that the object is supplied only if the plugged Hook raises an issue while checking the authorization for the requested subscription, whereas nothing is supplied when the Hook simply denies the request.
Properties
Name Type Description
errorCode number The error code, which is dependent on the specific plugged Hook.
errorMessage string The description of the error, which is dependent on the specific plugged Hook.
See:

OnSubscriptionSuccess(responseObjectnon-null)

Callback function that is invoked upon a successful acknowledgement of the requested subscription.
Parameters:
Name Type Description
responseObject Object The object whose properties contain the details about the successful acknowledgement.
Properties
Name Type Description
grantedQos number The max Quality of Service level granted by the MQTT broker for the requested subscription.
See:

OnUnsubscribeFailure(responseObject)

Callback function that is invoked in the case of failure of the requested unsubscription.
Parameters:
Name Type Description
responseObject Object The object whose properties contain the details about the unsubscription failure.
Properties
Name Type Description
errorCode number The error code.
errorMessage string The description of the error.
See:

OnUnsubscribeSuccess()

Callback function that is invoked upon a successful acknowledgement of the requested unsubscription.
See:

SubscribeOptions

Object containing the properties that specify the options to be used for controlling the subscription. If not supplied to the MqttClient#subscribe method, then the default values apply as specified below.

Note that if the provided properties are not of the expected type, then an exception will be thrown on MqttClient#subscribe invocation.

Type:
  • Object
Properties:
Name Type Argument Default Description
qos number <optional>
 0 The maximum Quality Of Service with which the the target MQTT broker is allowed to send Application Messages.

Note that any provided value different from 0, 1 and 2 will provoke an exception to be thrown on MqttClient#subscribe invocation.
maxFrequency number <optional>
 The maximum update frequency (expressed in updates per second) to be requested to MQTT.Cool for all messages subscribed with QoS 0. If not supplied, then the update frequency will be managed as unlimited.

Note that this feature is available only in the case of shared connection, whereas in the case of dedicated connection this value is ignored.

Note also that any provided value different from a positive number will provoke an exception to be thrown on MqttClient#subscribe invocation.
onSuccess OnSubscriptionSuccess <optional>
 The callback function invoked upon a successful acknowledgement of the requested subscription.
onFailure OnSubscriptionFailure <optional>
 The callback function invoked in the case of failure of the requested subscription.
onNotAuthorized OnSubscriptionNotAuthorized <optional>
 The callback function invoked when the plugged Hook denies the authorization for the requested subscription, or raises an issue while performing its checking activities.
See:

UnsubscribeOptions

Object containing the properties which specify the options to be used for controlling the unsubscription.

Note that if the provided properties are not of the expected type, then an exception will be thrown on MqttClient#unsubscribe invocation.

Type:
  • Object
Properties:
Name Type Argument Description
onSuccess OnUnsubscribeSuccess <optional>
 The callback function invoked upon a successful acknowledgement of the requested unsubscription.
onFailure OnUnsubscribeFailure <optional>
 The callback function expected to be called in case of failure of the requested unsubscription.

Note that this function is not actually employed by the current implementation of the library as the MQTT Protocol Specifications does not define any behavior in case of unsubscription failure. As a consequence of this, this function is only formally provided, but future use cannot be ruled out.
See: