File Explorer

1/*2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.3 * SPDX-License-Identifier: Apache-2.0.4 */5 6/**7 *8 * A module containing support for mqtt connection establishment and operations.9 *10 * @packageDocumentation11 * @module mqtt12 */13 14import { ICrtError } from './error';15 16/**17 * Quality of service control for mqtt publish operations18 *19 * @category MQTT20 */21export enum QoS {22    /**23     * QoS 0 - At most once delivery24     * The message is delivered according to the capabilities of the underlying network.25     * No response is sent by the receiver and no retry is performed by the sender.26     * The message arrives at the receiver either once or not at all.27     */28    AtMostOnce = 0,29 30    /**31     * QoS 1 - At least once delivery32     * This quality of service ensures that the message arrives at the receiver at least once.33     */34    AtLeastOnce = 1,35 36    /**37     * QoS 2 - Exactly once delivery38 39     * This is the highest quality of service, for use when neither loss nor40     * duplication of messages are acceptable. There is an increased overhead41     * associated with this quality of service.42 43     * Note that, while this client supports QoS 2, the AWS IoT Core service44     * does not support QoS 2 at time of writing (May 2020).45     */46    ExactlyOnce = 2,47}48 49/**50 * Possible types of data to send via publish.51 *52 * An ArrayBuffer will send its bytes without transformation.53 * An ArrayBufferView (DataView, Uint8Array, etc) will send its bytes without transformation.54 * A String will be sent with utf-8 encoding.55 * An Object will be sent as a JSON string with utf-8 encoding.56 *57 * @category MQTT58 */59export type Payload = string | Record<string, unknown> | ArrayBuffer | ArrayBufferView;60 61/**62 * Function called upon receipt of a Publish message on a subscribed topic.63 *64 * @param topic The topic to which the message was published.65 * @param payload The payload data.66 * @param dup DUP flag. If true, this might be re-delivery of an earlier67 *            attempt to send the message.68 * @param qos Quality of Service used to deliver the message.69 * @param retain Retain flag. If true, the message was sent as a result of70 *               a new subscription being made by the client. *71 *72 * @category MQTT73 */74export type OnMessageCallback = (topic: string, payload: ArrayBuffer, dup: boolean, qos: QoS, retain: boolean) => void;75 76/**77 * Every request sent returns an MqttRequest78 *79 * @category MQTT80 */81export interface MqttRequest {82    /** Packet ID being acknowledged when the request completes */83    packet_id?: number;84}85 86/**87 * The data returned from an on_connection_success callback88 *89 * @category MQTT90 */91export interface OnConnectionSuccessResult {92    /**93     * A boolean indicating if the connection resumed a session.94     */95    session_present: boolean;96    /**97     * An optional connect return code received from the server, if a connect return code was returned.98     */99    reason_code?: number;100}101 102/**103 * The data returned from an on_connection_failed callback104 *105 * @category MQTT106 */107export interface OnConnectionFailedResult {108    /**109     * Error description of the error that occurred110     */111    error: ICrtError;112}113 114/**115 * The data returned from the on_connection_closed callback116 *117 * @category MQTT118 */119export interface OnConnectionClosedResult {}120 121/**122 * Subscription SUBACK result123 *124 * @category MQTT125 */126export interface MqttSubscribeRequest extends MqttRequest {127    /** Topic filter of the SUBSCRIBE packet being acknowledged */128    topic: string;129    /** Maximum QoS granted by the server. This may be lower than the requested QoS. */130    qos: QoS;131    /** If an error occurred, the error code */132    error_code?: number;133}134 135/**136 * A Will message is published by the server if a client is lost unexpectedly.137 *138 * The Will message is stored on the server when a client connects.139 * It is published if the client connection is lost without the server140 * receiving a DISCONNECT packet.141 *142 * [MQTT - 3.1.2 - 8]143 *144 * @category MQTT145 */146export class MqttWill {147    constructor(148        /** Topic to publish Will message on. */149        readonly topic: string,150        /** QoS used when publishing the Will message. */151        readonly qos: QoS,152        /** Content of Will message. */153        readonly payload: Payload,154        /** Whether the Will message is to be retained when it is published. */155        readonly retain = false) {156    }157}158 159/**160 * Listener signature for event emitted from an {@link MqttClientConnection} when the connection reaches an initial161 * connected state162 *163 * @param session_present true if the reconnection went to an existing session, false if this is a clean session164 *165 * @category MQTT166 */167export type MqttConnectionConnected = (session_present: boolean) => void;168 169/**170 * Listener signature for event emitted from an {@link MqttClientConnection} when the connection has fully disconnected171 * by user request172 *173 * @category MQTT174 */175export type MqttConnectionDisconnected = () => void;176 177/**178 * Listener signature for event emitted from an {@link MqttClientConnection} when the connection successfully179 * reestablishes itself after an interruption180 *181 * @param return_code MQTT connect return code (should be 0 for a successful reconnection)182 * @param session_present true if the reconnection went to an existing session, false if this is a clean session183 *184 * @category MQTT185 */186export type MqttConnectionResumed = (return_code: number, session_present: boolean) => void;187 188/**189 * Const value for max reconnection back off time190 *191 * @category MQTT192 */193export const DEFAULT_RECONNECT_MAX_SEC = 128;194 195/**196 * Const value for min reconnection back off time197 *198 * @category MQTT199 */200 export const DEFAULT_RECONNECT_MIN_SEC = 1;201