aws_iot_mqtt_interface.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 /**
00017  * @file aws_iot_mqtt_interface.h
00018  * @brief Interface definition for MQTT client.
00019  */
00020 
00021 #ifndef AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_
00022 #define AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_
00023 
00024 #include "stddef.h"
00025 #include "stdbool.h"
00026 #include "stdint.h"
00027 #include "aws_iot_error.h"
00028 
00029 /**
00030  * @brief MQTT Version Type
00031  *
00032  * Defining an MQTT version type.
00033  *
00034  */
00035 typedef enum {
00036     MQTT_3_1 = 3,   ///< MQTT 3.1   (protocol message byte = 3)
00037     MQTT_3_1_1 = 4  ///< MQTT 3.1.1 (protocol message byte = 4)
00038 } MQTT_Ver_t;
00039 
00040 /**
00041  * @brief Quality of Service Type
00042  *
00043  * Defining a QoS type.
00044  * @note QoS 2 is \b NOT supported by the AWS IoT Service at the time of this SDK release.
00045  *
00046  */
00047 typedef enum {
00048     QOS_0,  ///< QoS 0 = at most once delivery
00049     QOS_1,  ///< QoS 1 = at least once delivery
00050     QOS_2   ///< QoS 2 is NOT supported
00051 } QoSLevel;
00052 
00053 /**
00054  * @brief Last Will and Testament Definition
00055  *
00056  * Defining a type for LWT parameters.
00057  * @note Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
00058  *
00059  */
00060 typedef struct {
00061     const char *pTopicName; ///< LWT Topic
00062     const char *pMessage;   ///< Message to be delivered as LWT
00063     bool isRetained;        ///< NOT supported
00064     QoSLevel qos;           ///< QoS of LWT message
00065 } MQTTwillOptions;
00066 extern const MQTTwillOptions MQTTwillOptionsDefault;
00067 
00068 /**
00069  * @brief Disconnect Callback Handler Type
00070  *
00071  * Defining a TYPE for definition of disconnect callback function pointers.
00072  *
00073  */
00074 typedef void (*iot_disconnect_handler)(void);
00075 
00076 /**
00077  * @brief MQTT Connection Parameters
00078  *
00079  * Defining a type for MQTT connection parameters.  Passed into client when establishing a connection.
00080  *
00081  */
00082 typedef struct {
00083     uint8_t enableAutoReconnect;        ///< Set to true to enable auto reconnect
00084     char *pHostURL;                     ///< Pointer to a string defining the endpoint for the MQTT service
00085     uint16_t port;                      ///< MQTT service listening port
00086     char *pRootCALocation;              ///< Pointer to a string defining the Root CA file (full file, not path)
00087     char *pDeviceCertLocation;          ///< Pointer to a string defining the device identity certificate file (full file, not path)
00088     char *pDevicePrivateKeyLocation;    ///< Pointer to a string defining the device private key file (full file, not path)
00089     char *pClientID;                    ///< Pointer to a string defining the MQTT client ID (this needs to be unique \b per \b device across your AWS account)
00090     char *pUserName;                    ///< Not used in the AWS IoT Service
00091     char *pPassword;                    ///< Not used in the AWS IoT Service
00092     MQTT_Ver_t MQTTVersion;             ///< Desired MQTT version used during connection
00093     uint16_t KeepAliveInterval_sec;     ///< MQTT keep alive interval in seconds.  Defines inactivity time allowed before determining the connection has been lost.
00094     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.
00095     bool isWillMsgPresent;              ///< Is there a LWT associated with this connection?
00096     MQTTwillOptions will;               ///< MQTT LWT parameters.
00097     uint32_t mqttCommandTimeout_ms;     ///< Timeout for MQTT blocking calls.  In milliseconds.
00098     uint32_t tlsHandshakeTimeout_ms;    ///< TLS handshake timeout.  In milliseconds.
00099     bool isSSLHostnameVerify;           ///< Client should perform server certificate hostname validation.
00100     iot_disconnect_handler disconnectHandler;   ///< Callback to be invoked upon connection loss.
00101 } MQTTConnectParams;
00102 extern const MQTTConnectParams MQTTConnectParamsDefault;
00103 
00104 /**
00105  * @brief MQTT Message Parameters
00106  *
00107  * Defines a type for properties of MQTT messages including topic, payload an QoS.
00108  *
00109  */
00110 typedef struct {
00111     QoSLevel qos;           ///< Message Quality of Service
00112     bool isRetained;        ///< Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
00113     bool isDuplicate;       ///< Is this message a duplicate QoS > 0 message?  Handled automatically by the MQTT client.
00114     uint16_t id;            ///< Message sequence identifier.  Handled automatically by the MQTT client.
00115     void *pPayload;         ///< Pointer to MQTT message payload (bytes).
00116     uint32_t PayloadLen;    ///< Length of MQTT payload.
00117 } MQTTMessageParams;
00118 extern const MQTTMessageParams MQTTMessageParamsDefault;
00119 /**
00120  * @brief MQTT Callback Function Parameters
00121  *
00122  * Defines a type for parameters returned to the user upon receipt of a publish message on a subscribed topic.
00123  *
00124  */
00125 typedef struct {
00126     char *pTopicName;                   ///< Pointer to the topic string on which the message was delivered.  In the case of a wildcard subscription this is the actual topic, not the wildcard filter.
00127     uint16_t TopicNameLen;              ///< Length of the topic string.
00128     MQTTMessageParams MessageParams;    ///< Message parameters structure.
00129 } MQTTCallbackParams;
00130 extern const MQTTCallbackParams MQTTCallbackParamsDefault;
00131 
00132 /**
00133  * @brief MQTT Callback Function
00134  *
00135  * Defines a type for the function pointer which stores the message callback function.
00136  * A pointer to the desired callback function to be invoked upon receipt of a message on a subscribed toipc.
00137  * Supplied upon subscribing to a topic.
00138  *
00139  */
00140 typedef int32_t (*iot_message_handler)(MQTTCallbackParams params);
00141 
00142 /**
00143  * @brief MQTT Subscription Parameters
00144  *
00145  * Defines the parameters needed when subscribing to an MQTT topic.
00146  *
00147  */
00148 typedef struct {
00149     char *pTopic;                   ///< Pointer to the string defining the desired subscription topic.
00150     QoSLevel qos;                   ///< Quality of service of the subscription.
00151     iot_message_handler mHandler;   ///< Callback to be invoked upon receipt of a message on the subscribed topic.
00152 } MQTTSubscribeParams;
00153 extern const MQTTSubscribeParams MQTTSubscribeParamsDefault;
00154 
00155 /**
00156  * @brief MQTT Publish Parameters
00157  *
00158  * Defines a type for parameters supplied when publishing an MQTT message.
00159  *
00160  */
00161 typedef struct {
00162     char *pTopic;                       ///< Pointer to the string defining the desired publishing topic.
00163     MQTTMessageParams MessageParams;    ///< Parameters defining the message to be published.
00164 } MQTTPublishParams;
00165 extern const MQTTPublishParams MQTTPublishParamsDefault;
00166 
00167 /**
00168  * @brief MQTT Connection Function
00169  *
00170  * Called to establish an MQTT connection with the AWS IoT Service
00171  *
00172  * @param pParams   Pointer to MQTT connection parameters
00173  * @return An IoT Error Type defining successful/failed connection
00174  */
00175 IoT_Error_t aws_iot_mqtt_connect(MQTTConnectParams *pParams);
00176 
00177 /**
00178  * @brief Publish an MQTT message on a topic
00179  *
00180  * Called to publish an MQTT message on a topic.
00181  * @note Call is blocking.  In the case of a QoS 0 message the function returns
00182  * after the message was successfully passed to the TLS layer.  In the case of QoS 1
00183  * the function returns after the receipt of the PUBACK control packet.
00184  *
00185  * @param pParams   Pointer to MQTT publish parameters
00186  * @return An IoT Error Type defining successful/failed publish
00187  */
00188 IoT_Error_t aws_iot_mqtt_publish(MQTTPublishParams *pParams);
00189 
00190 /**
00191  * @brief Subscribe to an MQTT topic.
00192  *
00193  * Called to send a subscribe message to the broker requesting a subscription
00194  * to an MQTT topic.
00195  * @note Call is blocking.  The call returns after the receipt of the SUBACK control packet.
00196  *
00197  * @param pParams   Pointer to MQTT subscribe parameters
00198  * @return An IoT Error Type defining successful/failed subscription
00199  */
00200 IoT_Error_t aws_iot_mqtt_subscribe(MQTTSubscribeParams *pParams);
00201 
00202 /**
00203  * @brief Unsubscribe to an MQTT topic.
00204  *
00205  * Called to send an usubscribe message to the broker requesting removal of a subscription
00206  * to an MQTT topic.
00207  * @note Call is blocking.  The call returns after the receipt of the UNSUBACK control packet.
00208  *
00209  * @param pTopic Pointer to the requested topic string. Ensure the string is null terminated
00210  * @return An IoT Error Type defining successful/failed unsubscription
00211  */
00212 IoT_Error_t aws_iot_mqtt_unsubscribe(char *pTopic);
00213 
00214 /**
00215  * @brief MQTT Manual Re-Connection Function
00216  *
00217  * Called to establish an MQTT connection with the AWS IoT Service
00218  * using parameters from the last time a connection was attempted
00219  * Use after disconnect to start the reconnect process manually
00220  * Makes only one reconnect attempt
00221  *
00222  * @return An IoT Error Type defining successful/failed connection
00223  */
00224 IoT_Error_t aws_iot_mqtt_attempt_reconnect(void);
00225 
00226 /**
00227  * @brief Disconnect an MQTT Connection
00228  *
00229  * Called to send a disconnect message to the broker.
00230  *
00231  * @return An IoT Error Type defining successful/failed send of the disconnect control packet.
00232  */
00233 IoT_Error_t aws_iot_mqtt_disconnect(void);
00234 
00235 /**
00236  * @brief Yield to the MQTT client
00237  *
00238  * Called to yield the current thread to the underlying MQTT client.  This time is used by
00239  * the MQTT client to manage PING requests to monitor the health of the TCP connection as
00240  * well as periodically check the socket receive buffer for subscribe messages.  Yield()
00241  * must be called at a rate faster than the keepalive interval.  It must also be called
00242  * at a rate faster than the incoming message rate as this is the only way the client receives
00243  * processing time to manage incoming messages.
00244  *
00245  * @param timeout Maximum number of milliseconds to pass thread execution to the client.
00246  * @return An IoT Error Type defining successful/failed client processing.
00247  *         If this call results in an error it is likely the MQTT connection has dropped.
00248  *         iot_is_mqtt_connected can be called to confirm.
00249  */
00250 IoT_Error_t aws_iot_mqtt_yield(int timeout);
00251 
00252 /**
00253  * @brief Is the MQTT client currently connected?
00254  *
00255  * Called to determine if the MQTT client is currently connected.  Used to support logic
00256  * in the device application around reconnecting and managing offline state.
00257  *
00258  * @return true = connected, false = not currently connected
00259  */
00260 bool aws_iot_is_mqtt_connected(void);
00261 
00262 /**
00263  * @brief Is the MQTT client set to reconnect automatically?
00264  *
00265  * Called to determine if the MQTT client is set to reconnect automatically.
00266  * Used to support logic in the device application around reconnecting
00267  *
00268  * @return true = enabled, false = disabled
00269  */
00270 bool aws_iot_is_autoreconnect_enabled(void);
00271 
00272 /**
00273  * @brief Enable or Disable AutoReconnect on Network Disconnect
00274  *
00275  * Called to enable or disabled the auto reconnect features provided with the SDK
00276  *
00277  * @param value set to true for enabling and false for disabling
00278  *
00279  * @return IoT_Error_t Type defining successful/failed API call
00280  */
00281 IoT_Error_t aws_iot_mqtt_autoreconnect_set_status(bool value);
00282 
00283 typedef IoT_Error_t (*pConnectFunc_t)(MQTTConnectParams *pParams);
00284 typedef IoT_Error_t (*pPublishFunc_t)(MQTTPublishParams *pParams);
00285 typedef IoT_Error_t (*pSubscribeFunc_t)(MQTTSubscribeParams *pParams);
00286 typedef IoT_Error_t (*pUnsubscribeFunc_t)(char *pTopic);
00287 typedef IoT_Error_t (*pDisconnectFunc_t)(void);
00288 typedef IoT_Error_t (*pYieldFunc_t)(int timeout);
00289 typedef bool (*pIsConnectedFunc_t)(void);
00290 typedef bool (*pIsAutoReconnectEnabledFunc_t)(void);
00291 typedef IoT_Error_t (*pReconnectFunc_t)();
00292 typedef IoT_Error_t (*pSetAutoReconnectStatusFunc_t)(bool);
00293 /**
00294  * @brief MQTT Client Type Definition
00295  *
00296  * Defines a structure of function pointers, each implementing a corresponding iot_mqtt_*
00297  * function.  In this way any MQTT client which implements the iot_mqtt_* interface
00298  * can be swapped in under the MQTT/Shadow layer.
00299  *
00300  */
00301 typedef struct{
00302     pConnectFunc_t connect;             ///< function implementing the iot_mqtt_connect function
00303     pPublishFunc_t publish;             ///< function implementing the iot_mqtt_publish function
00304     pSubscribeFunc_t subscribe;         ///< function implementing the iot_mqtt_subscribe function
00305     pUnsubscribeFunc_t unsubscribe;     ///< function implementing the iot_mqtt_unsubscribe function
00306     pDisconnectFunc_t disconnect;       ///< function implementing the iot_mqtt_disconnect function
00307     pYieldFunc_t yield;                 ///< function implementing the iot_mqtt_yield function
00308     pIsConnectedFunc_t isConnected;     ///< function implementing the iot_is_mqtt_connected function
00309     pReconnectFunc_t reconnect;         ///< function implementing the iot_mqtt_reconnect function
00310     pIsAutoReconnectEnabledFunc_t isAutoReconnectEnabled;   ///< function implementing the iot_is_autoreconnect_enabled function
00311     pSetAutoReconnectStatusFunc_t setAutoReconnectStatus;   ///< function implementing the iot_mqtt_autoreconnect_set_status function
00312 }MQTTClient_t;
00313 
00314 
00315 /**
00316  * @brief Set the MQTT client
00317  *
00318  * This function provides a way to pass in an MQTT client implementation to the
00319  * AWS IoT MQTT wrapper layer.  This is done through function pointers to the
00320  * interface functions.
00321  *
00322  */
00323 void aws_iot_mqtt_init(MQTTClient_t *pClient);
00324 
00325 
00326 #endif /* AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_ */
00327 
00328