owner-nrf52sdk/nRF5_SDK_15.3.0/components/iot/mqtt/mqtt.h

/**
 * Copyright (c) 2015 - 2019, Nordic Semiconductor ASA
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, must reproduce the above copyright notice, this list of
 *    conditions and the following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
/** @file mqtt.h
 *
 * @defgroup iot_sdk_mqtt_api MQTT Client on nRF5x
 * @ingroup iot_sdk_mqtt
 * @{
 * @brief MQTT Client Implementation on the Nordic nRF platforms.
 *
 * @details
 * MQTT Client's Application interface is defined in this header.
 *
 * @note The implementation assumes LwIP Stack is available with TCP module enabled.
 *
 * @note By default the implementation uses MQTT version 3.1.0.
 *       However few cloud services like the Xively use the version 3.1.1.
 *       For this please set p_client.protocol_version = MQTT_VERSION_3_1_1.
 */

#ifndef MQTT_H_
#define MQTT_H_

#include <stdint.h>
#include "iot_defines.h"
#include "iot_timer.h"
#include "nrf_tls.h"

#ifdef __cplusplus
extern "C" {
#endif

/**@brief MQTT Asynchronous Events notified to the application from the module
 *        through the callback registered by the application. */
typedef enum
{
    MQTT_EVT_CONNACK,                                                          /**< Acknowledgment of connection request. Event result accompanying the event indicates whether the connection failed or succeeded. */
    MQTT_EVT_DISCONNECT,                                                       /**< Disconnection Event. MQTT Client Reference is no longer valid once this event is received for the client. */
    MQTT_EVT_PUBLISH,                                                          /**< Publish event received when message is published on a topic client is subscribed to. */
    MQTT_EVT_PUBACK,                                                           /**< Acknowledgment for published message with QoS 1. */
    MQTT_EVT_PUBREC,                                                           /**< Reception confirmation for published message with QoS 2. */
    MQTT_EVT_PUBREL,                                                           /**< Release of published published messages with QoS 2. */
    MQTT_EVT_PUBCOMP,                                                          /**< Confirmation to a publish release message. Applicable only to QoS 2 messages. */
    MQTT_EVT_SUBACK,                                                           /**< Acknowledgment to a subscription request. */
    MQTT_EVT_UNSUBACK                                                          /**< Acknowledgment to a unsubscription request. */
} mqtt_evt_id_t;

/**@brief MQTT version protocol level. */
typedef enum
{
    MQTT_VERSION_3_1_0 = 3,                                                   /**< Protocol level for 3.1.0. */
    MQTT_VERSION_3_1_1 = 4                                                    /**< Protocol level for 3.1.1. */
} mqtt_version_t;

/**@brief MQTT transport type. */
typedef enum
{
    MQTT_TRANSPORT_NON_SECURE = 0x00,                                          /**< Use non secure TCP transport for MQTT connection. */
    MQTT_TRANSPORT_SECURE     = 0x01,                                          /**< Use secure TCP transport (TLS) for MQTT connection. */
    MQTT_TRANSPORT_MAX        = 0x02                                           /**< Shall not be used as a transport type. Indicator of maximum transport types possible. */
} mqtt_transport_type_t;

/**@brief MQTT Quality of Service types. */
typedef enum
{
    MQTT_QoS_0_AT_MOST_ONCE  = 0x00,                                           /**< Lowest Quality of Service, no acknowledgment needed for published message. */
    MQTT_QoS_1_ATLEAST_ONCE  = 0x01,                                           /**< Medium Quality of Service, if acknowledgment expected for published message, duplicate messages permitted. */
    MQTT_QoS_2_EACTLY_ONCE   = 0x02                                            /**< Highest Quality of Service, acknowledgment expected and message shall be published only once. Message not published to interested parties unless client issues a PUBREL. */
} mqtt_qos_t;

/**@brief MQTT Asynchronous Events notified to the application from the module
 *        through the callback registered by the application. */
typedef enum
{
    MQTT_CONNECTION_ACCEPTED            = 0x00,                                /**< Connection accepted. */
    MQTT_UNACCEPTABLE_PROTOCOL_VERSION  = 0x01,                                /**< The Server does not support the level of the MQTT protocol requested by the Client. */
    MQTT_IDENTIFIER_REJECTED            = 0x02,                                /**< The Client identifier is correct UTF-8 but not allowed by the Server. */
    MQTT_SERVER_UNAVAILABLE             = 0x03,                                /**< The Network Connection has been made but the MQTT service is unavailable. */
    MQTT_BAD_USER_NAME_OR_PASSWORD      = 0x04,                                /**< The data in the user name or password is malformed. */
    MQTT_NOT_AUTHORIZED                 = 0x05                                 /**< The Client is not authorized to connect. */
} mqtt_conn_return_code_t;

/**@brief MQTT client forward declaration @ref mqtt_client_t for details. */
typedef struct mqtt_client_t mqtt_client_t;

/**@brief Abstracts UTF-8 encoded strings. */
typedef struct
{
    uint8_t    * p_utf_str;                                                    /**< Pointer to UTF-8 string. */
    uint32_t     utf_strlen;                                                   /**< Length of UTF string. */
} mqtt_utf8_t;

/**@brief Abstracts binary strings. */
typedef struct
{
    uint8_t    * p_bin_str;                                                    /**< Pointer to binary stream. */
    uint32_t     bin_strlen;                                                   /**< Length of binary stream. */
} mqtt_binstr_t;

/**@brief Abstracts MQTT UTF-8 encoded topic that can be subscribed to or published. */
typedef struct
{
    mqtt_utf8_t     topic;                                                     /**< Topic on to be published or subscribed to. */
    uint8_t         qos;                                                       /**< Quality of service requested for the subscription. @ref mqtt_qos_t for details. */
} mqtt_topic_t;

/**@brief Abstracts MQTT UTF-8 encoded unique client identifier. */
typedef mqtt_utf8_t mqtt_client_id_t;

/**@brief Abstracts MQTT UTF-8 encoded password to be used for the client connection. */
typedef mqtt_utf8_t mqtt_password_t;

/**@brief Abstracts MQTT UTF-8 encoded user name to be used for the client connection. */
typedef mqtt_utf8_t mqtt_username_t;

/**@brief Abstracts will message used in @ref mqtt_connect request.
 *
 * @note utf8 is used here instead of binary string as a zero length encoding is expected in
 *       will message is empty.
 */
typedef mqtt_utf8_t mqtt_will_message_t;

/**@brief Abstracts message in binary encoded string received or published on a topic. */
typedef mqtt_binstr_t mqtt_message_t;

/**@brief Parameters for a publish message. */
typedef struct
{
    mqtt_topic_t    topic;                                                     /**< Topic on which data was published. */
    mqtt_message_t  payload;                                                   /**< Payload on the topic published. */
} mqtt_publish_message_t;

/**@brief Parameters for a connection acknowledgment (connack). */
typedef struct
{
    uint8_t                 session_present_flag;                              /**< The Session Present flag enables a Client to establish whether the Client and Server have a consistent view about whether there is already stored Session state. */
    mqtt_conn_return_code_t return_code;                                       /**< The appropriate non-zero Connect return code indicates if the Server is unable to process a connection request for some reason. */
} mqtt_connack_param_t;

/**@brief Parameters for MQTT publish acknowledgment(puback). */
typedef struct
{
    uint16_t message_id;
} mqtt_puback_param_t;

/**@brief Parameters for MQTT publish receive(pubrec). */
typedef struct
{
    uint16_t message_id;
} mqtt_pubrec_param_t;

/**@brief Parameters for MQTT publish release(pubrec). */
typedef struct
{
    uint16_t message_id;
} mqtt_pubrel_param_t;

/**@brief Parameters for MQTT publish complete(pubcomp). */
typedef struct
{
    uint16_t message_id;
} mqtt_pubcomp_param_t;

/**@brief Parameters for MQTT subscription acknowledgment (suback). */
typedef struct
{
    uint16_t message_id;
} mqtt_suback_param_t;

/**@brief Parameters for MQTT unsubscription acknowledgment (unsuback). */
typedef struct
{
    uint16_t message_id;
} mqtt_unsuback_param_t;

/**@brief Parameters for a publish message. */
typedef struct
{
    mqtt_publish_message_t   message;                                          /**< Messages including topic, QoS and its payload (if any) to be published. */
    uint16_t                 message_id;                                       /**< Message id used for the publish message. Redundant for QoS 0. */
    uint8_t                  dup_flag:1;                                       /**< Duplicate flag. If 1, it indicates the message is being retransmitted. Has no meaning with QoS 0. */
    uint8_t                  retain_flag:1;                                    /**< retain flag. If 1, the message shall be stored persistently by the broker. */
} mqtt_publish_param_t;

/**@brief List of topics in a subscription request. */
typedef struct
{
    mqtt_topic_t    *        p_list;                                           /**< Array containing topics along with QoS for each. */
    uint32_t                 list_count;                                       /**< Number of topics in the subscription list */
    uint16_t                 message_id;                                       /**< Message id used to identify subscription request. */
} mqtt_subscription_list_t;

/**
 * @brief Defines event parameters notified along with asynchronous events to the application.
 *        Currently, only MQTT_EVT_PUBLISH is accompanied with parameters.
 */
typedef union
{
    mqtt_connack_param_t     connack;                                          /**< Parameters accompanying MQTT_EVT_CONNACK event. */
    mqtt_publish_param_t     publish;                                          /**< Parameters accompanying MQTT_EVT_PUBLISH event. */
    mqtt_puback_param_t      puback;                                           /**< Parameters accompanying MQTT_EVT_PUBACK event. */
    mqtt_pubrec_param_t      pubrec;                                           /**< Parameters accompanying MQTT_EVT_PUBREC event. */
    mqtt_pubrel_param_t      pubrel;                                           /**< Parameters accompanying MQTT_EVT_PUBREL event. */
    mqtt_pubcomp_param_t     pubcomp;                                          /**< Parameters accompanying MQTT_EVT_PUBCOMP event. */
    mqtt_suback_param_t      suback;                                           /**< Parameters accompanying MQTT_EVT_SUBACK event. */
    mqtt_suback_param_t      unsuback;                                         /**< Parameters accompanying MQTT_EVT_UNSUBACK event. */
} mqtt_evt_param_t;

/**@brief Defined MQTT asynchronous event notified to the application. */
typedef struct
{
    mqtt_evt_id_t            id;                                               /**< Identifies the event. */
    mqtt_evt_param_t         param;                                            /**< Contains parameters (if any) accompanying the event. */
    uint32_t                 result;                                           /**< Event result. For example, MQTT_EVT_CONNACK has a result code indicating success or failure code of connection procedure. */
} mqtt_evt_t;

/**@brief Asynchronous event notification callback registered by the application with
 *        the module to receive module events.
 *
 * @param[in] p_client Identifies the client for which the event is notified.
 * @param[in] p_evet   Event description along with result and associated parameters (if any).
 */
typedef void (*mqtt_evt_cb_t)(mqtt_client_t * const p_client, const mqtt_evt_t * p_evt);

/**@brief MQTT Client definition to maintain information relevant to the client. */
struct mqtt_client_t
{
    mqtt_client_id_t         client_id;                                        /**< Unique client identification to be used for the connection. Shall be zero length or NULL valued. */
    mqtt_username_t        * p_user_name;                                      /**< User name (if any) to be used for the connection. NULL indicates no user name. */
    mqtt_password_t        * p_password;                                       /**< Password (if any) to be used for the connection. Note that if password is provided, user name shall also be provided. NULL indicates no password. */
    mqtt_topic_t           * p_will_topic;                                     /**< Will topic and QoS. Can be NULL. */
    mqtt_will_message_t    * p_will_message;                                   /**< Will message. Can be NULL. Non NULL value valid only if will topic is not NULL. */
    nrf_tls_key_settings_t * p_security_settings;                              /**< Provide security settings like PSK, own certificate etc here. The memory provided for the settings shall be resident. */
    mqtt_evt_cb_t            evt_cb;                                           /**< Application callback registered with the module to get MQTT events. */
    ipv6_addr_t              broker_addr;                                      /**< IPv6 Address of MQTT broker to which client connection is requested. */
    uint16_t                 broker_port;                                      /**< Broker's Port number. */
    uint8_t                  poll_abort_counter;                               /**< Poll abort counter maintained for the TCP connection. */
    uint8_t                  protocol_version;                                 /**< MQTT protocol version. */
    uint8_t                  transport_type;                                   /**< Transport type selection for client instance. @ref mqtt_transport_type_t for possible values. MQTT_TRANSPORT_MAX is not a valid type.*/
    uint8_t                  will_retain:1;                                    /**< Will retain flag, 1 if will message shall be retained persistently. */
    uint8_t                  clean_session:1;                                  /**< Clean session flag indicating a fresh (1) or a retained session (0). Default is 1. */
    iot_timer_time_in_ms_t   last_activity;                                    /**< Internal. Ticks maintaining wallcock in last activity that occurred. Needed for periodic PING. */
    uint32_t                 state;                                            /**< Internal. Shall not be touched by the application. Client's state in the connection. */
    int                      socket_fd;                                        /**< Internal. Shall not be touched by the application. TCP socket file descriptor. */
    uint32_t                 tcp_id;                                           /**< Internal. Shall not be touched by the application. TCP Connection Reference provided by the IP stack. */
    uint8_t                * p_packet;                                         /**< Internal. Shall not be touched by the application. Used for creating MQTT packet in TX path. */
    uint8_t                * p_pending_packet;                                 /**< Internal. Shall not be touched by the application. */
    nrf_tls_instance_t       tls_instance;                                     /**< Internal. Shall not be touched by the application. TLS instance identifier. Valid only if transport is a secure one. */
    uint32_t                 pending_packetlen;                                /**< Internal. Shall not be touched by the application. */
};


/**
 * @brief Initializes the module.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Shall be called before initiating any procedures on the module.
 * @note If module initialization fails, no module APIs shall be called.
 */
uint32_t mqtt_init(void);


/**
 * @brief Initializes the client instance.
 *
 * @param[in] p_client Client instance for which the procedure is requested.
 *                     Shall not be NULL.
 *
 * @note Shall be called before connecting the client in order to avoid unexpected behavior
 *       caused by uninitialized parameters.
 */
void mqtt_client_init(mqtt_client_t * const p_client);


/**
 * @brief API to request new MQTT client connection.
 *
 * @param[out] p_client  Client instance for which the procedure is requested.
 *                       Shall not be NULL.
 *
 * @note This memory is assumed to be resident until mqtt_disconnect is called.
 * @note Any subsequent changes to parameters like broker address, user name, device id, etc. have
 *       no effect once MQTT connection is established.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 * @note If more than one simultaneous client connections are needed, please define
 *        MQTT_MAX_CLIENTS to override default of 1.
 * @note Please define MQTT_KEEPALIVE time to override default of 1 minute.
 * @note Please define MQTT_MAX_PACKET_LENGTH time to override default of 128 bytes.
 *       Ensure the system has enough memory for the new length per client.
 */
uint32_t mqtt_connect(mqtt_client_t * const p_client);


/**
 * @brief API to publish messages on topics.
 *
 * @param[in]  p_client   Client instance for which the procedure is requested.
 *                        Shall not be NULL.
 * @param[in]  p_param    Parameters to be used for the publish message.
 *                        Shall not be NULL.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 */
uint32_t mqtt_publish(mqtt_client_t              * const p_client,
                      mqtt_publish_param_t const * const p_param);


/**
 * @brief API used by subscribing client to send acknowledgment to the broker.
 *        Applicable only to QoS 1 publish messages.
 *
 * @param[in]  p_client   Client instance for which the procedure is requested.
 *                        Shall not be NULL.
 * @param[in]  p_param    Identifies message being acknowledged.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 */
uint32_t mqtt_publish_ack(mqtt_client_t             * const p_client,
                          mqtt_puback_param_t const * const p_param);


/**
 * @brief API to send assured acknowledgment from a subscribing client to the broker.
 *        Should be called on reception of @ref MQTT_EVT_PUBLISH with QoS set to
 *        @ref MQTT_QoS_2_EACTLY_ONCE.
 *
 * @param[in]  p_client   Identifies client instance for which the procedure is requested.
 *                        Shall not be NULL.
 * @param[in]  p_param    Identifies message being acknowledged.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 */
uint32_t mqtt_publish_receive(mqtt_client_t             * const p_client,
                              mqtt_pubrec_param_t const * const p_param);


/**
 * @brief API to used by publishing client to request releasing published data.
 *        Shall be used only after @ref MQTT_EVT_PUBREC is received and is valid
 *        only for QoS level @ref MQTT_QoS_2_EACTLY_ONCE.
 *
 * @param[in]  p_client   Client instance for which the procedure is requested.
 *                        Shall not be NULL.
 * @param[in]  p_param    Identifies message being released.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 */
uint32_t mqtt_publish_release(mqtt_client_t             * const p_client,
                              mqtt_pubrel_param_t const * const p_param);


/**
 * @brief API  used by subscribing clients to acknowledge reception of a released message.
 *        Should be used on reception @ref MQTT_EVT_PUBREL event.
 *
 * @param[in]  p_client   Identifies client instance for which the procedure is requested.
 *                        Shall not be NULL.
 * @param[in]  p_param    Identifies message being completed.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note Default protocol revision used for connection request is 3.1.0. Please set
 *       p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.
 */
uint32_t mqtt_publish_complete(mqtt_client_t              * const p_client,
                               mqtt_pubcomp_param_t const * const p_param);


/**
 * @brief API to request subscribing to a topic on the connection.
 *
 * @param[in]  p_client  Identifies client instance for which the procedure is requested.
 *                       Shall not be NULL.
 * @param[in]  p_param   Subscription parameters. Shall not be NULL.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 */
uint32_t mqtt_subscribe(mqtt_client_t                  * const p_client,
                        mqtt_subscription_list_t const * const p_param);


/**
 * @brief API to request un-subscribe from a topic on the connection.
 *
 * @param[in]  p_client  Identifies client instance for which the procedure is requested.
 *                       Shall not be NULL.
 * @param[in]  p_param   Parameters describing topics being unsubscribed from.
 *                       Shall not be NULL.
 *
 * @note QoS included in topic description is unused in this API.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 */
uint32_t mqtt_unsubscribe(mqtt_client_t                  * const p_client,
                          mqtt_subscription_list_t const * const p_param);


/**
 * @brief API to abort MQTT connection.
 *
 * @param[in]  p_client  Identifies client instance for which procedure is requested.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 */
uint32_t mqtt_abort(mqtt_client_t * const p_client);


/**
 * @brief API to disconnect MQTT connection.
 *
 * @param[in]  p_client  Identifies client instance for which procedure is requested.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 */
uint32_t mqtt_disconnect(mqtt_client_t * const p_client);


/**
 * @brief This API should be called periodically for the module to be able to keep the connection
 *        alive by sending Ping Requests if need be.
 *
 * @note  Application shall ensure that the periodicity of calling this function makes it possible to
 *        respect the Keep Alive time agreed with the broker on connection.
 *        @ref mqtt_connect for details on Keep Alive time.
 *
 * @retval NRF_SUCCESS or an result code indicating reason for failure.
 */
uint32_t mqtt_live(void);


/**
 * @brief Wait for an incoming MQTT packet.
 *        The registered callback will be called with the packet payload.
 *
 * @param[in]  p_client  Client instance for which the procedure is requested.
 *                       Shall not be NULL.
 * @param[in]  timeout   Maximum interval (in milliseconds) to wait for a packet.
 *                       If timeout is 0, the interval is indefinitely.
 *
 * @retval NRF_SUCCESS or an error code indicating reason for failure.
 *
 * @note This API is only supported when using the socket transport layer.
 */
uint32_t mqtt_input(mqtt_client_t * const p_client, uint32_t timeout);


#ifdef __cplusplus
}
#endif

#endif // MQTT_H_

/**@}  */