aws_iot_mqtt_client_interface.h

00001 /*
00002 * Copyright 2015-2016 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_interface.h
00036  * @brief Interface definition for MQTT client.
00037  */
00038 
00039 #ifndef AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H
00040 #define AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_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 #include "aws_iot_mqtt_client.h"
00056 
00057 /* Platform specific implementation header files */
00058 #include "network_interface.h"
00059 #include "timer_interface.h"
00060 
00061 
00062 /**
00063 * @brief Clean mqtt client from all dynamic memory allocate
00064 *
00065 * This function will free up memory that was dynamically allocated for the client.
00066 *
00067 * @param pClient MQTT Client that was previously created by calling aws_iot_mqtt_init
00068 * @return An IoT Error Type defining successful/failed freeing
00069 */
00070  IoT_Error_t aws_iot_mqtt_free( AWS_IoT_Client *pClient );
00071 
00072 /**
00073  * @brief MQTT Client Initialization Function
00074  *
00075  * Called to initialize the MQTT Client
00076  *
00077  * @param pClient Reference to the IoT Client
00078  * @param pInitParams Pointer to MQTT connection parameters
00079  *
00080  * @return IoT_Error_t Type defining successful/failed API call
00081  */
00082 IoT_Error_t aws_iot_mqtt_init(AWS_IoT_Client *pClient, IoT_Client_Init_Params *pInitParams);
00083 
00084 /**
00085  * @brief MQTT Connection Function
00086  *
00087  * Called to establish an MQTT connection with the AWS IoT Service
00088  *
00089  * @param pClient Reference to the IoT Client
00090  * @param pConnectParams Pointer to MQTT connection parameters
00091  *
00092  * @return An IoT Error Type defining successful/failed connection
00093  */
00094 IoT_Error_t aws_iot_mqtt_connect(AWS_IoT_Client *pClient, IoT_Client_Connect_Params *pConnectParams);
00095 
00096 /**
00097  * @brief Publish an MQTT message on a topic
00098  *
00099  * Called to publish an MQTT message on a topic.
00100  * @note Call is blocking.  In the case of a QoS 0 message the function returns
00101  * after the message was successfully passed to the TLS layer.  In the case of QoS 1
00102  * the function returns after the receipt of the PUBACK control packet.
00103  *
00104  * @param pClient Reference to the IoT Client
00105  * @param pTopicName Topic Name to publish to
00106  * @param topicNameLen Length of the topic name
00107  * @param pParams Pointer to Publish Message parameters
00108  *
00109  * @return An IoT Error Type defining successful/failed publish
00110  */
00111 IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen,
00112                                  IoT_Publish_Message_Params *pParams);
00113 
00114 /**
00115  * @brief Subscribe to an MQTT topic.
00116  *
00117  * Called to send a subscribe message to the broker requesting a subscription
00118  * to an MQTT topic.
00119  * @note Call is blocking.  The call returns after the receipt of the SUBACK control packet.
00120  * @warning pTopicName and pApplicationHandlerData need to be static in memory.
00121  *
00122  * @param pClient Reference to the IoT Client
00123  * @param pTopicName Topic Name to publish to. pTopicName needs to be static in memory since 
00124  *     no malloc are performed by the SDK
00125  * @param topicNameLen Length of the topic name
00126  * @param pApplicationHandler_t Reference to the handler function for this subscription
00127  * @param pApplicationHandlerData Point to data passed to the callback. 
00128  *    pApplicationHandlerData also needs to be static in memory  since no malloc are performed by the SDK
00129  *
00130  * @return An IoT Error Type defining successful/failed subscription
00131  */
00132 IoT_Error_t aws_iot_mqtt_subscribe(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen,
00133                                    QoS qos, pApplicationHandler_t pApplicationHandler, void *pApplicationHandlerData);
00134 
00135 /**
00136  * @brief Subscribe to an MQTT topic.
00137  *
00138  * Called to resubscribe to the topics that the client has active subscriptions on.
00139  * Internally called when autoreconnect is enabled
00140  *
00141  * @note Call is blocking.  The call returns after the receipt of the SUBACK control packet.
00142  *
00143  * @param pClient Reference to the IoT Client
00144  *
00145  * @return An IoT Error Type defining successful/failed subscription
00146  */
00147 IoT_Error_t aws_iot_mqtt_resubscribe(AWS_IoT_Client *pClient);
00148 
00149 /**
00150  * @brief Unsubscribe to an MQTT topic.
00151  *
00152  * Called to send an unsubscribe message to the broker requesting removal of a subscription
00153  * to an MQTT topic.
00154  * @note Call is blocking.  The call returns after the receipt of the UNSUBACK control packet.
00155  *
00156  * @param pClient Reference to the IoT Client
00157  * @param pTopicName Topic Name to publish to
00158  * @param topicNameLen Length of the topic name
00159  *
00160  * @return An IoT Error Type defining successful/failed unsubscribe call
00161  */
00162 IoT_Error_t aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopicFilter, uint16_t topicFilterLen);
00163 
00164 /**
00165  * @brief Disconnect an MQTT Connection
00166  *
00167  * Called to send a disconnect message to the broker.
00168  *
00169  * @param pClient Reference to the IoT Client
00170  *
00171  * @return An IoT Error Type defining successful/failed send of the disconnect control packet.
00172  */
00173 IoT_Error_t aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient);
00174 
00175 /**
00176  * @brief Yield to the MQTT client
00177  *
00178  * Called to yield the current thread to the underlying MQTT client.  This time is used by
00179  * the MQTT client to manage PING requests to monitor the health of the TCP connection as
00180  * well as periodically check the socket receive buffer for subscribe messages.  Yield()
00181  * must be called at a rate faster than the keepalive interval.  It must also be called
00182  * at a rate faster than the incoming message rate as this is the only way the client receives
00183  * processing time to manage incoming messages.
00184  *
00185  * @param pClient Reference to the IoT Client
00186  * @param timeout_ms Maximum number of milliseconds to pass thread execution to the client.
00187  *
00188  * @return An IoT Error Type defining successful/failed client processing.
00189  *         If this call results in an error it is likely the MQTT connection has dropped.
00190  *         iot_is_mqtt_connected can be called to confirm.
00191  */
00192 IoT_Error_t aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms);
00193 
00194 /**
00195  * @brief MQTT Manual Re-Connection Function
00196  *
00197  * Called to establish an MQTT connection with the AWS IoT Service
00198  * using parameters from the last time a connection was attempted
00199  * Use after disconnect to start the reconnect process manually
00200  * Makes only one reconnect attempt Sets the client state to
00201  * pending reconnect in case of failure
00202  *
00203  * @param pClient Reference to the IoT Client
00204  *
00205  * @return An IoT Error Type defining successful/failed connection
00206  */
00207 IoT_Error_t aws_iot_mqtt_attempt_reconnect(AWS_IoT_Client *pClient);
00208 
00209 #ifdef __cplusplus
00210 }
00211 #endif
00212 
00213 #endif