aws_iot_mqtt_client.h

00001 /*
00002  * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License").
00005  * You may not use this file except in compliance with the License.
00006  * A copy of the License is located at
00007  *
00008  *  http://aws.amazon.com/apache2.0
00009  *
00010  * or in the "license" file accompanying this file. This file is distributed
00011  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
00012  * express or implied. See the License for the specific language governing
00013  * permissions and limitations under the License.
00014  */
00015 
00016 // Based on Eclipse Paho.
00017 /*******************************************************************************
00018  * Copyright (c) 2014 IBM Corp.
00019  *
00020  * All rights reserved. This program and the accompanying materials
00021  * are made available under the terms of the Eclipse Public License v1.0
00022  * and Eclipse Distribution License v1.0 which accompany this distribution.
00023  *
00024  * The Eclipse Public License is available at
00025  *    http://www.eclipse.org/legal/epl-v10.html
00026  * and the Eclipse Distribution License is available at
00027  *   http://www.eclipse.org/org/documents/edl-v10.php.
00028  *
00029  * Contributors:
00030  *    Ian Craggs - initial API and implementation and/or initial documentation
00031  *    Xiang Rong - 442039 Add makefile to Embedded C client
00032  *******************************************************************************/
00033 
00034 /**
00035  * @file aws_iot_mqtt_client.h
00036  * @brief Client definition for MQTT
00037  */
00038 
00039 #ifndef AWS_IOT_SDK_SRC_IOT_MQTT_CLIENT_H
00040 #define AWS_IOT_SDK_SRC_IOT_MQTT_CLIENT_H
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /* Library Header files */
00047 #include "stdio.h"
00048 #include "stdbool.h"
00049 #include "stdint.h"
00050 #include "stddef.h"
00051 
00052 /* AWS Specific header files */
00053 #include "aws_iot_error.h"
00054 #include "aws_iot_config.h"
00055 
00056 /* Platform specific implementation header files */
00057 #include "network_interface.h"
00058 #include "timer_interface.h"
00059 
00060 #ifdef _ENABLE_THREAD_SUPPORT_
00061 #include "threads_interface.h"
00062 #endif
00063 
00064 #define MAX_PACKET_ID 65535
00065 
00066 typedef struct _Client AWS_IoT_Client;
00067 
00068 /**
00069  * @brief Quality of Service Type
00070  *
00071  * Defining a QoS type.
00072  * @note QoS 2 is \b NOT supported by the AWS IoT Service at the time of this SDK release.
00073  *
00074  */
00075 typedef enum QoS {
00076     QOS0 = 0,
00077     QOS1 = 1
00078 } QoS;
00079 
00080 /**
00081  * @brief Publish Message Parameters Type
00082  *
00083  * Defines a type for MQTT Publish messages. Used for both incoming and out going messages
00084  *
00085  */
00086 typedef struct {
00087     QoS qos;        ///< Message Quality of Service
00088     uint8_t isRetained; ///< Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
00089     uint8_t isDup;      ///< Is this message a duplicate QoS > 0 message?  Handled automatically by the MQTT client.
00090     uint16_t id;        ///< Message sequence identifier.  Handled automatically by the MQTT client.
00091     void *payload;      ///< Pointer to MQTT message payload (bytes).
00092     size_t payloadLen;  ///< Length of MQTT payload.
00093 } IoT_Publish_Message_Params;
00094 
00095 /**
00096  * @brief MQTT Version Type
00097  *
00098  * Defining an MQTT version type. Only 3.1.1 is supported at this time
00099  *
00100  */
00101 typedef enum {
00102     MQTT_3_1_1 = 4    ///< MQTT 3.1.1 (protocol message byte = 4)
00103 } MQTT_Ver_t;
00104 
00105 /**
00106  * @brief Last Will and Testament Definition
00107  *
00108  * Defining a type for the MQTT "Last Will and Testament" (LWT) parameters.
00109  * @note Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
00110  *
00111  */
00112 typedef struct {
00113     char struct_id[4];      ///< The eyecatcher for this structure.  must be MQTW
00114     char *pTopicName;       ///< The LWT topic to which the LWT message will be published
00115     uint16_t topicNameLen;      ///< The length of the LWT topic, 16 bit unsinged integer
00116     char *pMessage;         ///< Message to be delivered as LWT
00117     uint16_t msgLen;        ///< The length of the Message, 16 bit unsinged integer
00118     bool isRetained;        ///< NOT supported. The retained flag for the LWT message (see MQTTAsync_message.retained)
00119     QoS qos;            ///< QoS of LWT message
00120 } IoT_MQTT_Will_Options;
00121 extern const IoT_MQTT_Will_Options iotMqttWillOptionsDefault;
00122 
00123 #define IoT_MQTT_Will_Options_Initializer { {'M', 'Q', 'T', 'W'}, NULL, 0, NULL, 0, false, QOS0 }
00124 
00125 /**
00126  * @brief MQTT Connection Parameters
00127  *
00128  * Defining a type for MQTT connection parameters.  Passed into client when establishing a connection.
00129  *
00130  */
00131 typedef struct {
00132     char struct_id[4];          ///< The eyecatcher for this structure.  must be MQTC
00133     MQTT_Ver_t MQTTVersion;         ///< Desired MQTT version used during connection
00134     char *pClientID;                    ///< Pointer to a string defining the MQTT client ID (this needs to be unique \b per \b device across your AWS account)
00135     uint16_t clientIDLen;           ///< Client Id Length. 16 bit unsigned integer
00136     uint16_t keepAliveIntervalInSec;    ///< MQTT keep alive interval in seconds.  Defines inactivity time allowed before determining the connection has been lost.
00137     bool isCleanSession;            ///< MQTT clean session.  True = this session is to be treated as clean.  Previous server state is cleared and no stated is retained from this connection.
00138     bool isWillMsgPresent;          ///< Is there a LWT associated with this connection?
00139     IoT_MQTT_Will_Options will;     ///< MQTT LWT parameters.
00140     char *pUsername;            ///< Not used in the AWS IoT Service, will need to be cstring if used
00141     uint16_t usernameLen;           ///< Username Length. 16 bit unsigned integer
00142     char *pPassword;            ///< Not used in the AWS IoT Service, will need to be cstring if used
00143     uint16_t passwordLen;           ///< Password Length. 16 bit unsigned integer
00144 } IoT_Client_Connect_Params;
00145 extern const IoT_Client_Connect_Params iotClientConnectParamsDefault;
00146 
00147 #define IoT_Client_Connect_Params_initializer { {'M', 'Q', 'T', 'C'}, MQTT_3_1_1, NULL, 0, 60, true, false, \
00148         IoT_MQTT_Will_Options_Initializer, NULL, 0, NULL, 0 }
00149 
00150 /**
00151  * @brief Disconnect Callback Handler Type
00152  *
00153  * Defining a TYPE for definition of disconnect callback function pointers.
00154  *
00155  */
00156 typedef void (*iot_disconnect_handler)(AWS_IoT_Client *, void *);
00157 
00158 /**
00159  * @brief MQTT Initialization Parameters
00160  *
00161  * Defining a type for MQTT initialization parameters.
00162  * Passed into client when to initialize the client
00163  *
00164  */
00165 typedef struct {
00166     bool enableAutoReconnect;           ///< Set to true to enable auto reconnect
00167     char *pHostURL;                 ///< Pointer to a string defining the endpoint for the MQTT service
00168     uint16_t port;                  ///< MQTT service listening port
00169     char *pRootCALocation;              ///< Pointer to a string defining the Root CA file (full file, not path)
00170     char *pDeviceCertLocation;          ///< Pointer to a string defining the device identity certificate file (full file, not path)
00171     char *pDevicePrivateKeyLocation;            ///< Pointer to a string defining the device private key file (full file, not path)
00172     uint32_t mqttPacketTimeout_ms;          ///< Timeout for reading a complete MQTT packet. In milliseconds
00173     uint32_t mqttCommandTimeout_ms;         ///< Timeout for MQTT blocking calls. In milliseconds
00174     uint32_t tlsHandshakeTimeout_ms;        ///< TLS handshake timeout.  In milliseconds
00175     bool isSSLHostnameVerify;           ///< Client should perform server certificate hostname validation
00176     iot_disconnect_handler disconnectHandler;   ///< Callback to be invoked upon connection loss
00177     void *disconnectHandlerData;            ///< Data to pass as argument when disconnect handler is called
00178 #ifdef _ENABLE_THREAD_SUPPORT_
00179     bool isBlockOnThreadLockEnabled;        ///< Timeout for Thread blocking calls. Set to 0 to block until lock is obtained. In milliseconds
00180 #endif
00181 } IoT_Client_Init_Params;
00182 extern const IoT_Client_Init_Params iotClientInitParamsDefault;
00183 
00184 #ifdef _ENABLE_THREAD_SUPPORT_
00185 #define IoT_Client_Init_Params_initializer { true, NULL, 0, NULL, NULL, NULL, 2000, 20000, 5000, true, NULL, NULL, false }
00186 #else
00187 #define IoT_Client_Init_Params_initializer { true, NULL, 0, NULL, NULL, NULL, 2000, 20000, 5000, true, NULL, NULL }
00188 #endif
00189 
00190 /**
00191  * @brief MQTT Client State Type
00192  *
00193  * Defining a type for MQTT Client State
00194  *
00195  */
00196 typedef enum _ClientState {
00197     CLIENT_STATE_INVALID = 0,
00198     CLIENT_STATE_INITIALIZED = 1,
00199     CLIENT_STATE_CONNECTING = 2,
00200     CLIENT_STATE_CONNECTED_IDLE = 3,
00201     CLIENT_STATE_CONNECTED_YIELD_IN_PROGRESS = 4,
00202     CLIENT_STATE_CONNECTED_PUBLISH_IN_PROGRESS = 5,
00203     CLIENT_STATE_CONNECTED_SUBSCRIBE_IN_PROGRESS = 6,
00204     CLIENT_STATE_CONNECTED_UNSUBSCRIBE_IN_PROGRESS = 7,
00205     CLIENT_STATE_CONNECTED_RESUBSCRIBE_IN_PROGRESS = 8,
00206     CLIENT_STATE_CONNECTED_WAIT_FOR_CB_RETURN = 9,
00207     CLIENT_STATE_DISCONNECTING = 10,
00208     CLIENT_STATE_DISCONNECTED_ERROR = 11,
00209     CLIENT_STATE_DISCONNECTED_MANUALLY = 12,
00210     CLIENT_STATE_PENDING_RECONNECT = 13
00211 } ClientState;
00212 
00213 /**
00214  * @brief Application Callback Handler Type
00215  *
00216  * Defining a TYPE for definition of application callback function pointers.
00217  * Used to send incoming data to the application
00218  *
00219  */
00220 typedef void (*pApplicationHandler_t)(AWS_IoT_Client *pClient, char *pTopicName, uint16_t topicNameLen,
00221                                       IoT_Publish_Message_Params *pParams, void *pClientData);
00222 
00223 /**
00224  * @brief MQTT Message Handler
00225  *
00226  * Defining a type for MQTT Message Handlers.
00227  * Used to pass incoming data back to the application
00228  *
00229  */
00230 typedef struct _MessageHandlers {
00231     const char *topicName;
00232     uint16_t topicNameLen;
00233     QoS qos;
00234     pApplicationHandler_t pApplicationHandler;
00235     void *pApplicationHandlerData;
00236 } MessageHandlers;   /* Message handlers are indexed by subscription topic */
00237 
00238 /**
00239  * @brief MQTT Client Status
00240  *
00241  * Defining a type for MQTT Client Status
00242  * Contains information about the state of the MQTT Client
00243  *
00244  */
00245 typedef struct _ClientStatus {
00246     ClientState clientState;
00247     bool isPingOutstanding;
00248     bool isAutoReconnectEnabled;
00249 } ClientStatus;
00250 
00251 /**
00252  * @brief MQTT Client Data
00253  *
00254  * Defining a type for MQTT Client Data
00255  * Contains data used by the MQTT Client
00256  *
00257  */
00258 typedef struct _ClientData {
00259     uint16_t nextPacketId;
00260 
00261     uint32_t packetTimeoutMs;
00262     uint32_t commandTimeoutMs;
00263     uint16_t keepAliveInterval;
00264     uint32_t currentReconnectWaitInterval;
00265     uint32_t counterNetworkDisconnected;
00266 
00267     /* The below values are initialized with the
00268      * lengths of the TX/RX buffers and never modified
00269      * afterwards */
00270     size_t writeBufSize;
00271     size_t readBufSize;
00272 
00273     unsigned char writeBuf[AWS_IOT_MQTT_TX_BUF_LEN];
00274     unsigned char readBuf[AWS_IOT_MQTT_RX_BUF_LEN];
00275 
00276 #ifdef _ENABLE_THREAD_SUPPORT_
00277     bool isBlockOnThreadLockEnabled;
00278     IoT_Mutex_t state_change_mutex;
00279     IoT_Mutex_t tls_read_mutex;
00280     IoT_Mutex_t tls_write_mutex;
00281 #endif
00282 
00283     IoT_Client_Connect_Params options;
00284 
00285     MessageHandlers messageHandlers[AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS];
00286     iot_disconnect_handler disconnectHandler;
00287 
00288     void *disconnectHandlerData;
00289 } ClientData;
00290 
00291 /**
00292  * @brief MQTT Client
00293  *
00294  * Defining a type for MQTT Client
00295  *
00296  */
00297 struct _Client {
00298     TimerAWS pingTimer;
00299     TimerAWS reconnectDelayTimer;
00300 
00301     ClientStatus clientStatus;
00302     ClientData clientData;
00303     Network networkStack;
00304 };
00305 
00306 /**
00307  * @brief What is the next available packet Id
00308  *
00309  * Called to retrieve the next packet id to be used for outgoing packets.
00310  * Automatically increments the last sent packet id variable
00311  *
00312  * @param pClient Reference to the IoT Client
00313  *
00314  * @return next packet id as a 16 bit unsigned integer
00315  */
00316 uint16_t aws_iot_mqtt_get_next_packet_id(AWS_IoT_Client *pClient);
00317 
00318 /**
00319  * @brief Set the connection parameters for the IoT Client
00320  *
00321  * Called to set the connection parameters for the IoT Client.
00322  * Used to update the connection parameters provided before the last connect.
00323  * Won't take effect until the next time connect is called
00324  *
00325  * @param pClient Reference to the IoT Client
00326  * @param pNewConnectParams Reference to the new Connection Parameters structure
00327  *
00328  * @return IoT_Error_t Type defining successful/failed API call
00329  */
00330 IoT_Error_t aws_iot_mqtt_set_connect_params(AWS_IoT_Client *pClient, IoT_Client_Connect_Params *pNewConnectParams);
00331 
00332 /**
00333  * @brief Is the MQTT client currently connected?
00334  *
00335  * Called to determine if the MQTT client is currently connected.  Used to support logic
00336  * in the device application around reconnecting and managing offline state.
00337  *
00338  * @param pClient Reference to the IoT Client
00339  *
00340  * @return true = connected, false = not currently connected
00341  */
00342 bool aws_iot_mqtt_is_client_connected(AWS_IoT_Client *pClient);
00343 
00344 /**
00345  * @brief Get the current state of the client
00346  *
00347  * Called to get the current state of the client
00348  *
00349  * @param pClient Reference to the IoT Client
00350  *
00351  * @return ClientState value equal to the current state of the client
00352  */
00353 ClientState aws_iot_mqtt_get_client_state(AWS_IoT_Client *pClient);
00354 
00355 /**
00356  * @brief Is the MQTT client set to reconnect automatically?
00357  *
00358  * Called to determine if the MQTT client is set to reconnect automatically.
00359  * Used to support logic in the device application around reconnecting
00360  *
00361  * @param pClient Reference to the IoT Client
00362  *
00363  * @return true = enabled, false = disabled
00364  */
00365 bool aws_iot_is_autoreconnect_enabled(AWS_IoT_Client *pClient);
00366 
00367 /**
00368  * @brief Set the IoT Client disconnect handler
00369  *
00370  * Called to set the IoT Client disconnect handler
00371  * The disconnect handler is called whenever the client disconnects with error
00372  *
00373  * @param pClient Reference to the IoT Client
00374  * @param pConnectHandler Reference to the new Disconnect Handler
00375  * @param pDisconnectHandlerData Reference to the data to be passed as argument when disconnect handler is called
00376  *
00377  * @return IoT_Error_t Type defining successful/failed API call
00378  */
00379 IoT_Error_t aws_iot_mqtt_set_disconnect_handler(AWS_IoT_Client *pClient, iot_disconnect_handler pDisconnectHandler,
00380                                                 void *pDisconnectHandlerData);
00381 
00382 /**
00383  * @brief Enable or Disable AutoReconnect on Network Disconnect
00384  *
00385  * Called to enable or disabled the auto reconnect features provided with the SDK
00386  *
00387  * @param pClient Reference to the IoT Client
00388  * @param newStatus set to true for enabling and false for disabling
00389  *
00390  * @return IoT_Error_t Type defining successful/failed API call
00391  */
00392 IoT_Error_t aws_iot_mqtt_autoreconnect_set_status(AWS_IoT_Client *pClient, bool newStatus);
00393 
00394 /**
00395  * @brief Get count of Network Disconnects
00396  *
00397  * Called to get the number of times a network disconnect occurred due to errors
00398  *
00399  * @param pClient Reference to the IoT Client
00400  *
00401  * @return uint32_t the disconnect count
00402  */
00403 uint32_t aws_iot_mqtt_get_network_disconnected_count(AWS_IoT_Client *pClient);
00404 
00405 /**
00406  * @brief Reset Network Disconnect conter
00407  *
00408  * Called to reset the Network Disconnect counter to zero
00409  *
00410  * @param pClient Reference to the IoT Client
00411  */
00412 void aws_iot_mqtt_reset_network_disconnected_count(AWS_IoT_Client *pClient);
00413 
00414 #ifdef __cplusplus
00415 }
00416 #endif
00417 
00418 #endif