Diff: AWS_openssl/aws_iot_src/protocol/mqtt/aws_iot_mqtt_interface.h

Revision:

15:6f2798e45099

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/AWS_openssl/aws_iot_src/protocol/mqtt/aws_iot_mqtt_interface.h	Thu Dec 01 18:05:38 2016 +0000
@@ -0,0 +1,328 @@
+/*
+ * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+/**
+ * @file aws_iot_mqtt_interface.h
+ * @brief Interface definition for MQTT client.
+ */
+
+#ifndef AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_
+#define AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_
+
+#include "stddef.h"
+#include "stdbool.h"
+#include "stdint.h"
+#include "aws_iot_error.h"
+
+/**
+ * @brief MQTT Version Type
+ *
+ * Defining an MQTT version type.
+ *
+ */
+typedef enum {
+	MQTT_3_1 = 3,	///< MQTT 3.1   (protocol message byte = 3)
+	MQTT_3_1_1 = 4	///< MQTT 3.1.1 (protocol message byte = 4)
+} MQTT_Ver_t;
+
+/**
+ * @brief Quality of Service Type
+ *
+ * Defining a QoS type.
+ * @note QoS 2 is \b NOT supported by the AWS IoT Service at the time of this SDK release.
+ *
+ */
+typedef enum {
+	QOS_0,	///< QoS 0 = at most once delivery
+	QOS_1,	///< QoS 1 = at least once delivery
+	QOS_2	///< QoS 2 is NOT supported
+} QoSLevel;
+
+/**
+ * @brief Last Will and Testament Definition
+ *
+ * Defining a type for LWT parameters.
+ * @note Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
+ *
+ */
+typedef struct {
+	const char *pTopicName;	///< LWT Topic
+	const char *pMessage;	///< Message to be delivered as LWT
+	bool isRetained;		///< NOT supported
+	QoSLevel qos;			///< QoS of LWT message
+} MQTTwillOptions;
+extern const MQTTwillOptions MQTTwillOptionsDefault;
+
+/**
+ * @brief Disconnect Callback Handler Type
+ *
+ * Defining a TYPE for definition of disconnect callback function pointers.
+ *
+ */
+typedef void (*iot_disconnect_handler)(void);
+
+/**
+ * @brief MQTT Connection Parameters
+ *
+ * Defining a type for MQTT connection parameters.  Passed into client when establishing a connection.
+ *
+ */
+typedef struct {
+	uint8_t enableAutoReconnect;		///< Set to true to enable auto reconnect
+	char *pHostURL;						///< Pointer to a string defining the endpoint for the MQTT service
+	uint16_t port;						///< MQTT service listening port
+	char *pRootCALocation;				///< Pointer to a string defining the Root CA file (full file, not path)
+	char *pDeviceCertLocation;			///< Pointer to a string defining the device identity certificate file (full file, not path)
+	char *pDevicePrivateKeyLocation;	///< Pointer to a string defining the device private key file (full file, not path)
+	char *pClientID;					///< Pointer to a string defining the MQTT client ID (this needs to be unique \b per \b device across your AWS account)
+	char *pUserName;					///< Not used in the AWS IoT Service
+	char *pPassword;					///< Not used in the AWS IoT Service
+	MQTT_Ver_t MQTTVersion;				///< Desired MQTT version used during connection
+	uint16_t KeepAliveInterval_sec;		///< MQTT keep alive interval in seconds.  Defines inactivity time allowed before determining the connection has been lost.
+	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.
+	bool isWillMsgPresent;				///< Is there a LWT associated with this connection?
+	MQTTwillOptions will;				///< MQTT LWT parameters.
+	uint32_t mqttCommandTimeout_ms;		///< Timeout for MQTT blocking calls.  In milliseconds.
+	uint32_t tlsHandshakeTimeout_ms;	///< TLS handshake timeout.  In milliseconds.
+	bool isSSLHostnameVerify;			///< Client should perform server certificate hostname validation.
+	iot_disconnect_handler disconnectHandler;	///< Callback to be invoked upon connection loss.
+} MQTTConnectParams;
+extern const MQTTConnectParams MQTTConnectParamsDefault;
+
+/**
+ * @brief MQTT Message Parameters
+ *
+ * Defines a type for properties of MQTT messages including topic, payload an QoS.
+ *
+ */
+typedef struct {
+	QoSLevel qos;			///< Message Quality of Service
+	bool isRetained;		///< Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release.
+	bool isDuplicate;		///< Is this message a duplicate QoS > 0 message?  Handled automatically by the MQTT client.
+	uint16_t id;			///< Message sequence identifier.  Handled automatically by the MQTT client.
+	void *pPayload;			///< Pointer to MQTT message payload (bytes).
+	uint32_t PayloadLen;	///< Length of MQTT payload.
+} MQTTMessageParams;
+extern const MQTTMessageParams MQTTMessageParamsDefault;
+/**
+ * @brief MQTT Callback Function Parameters
+ *
+ * Defines a type for parameters returned to the user upon receipt of a publish message on a subscribed topic.
+ *
+ */
+typedef struct {
+	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.
+	uint16_t TopicNameLen;				///< Length of the topic string.
+	MQTTMessageParams MessageParams;	///< Message parameters structure.
+} MQTTCallbackParams;
+extern const MQTTCallbackParams MQTTCallbackParamsDefault;
+
+/**
+ * @brief MQTT Callback Function
+ *
+ * Defines a type for the function pointer which stores the message callback function.
+ * A pointer to the desired callback function to be invoked upon receipt of a message on a subscribed toipc.
+ * Supplied upon subscribing to a topic.
+ *
+ */
+typedef int32_t (*iot_message_handler)(MQTTCallbackParams params);
+
+/**
+ * @brief MQTT Subscription Parameters
+ *
+ * Defines the parameters needed when subscribing to an MQTT topic.
+ *
+ */
+typedef struct {
+	char *pTopic;					///< Pointer to the string defining the desired subscription topic.
+	QoSLevel qos;					///< Quality of service of the subscription.
+	iot_message_handler mHandler;	///< Callback to be invoked upon receipt of a message on the subscribed topic.
+} MQTTSubscribeParams;
+extern const MQTTSubscribeParams MQTTSubscribeParamsDefault;
+
+/**
+ * @brief MQTT Publish Parameters
+ *
+ * Defines a type for parameters supplied when publishing an MQTT message.
+ *
+ */
+typedef struct {
+	char *pTopic;						///< Pointer to the string defining the desired publishing topic.
+	MQTTMessageParams MessageParams;	///< Parameters defining the message to be published.
+} MQTTPublishParams;
+extern const MQTTPublishParams MQTTPublishParamsDefault;
+
+/**
+ * @brief MQTT Connection Function
+ *
+ * Called to establish an MQTT connection with the AWS IoT Service
+ *
+ * @param pParams	Pointer to MQTT connection parameters
+ * @return An IoT Error Type defining successful/failed connection
+ */
+IoT_Error_t aws_iot_mqtt_connect(MQTTConnectParams *pParams);
+
+/**
+ * @brief Publish an MQTT message on a topic
+ *
+ * Called to publish an MQTT message on a topic.
+ * @note Call is blocking.  In the case of a QoS 0 message the function returns
+ * after the message was successfully passed to the TLS layer.  In the case of QoS 1
+ * the function returns after the receipt of the PUBACK control packet.
+ *
+ * @param pParams	Pointer to MQTT publish parameters
+ * @return An IoT Error Type defining successful/failed publish
+ */
+IoT_Error_t aws_iot_mqtt_publish(MQTTPublishParams *pParams);
+
+/**
+ * @brief Subscribe to an MQTT topic.
+ *
+ * Called to send a subscribe message to the broker requesting a subscription
+ * to an MQTT topic.
+ * @note Call is blocking.  The call returns after the receipt of the SUBACK control packet.
+ *
+ * @param pParams	Pointer to MQTT subscribe parameters
+ * @return An IoT Error Type defining successful/failed subscription
+ */
+IoT_Error_t aws_iot_mqtt_subscribe(MQTTSubscribeParams *pParams);
+
+/**
+ * @brief Unsubscribe to an MQTT topic.
+ *
+ * Called to send an usubscribe message to the broker requesting removal of a subscription
+ * to an MQTT topic.
+ * @note Call is blocking.  The call returns after the receipt of the UNSUBACK control packet.
+ *
+ * @param pTopic Pointer to the requested topic string. Ensure the string is null terminated
+ * @return An IoT Error Type defining successful/failed unsubscription
+ */
+IoT_Error_t aws_iot_mqtt_unsubscribe(char *pTopic);
+
+/**
+ * @brief MQTT Manual Re-Connection Function
+ *
+ * Called to establish an MQTT connection with the AWS IoT Service
+ * using parameters from the last time a connection was attempted
+ * Use after disconnect to start the reconnect process manually
+ * Makes only one reconnect attempt
+ *
+ * @return An IoT Error Type defining successful/failed connection
+ */
+IoT_Error_t aws_iot_mqtt_attempt_reconnect(void);
+
+/**
+ * @brief Disconnect an MQTT Connection
+ *
+ * Called to send a disconnect message to the broker.
+ *
+ * @return An IoT Error Type defining successful/failed send of the disconnect control packet.
+ */
+IoT_Error_t aws_iot_mqtt_disconnect(void);
+
+/**
+ * @brief Yield to the MQTT client
+ *
+ * Called to yield the current thread to the underlying MQTT client.  This time is used by
+ * the MQTT client to manage PING requests to monitor the health of the TCP connection as
+ * well as periodically check the socket receive buffer for subscribe messages.  Yield()
+ * must be called at a rate faster than the keepalive interval.  It must also be called
+ * at a rate faster than the incoming message rate as this is the only way the client receives
+ * processing time to manage incoming messages.
+ *
+ * @param timeout Maximum number of milliseconds to pass thread execution to the client.
+ * @return An IoT Error Type defining successful/failed client processing.
+ *         If this call results in an error it is likely the MQTT connection has dropped.
+ *         iot_is_mqtt_connected can be called to confirm.
+ */
+IoT_Error_t aws_iot_mqtt_yield(int timeout);
+
+/**
+ * @brief Is the MQTT client currently connected?
+ *
+ * Called to determine if the MQTT client is currently connected.  Used to support logic
+ * in the device application around reconnecting and managing offline state.
+ *
+ * @return true = connected, false = not currently connected
+ */
+bool aws_iot_is_mqtt_connected(void);
+
+/**
+ * @brief Is the MQTT client set to reconnect automatically?
+ *
+ * Called to determine if the MQTT client is set to reconnect automatically.
+ * Used to support logic in the device application around reconnecting
+ *
+ * @return true = enabled, false = disabled
+ */
+bool aws_iot_is_autoreconnect_enabled(void);
+
+/**
+ * @brief Enable or Disable AutoReconnect on Network Disconnect
+ *
+ * Called to enable or disabled the auto reconnect features provided with the SDK
+ *
+ * @param value set to true for enabling and false for disabling
+ *
+ * @return IoT_Error_t Type defining successful/failed API call
+ */
+IoT_Error_t aws_iot_mqtt_autoreconnect_set_status(bool value);
+
+typedef IoT_Error_t (*pConnectFunc_t)(MQTTConnectParams *pParams);
+typedef IoT_Error_t (*pPublishFunc_t)(MQTTPublishParams *pParams);
+typedef IoT_Error_t (*pSubscribeFunc_t)(MQTTSubscribeParams *pParams);
+typedef IoT_Error_t (*pUnsubscribeFunc_t)(char *pTopic);
+typedef IoT_Error_t (*pDisconnectFunc_t)(void);
+typedef IoT_Error_t (*pYieldFunc_t)(int timeout);
+typedef bool (*pIsConnectedFunc_t)(void);
+typedef bool (*pIsAutoReconnectEnabledFunc_t)(void);
+typedef IoT_Error_t (*pReconnectFunc_t)();
+typedef IoT_Error_t (*pSetAutoReconnectStatusFunc_t)(bool);
+/**
+ * @brief MQTT Client Type Definition
+ *
+ * Defines a structure of function pointers, each implementing a corresponding iot_mqtt_*
+ * function.  In this way any MQTT client which implements the iot_mqtt_* interface
+ * can be swapped in under the MQTT/Shadow layer.
+ *
+ */
+typedef struct{
+	pConnectFunc_t connect;				///< function implementing the iot_mqtt_connect function
+	pPublishFunc_t publish;				///< function implementing the iot_mqtt_publish function
+	pSubscribeFunc_t subscribe;			///< function implementing the iot_mqtt_subscribe function
+	pUnsubscribeFunc_t unsubscribe;		///< function implementing the iot_mqtt_unsubscribe function
+	pDisconnectFunc_t disconnect;		///< function implementing the iot_mqtt_disconnect function
+	pYieldFunc_t yield;					///< function implementing the iot_mqtt_yield function
+	pIsConnectedFunc_t isConnected;		///< function implementing the iot_is_mqtt_connected function
+	pReconnectFunc_t reconnect;			///< function implementing the iot_mqtt_reconnect function
+	pIsAutoReconnectEnabledFunc_t isAutoReconnectEnabled;	///< function implementing the iot_is_autoreconnect_enabled function
+	pSetAutoReconnectStatusFunc_t setAutoReconnectStatus;	///< function implementing the iot_mqtt_autoreconnect_set_status function
+}MQTTClient_t;
+
+
+/**
+ * @brief Set the MQTT client
+ *
+ * This function provides a way to pass in an MQTT client implementation to the
+ * AWS IoT MQTT wrapper layer.  This is done through function pointers to the
+ * interface functions.
+ *
+ */
+void aws_iot_mqtt_init(MQTTClient_t *pClient);
+
+
+#endif /* AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_ */
+
+