aws_iot_shadow_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 #ifndef AWS_IOT_SDK_SRC_IOT_SHADOW_H_
00016 #define AWS_IOT_SDK_SRC_IOT_SHADOW_H_
00017 
00018 #ifdef __cplusplus
00019 extern "C" {
00020 #endif
00021 
00022 
00023 /**
00024  * @file aws_iot_shadow_interface.h
00025  * @brief Interface for thing shadow
00026  *
00027  * These are the functions and structs to manage/interact the Thing Shadow(in the cloud).
00028  * This SDK will let you interact with your own thing shadow or any other shadow using its Thing Name.
00029  * There are totally 3 actions a device can perform on the shadow - Get, Update and Delete.
00030  *
00031  * Currently the device should use MQTT/S underneath. In the future this will also support other protocols. As it supports MQTT, the shadow needs to connect and disconnect.
00032  * It will also work on the pub/sub model. On performing any action, the acknowledgment will be received in either accepted or rejected. For Example:
00033  * If we want to perform a GET on the thing shadow the following messages will be sent and received:
00034  * 1. A MQTT Publish on the topic - $aws/things/{thingName}/shadow/get
00035  * 2. Subscribe to MQTT topics - $aws/things/{thingName}/shadow/get/accepted and $aws/things/{thingName}/shadow/get/rejected.
00036  * If the request was successful we will receive the things json document in the accepted topic.
00037  *
00038  *
00039  */
00040 #include "aws_iot_mqtt_client_interface.h"
00041 #include "aws_iot_shadow_json_data.h"
00042 
00043 /*!
00044  * @brief Shadow Initialization parameters
00045  *
00046  * As the Shadow SDK uses MQTT underneath, it could be connected and disconnected on events to save some battery.
00047  * @note Always use the \c ShadowIniTParametersDefault to initialize this struct
00048  *
00049  *
00050  *
00051  */
00052 typedef struct {
00053     char *pHost; ///< This will be unique to a customer and can be retrieved from the console
00054     uint16_t port; ///< Network port for TCP/IP socket
00055     char *pRootCA; ///< Location with the Filename of the Root CA
00056     char *pClientCRT; ///< Location of Device certs signed by AWS IoT service
00057     char *pClientKey; ///< Location of Device private key
00058     bool enableAutoReconnect;        ///< Set to true to enable auto reconnect
00059     iot_disconnect_handler disconnectHandler;    ///< Callback to be invoked upon connection loss.
00060 } ShadowInitParameters_t;
00061 
00062 /*!
00063  * @brief Shadow Connect parameters
00064  *
00065  * As the Shadow SDK uses MQTT underneath, it could be connected and disconnected on events to save some battery.
00066  * @note Always use the \c ShadowConnectParametersDefault to initialize this struct
00067  *
00068  *d
00069  *
00070  */
00071 typedef struct {
00072     char *pMyThingName; ///< Every device has a Thing Shadow and this is the placeholder for name
00073     char *pMqttClientId; ///< Currently the Shadow uses MQTT to connect and it is important to ensure we have unique client id
00074     uint16_t mqttClientIdLen; ///< Currently the Shadow uses MQTT to connect and it is important to ensure we have unique client id
00075     pApplicationHandler_t deleteActionHandler;  ///< Callback to be invoked when Thing shadow for this device is deleted
00076 } ShadowConnectParameters_t;
00077 
00078 /*!
00079  * @brief This is set to defaults from the configuration file
00080  * The certs are set to NULL because they need the path to the file. shadow_sample.c file demonstrates on how to get the relative path
00081  *
00082  * \relates ShadowInitParameters_t
00083  */
00084 extern const ShadowInitParameters_t ShadowInitParametersDefault;
00085 
00086 /*!
00087  * @brief This is set to defaults from the configuration file
00088  * The length of the client id is initialized as 0. This is due to C language limitations of using constant literals
00089  * only for creating const variables. The client id will be assigned using the value from aws_iot_config.h but the
00090  * length needs to be assigned in code. shadow_sample.c file demonstrates this.
00091  *
00092  * \relates ShadowConnectParameters_t
00093  */
00094 extern const ShadowConnectParameters_t ShadowConnectParametersDefault;
00095 
00096 /**
00097 * @brief Clean shadow client from all dynamic memory allocate
00098 *
00099 * This function will free up memory that was dynamically allocated for the client. 
00100 *
00101 * @param pClient MQTT Client that was previously created by calling aws_iot_shadow_init
00102 * @return An IoT Error Type defining successful/failed freeing
00103 */
00104 IoT_Error_t aws_iot_shadow_free(AWS_IoT_Client *pClient);
00105 
00106 /**
00107  * @brief Initialize the Thing Shadow before use
00108  *
00109  * This function takes care of initializing the internal book-keeping data structures and initializing the IoT client.
00110  *
00111  * @param pClient A new MQTT Client to be used as the protocol layer. Will be initialized with pParams.
00112  * @return An IoT Error Type defining successful/failed Initialization
00113  */
00114 IoT_Error_t aws_iot_shadow_init(AWS_IoT_Client *pClient, ShadowInitParameters_t *pParams);
00115 
00116 /**
00117  * @brief Connect to the AWS IoT Thing Shadow service over MQTT
00118  *
00119  * This function does the TLSv1.2 handshake and establishes the MQTT connection
00120  *
00121  * @param pClient   MQTT Client used as the protocol layer
00122  * @param pParams   Shadow Conenction parameters like TLS cert location
00123  * @return An IoT Error Type defining successful/failed Connection
00124  */
00125 IoT_Error_t aws_iot_shadow_connect(AWS_IoT_Client *pClient, ShadowConnectParameters_t *pParams);
00126 
00127 /**
00128  * @brief Yield function to let the background tasks of MQTT and Shadow
00129  *
00130  * This function could be use in a separate thread waiting for the incoming messages, ensuring the connection is kept alive with the AWS Service.
00131  * It also ensures the expired requests of Shadow actions are cleared and Timeout callback is executed.
00132  * @note All callbacks ever used in the SDK will be executed in the context of this function.
00133  *
00134  * @param pClient   MQTT Client used as the protocol layer
00135  * @param timeout   in milliseconds, This is the maximum time the yield function will wait for a message and/or read the messages from the TLS buffer
00136  * @return An IoT Error Type defining successful/failed Yield
00137  */
00138 IoT_Error_t aws_iot_shadow_yield(AWS_IoT_Client *pClient, uint32_t timeout);
00139 
00140 /**
00141  * @brief Disconnect from the AWS IoT Thing Shadow service over MQTT
00142  *
00143  * This will close the underlying TCP connection, MQTT connection will also be closed
00144  *
00145  * @param pClient   MQTT Client used as the protocol layer
00146  * @return An IoT Error Type defining successful/failed disconnect status
00147  */
00148 IoT_Error_t aws_iot_shadow_disconnect(AWS_IoT_Client *pClient);
00149 
00150 /**
00151  * @brief Thing Shadow Acknowledgment enum
00152  *
00153  * This enum type is use in the callback for the action response
00154  *
00155  */
00156 typedef enum {
00157     SHADOW_ACK_TIMEOUT, SHADOW_ACK_REJECTED, SHADOW_ACK_ACCEPTED
00158 } Shadow_Ack_Status_t;
00159 
00160 /**
00161  * @brief Thing Shadow Action type enum
00162  *
00163  * This enum type is use in the callback for the action response
00164  *
00165  */
00166 typedef enum {
00167     SHADOW_GET, SHADOW_UPDATE, SHADOW_DELETE
00168 } ShadowActions_t;
00169 
00170 
00171 /**
00172  * @brief Function Pointer typedef used as the callback for every action
00173  *
00174  * This function will be called from the context of \c aws_iot_shadow_yield() context
00175  *
00176  * @param pThingName Thing Name of the response received
00177  * @param action The response of the action
00178  * @param status Informs if the action was Accepted/Rejected or Timed out
00179  * @param pReceivedJsonDocument Received JSON document
00180  * @param pContextData the void* data passed in during the action call(update, get or delete)
00181  *
00182  */
00183 typedef void (*fpActionCallback_t)(const char *pThingName, ShadowActions_t action, Shadow_Ack_Status_t status,
00184                                    const char *pReceivedJsonDocument, void *pContextData);
00185 
00186 /**
00187  * @brief This function is the one used to perform an Update action to a Thing Name's Shadow.
00188  *
00189  * update is one of the most frequently used functionality by a device. In most cases the device may be just reporting few params to update the thing shadow in the cloud
00190  * Update Action if no callback or if the JSON document does not have a client token then will just publish the update and not track it.
00191  *
00192  * @note The update has to subscribe to two topics update/accepted and update/rejected. This function waits 2 seconds to ensure the subscriptions are registered before publishing the update message.
00193  * The following steps are performed on using this function:
00194  * 1. Subscribe to Shadow topics - $aws/things/{thingName}/shadow/update/accepted and $aws/things/{thingName}/shadow/update/rejected
00195  * 2. wait for 2 seconds for the subscription to take effect
00196  * 3. Publish on the update topic - $aws/things/{thingName}/shadow/update
00197  * 4. In the \c aws_iot_shadow_yield() function the response will be handled. In case of timeout or if the response is received, the subscription to shadow response topics are un-subscribed from.
00198  *    On the contrary if the persistent subscription is set to true then the un-subscribe will not be done. The topics will always be listened to.
00199  *
00200  * @param pClient   MQTT Client used as the protocol layer
00201  * @param pThingName Thing Name of the shadow that needs to be Updated
00202  * @param pJsonString The update action expects a JSON document to send. The JSON String should be a null terminated string. This JSON document should adhere to the AWS IoT Thing Shadow specification. To help in the process of creating this document- SDK provides apis in \c aws_iot_shadow_json_data.h
00203  * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important
00204  * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used
00205  * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action
00206  * @param isPersistentSubscribe As mentioned above, every  time if a device updates the same shadow then this should be set to true to avoid repeated subscription and unsubscription. If the Thing Name is one off update then this should be set to false
00207  * @return An IoT Error Type defining successful/failed update action
00208  */
00209 IoT_Error_t aws_iot_shadow_update(AWS_IoT_Client *pClient, const char *pThingName, char *pJsonString,
00210                                   fpActionCallback_t callback, void *pContextData, uint8_t timeout_seconds,
00211                                   bool isPersistentSubscribe);
00212 
00213 /**
00214  * @brief This function is the one used to perform an Get action to a Thing Name's Shadow.
00215  *
00216  * One use of this function is usually to get the config of a device at boot up.
00217  * It is similar to the Update function internally except it does not take a JSON document as the input. The entire JSON document will be sent over the accepted topic
00218  *
00219  * @param pClient   MQTT Client used as the protocol layer
00220  * @param pThingName Thing Name of the JSON document that is needed
00221  * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important
00222  * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used
00223  * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action
00224  * @param isPersistentSubscribe As mentioned above, every  time if a device gets the same Sahdow (JSON document) then this should be set to true to avoid repeated subscription and un-subscription. If the Thing Name is one off get then this should be set to false
00225  * @return An IoT Error Type defining successful/failed get action
00226  */
00227 IoT_Error_t aws_iot_shadow_get(AWS_IoT_Client *pClient, const char *pThingName, fpActionCallback_t callback,
00228                                void *pContextData, uint8_t timeout_seconds, bool isPersistentSubscribe);
00229 
00230 /**
00231  * @brief This function is the one used to perform an Delete action to a Thing Name's Shadow.
00232  *
00233  * This is not a very common use case for  device. It is generally the responsibility of the accompanying app to do the delete.
00234  * It is similar to the Update function internally except it does not take a JSON document as the input. The Thing Shadow referred by the ThingName will be deleted.
00235  *
00236  * @param pClient MQTT Client used as the protocol layer
00237  * @param pThingName Thing Name of the Shadow that should be deleted
00238  * @param callback This is the callback that will be used to inform the caller of the response from the AWS IoT Shadow service.Callback could be set to NULL if response is not important
00239  * @param pContextData This is an extra parameter that could be passed along with the callback. It should be set to NULL if not used
00240  * @param timeout_seconds It is the time the SDK will wait for the response on either accepted/rejected before declaring timeout on the action
00241  * @param isPersistentSubscribe As mentioned above, every  time if a device deletes the same Shadow (JSON document) then this should be set to true to avoid repeated subscription and un-subscription. If the Thing Name is one off delete then this should be set to false
00242  * @return An IoT Error Type defining successful/failed delete action
00243  */
00244 IoT_Error_t aws_iot_shadow_delete(AWS_IoT_Client *pClient, const char *pThingName, fpActionCallback_t callback,
00245                                   void *pContextData, uint8_t timeout_seconds, bool isPersistentSubscriptions);
00246 
00247 /**
00248  * @brief This function is used to listen on the delta topic of #AWS_IOT_MY_THING_NAME mentioned in the aws_iot_config.h file.
00249  *
00250  * Any time a delta is published the Json document will be delivered to the pStruct->cb. If you don't want the parsing done by the SDK then use the jsonStruct_t key set to "state". A good example of this is displayed in the sample_apps/shadow_console_echo.c
00251  *
00252  * @param pClient MQTT Client used as the protocol layer
00253  * @param pStruct The struct used to parse JSON value
00254  * @return An IoT Error Type defining successful/failed delta registering
00255  */
00256 IoT_Error_t aws_iot_shadow_register_delta(AWS_IoT_Client *pClient, jsonStruct_t *pStruct);
00257 
00258 /**
00259  * @brief Reset the last received version number to zero.
00260  * This will be useful if the Thing Shadow is deleted and would like to to reset the local version
00261  * @return no return values
00262  *
00263  */
00264 void aws_iot_shadow_reset_last_received_version(void);
00265 
00266 /**
00267  * @brief Version of a document is received with every accepted/rejected and the SDK keeps track of the last received version of the JSON document of #AWS_IOT_MY_THING_NAME shadow
00268  *
00269  * One exception to this version tracking is that, the SDK will ignore the version from update/accepted topic. Rest of the responses will be scanned to update the version number.
00270  * Accepting version change for update/accepted may cause version conflicts for delta message if the update message is received before the delta.
00271  *
00272  * @return version number of the last received response
00273  *
00274  */
00275 uint32_t aws_iot_shadow_get_last_received_version(void);
00276 
00277 /**
00278  * @brief Enable the ignoring of delta messages with old version number
00279  *
00280  * As we use MQTT underneath, there could be more than 1 of the same message if we use QoS 0. To avoid getting called for the same message, this functionality should be enabled. All the old message will be ignored
00281  */
00282 void aws_iot_shadow_enable_discard_old_delta_msgs(void);
00283 
00284 /**
00285  * @brief Disable the ignoring of delta messages with old version number
00286  */
00287 void aws_iot_shadow_disable_discard_old_delta_msgs(void);
00288 
00289 /**
00290  * @brief This function is used to enable or disable autoreconnect
00291  *
00292  * Any time a disconnect happens the underlying MQTT client attempts to reconnect if this is set to true
00293  *
00294  * @param pClient MQTT Client used as the protocol layer
00295  * @param newStatus The new status to set the autoreconnect option to
00296  *
00297  * @return An IoT Error Type defining successful/failed operation
00298  */
00299 IoT_Error_t aws_iot_shadow_set_autoreconnect_status(AWS_IoT_Client *pClient, bool newStatus);
00300 
00301 #ifdef __cplusplus
00302 }
00303 #endif
00304 
00305 #endif //AWS_IOT_SDK_SRC_IOT_SHADOW_H_