aws_iot_shadow_json_data.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 #ifndef SRC_SHADOW_AWS_IOT_SHADOW_JSON_DATA_H_
00017 #define SRC_SHADOW_AWS_IOT_SHADOW_JSON_DATA_H_
00018 
00019 #ifdef __cplusplus
00020 extern "C" {
00021 #endif
00022 
00023 /**
00024  * @file aws_iot_shadow_json_data.h
00025  * @brief This file is the interface for all the Shadow related JSON functions.
00026  */
00027 
00028 #include <stddef.h>
00029 
00030 /**
00031  * @brief This is a static JSON object that could be used in code
00032  *
00033  */
00034 typedef struct jsonStruct jsonStruct_t;
00035 
00036 /**
00037  * @brief Every JSON name value can have a callback. The callback should follow this signature
00038  */
00039 typedef void (*jsonStructCallback_t)(const char *pJsonValueBuffer, uint32_t valueLength, jsonStruct_t *pJsonStruct_t);
00040 
00041 /**
00042  * @brief All the JSON object types enum
00043  *
00044  * JSON number types need to be split into proper integer / floating point data types and sizes on embedded platforms.
00045  */
00046 typedef enum {
00047     SHADOW_JSON_INT32,
00048     SHADOW_JSON_INT16,
00049     SHADOW_JSON_INT8,
00050     SHADOW_JSON_UINT32,
00051     SHADOW_JSON_UINT16,
00052     SHADOW_JSON_UINT8,
00053     SHADOW_JSON_FLOAT,
00054     SHADOW_JSON_DOUBLE,
00055     SHADOW_JSON_BOOL,
00056     SHADOW_JSON_STRING,
00057     SHADOW_JSON_OBJECT
00058 } JsonPrimitiveType;
00059 
00060 /**
00061  * @brief This is the struct form of a JSON Key value pair
00062  */
00063 struct jsonStruct {
00064     const char *pKey; ///< JSON key
00065     void *pData; ///< pointer to the data (JSON value)
00066     size_t dataLength; ///< Length (in bytes) of pData
00067     JsonPrimitiveType type; ///< type of JSON
00068     jsonStructCallback_t cb; ///< callback to be executed on receiving the Key value pair
00069 };
00070 
00071 /**
00072  * @brief Initialize the JSON document with Shadow expected name/value
00073  *
00074  * This Function will fill the JSON Buffer with a null terminated string. Internally it uses snprintf
00075  * This function should always be used First, followed by iot_shadow_add_reported and/or iot_shadow_add_desired.
00076  * Always finish the call sequence with iot_finalize_json_document
00077  *
00078  * @note Ensure the size of the Buffer is enough to hold the entire JSON Document.
00079  *
00080  *
00081  * @param pJsonDocument The JSON Document filled in this char buffer
00082  * @param maxSizeOfJsonDocument maximum size of the pJsonDocument that can be used to fill the JSON document
00083  * @return An IoT Error Type defining if the buffer was null or the entire string was not filled up
00084  */
00085 IoT_Error_t aws_iot_shadow_init_json_document(char *pJsonDocument, size_t maxSizeOfJsonDocument);
00086 
00087 /**
00088  * @brief Add the reported section of the JSON document of jsonStruct_t
00089  *
00090  * This is a variadic function and please be careful with the usage. count is the number of jsonStruct_t types that you would like to add in the reported section
00091  * This function will add "reported":{<all the values that needs to be added>}
00092  *
00093  * @note Ensure the size of the Buffer is enough to hold the reported section + the init section. Always use the same JSON document buffer used in the iot_shadow_init_json_document function. This function will accommodate the size of previous null terminated string, so pass teh max size of the buffer
00094  *
00095  *
00096  * @param pJsonDocument The JSON Document filled in this char buffer
00097  * @param maxSizeOfJsonDocument maximum size of the pJsonDocument that can be used to fill the JSON document
00098  * @param count total number of arguments(jsonStruct_t object) passed in the arguments
00099  * @return An IoT Error Type defining if the buffer was null or the entire string was not filled up
00100  */
00101 IoT_Error_t aws_iot_shadow_add_reported(char *pJsonDocument, size_t maxSizeOfJsonDocument, uint8_t count, ...);
00102 
00103 /**
00104  * @brief Add the desired section of the JSON document of jsonStruct_t
00105  *
00106  * This is a variadic function and please be careful with the usage. count is the number of jsonStruct_t types that you would like to add in the reported section
00107  * This function will add "desired":{<all the values that needs to be added>}
00108  *
00109  * @note Ensure the size of the Buffer is enough to hold the reported section + the init section. Always use the same JSON document buffer used in the iot_shadow_init_json_document function. This function will accommodate the size of previous null terminated string, so pass the max size of the buffer
00110  *
00111  *
00112  * @param pJsonDocument The JSON Document filled in this char buffer
00113  * @param maxSizeOfJsonDocument maximum size of the pJsonDocument that can be used to fill the JSON document
00114  * @param count total number of arguments(jsonStruct_t object) passed in the arguments
00115  * @return An IoT Error Type defining if the buffer was null or the entire string was not filled up
00116  */
00117 IoT_Error_t aws_iot_shadow_add_desired(char *pJsonDocument, size_t maxSizeOfJsonDocument, uint8_t count, ...);
00118 
00119 /**
00120  * @brief Finalize the JSON document with Shadow expected client Token.
00121  *
00122  * This function will automatically increment the client token every time this function is called.
00123  *
00124  * @note Ensure the size of the Buffer is enough to hold the entire JSON Document. If the finalized section is not invoked then the JSON doucment will not be valid
00125  *
00126  *
00127  * @param pJsonDocument The JSON Document filled in this char buffer
00128  * @param maxSizeOfJsonDocument maximum size of the pJsonDocument that can be used to fill the JSON document
00129  * @return An IoT Error Type defining if the buffer was null or the entire string was not filled up
00130  */
00131 IoT_Error_t aws_iot_finalize_json_document(char *pJsonDocument, size_t maxSizeOfJsonDocument);
00132 
00133 /**
00134  * @brief Fill the given buffer with client token for tracking the Repsonse.
00135  *
00136  * This function will add the AWS_IOT_MQTT_CLIENT_ID with a sequence number. Every time this function is used the sequence number gets incremented
00137  *
00138  *
00139  * @param pBufferToBeUpdatedWithClientToken buffer to be updated with the client token string
00140  * @param maxSizeOfJsonDocument maximum size of the pBufferToBeUpdatedWithClientToken that can be used
00141  * @return An IoT Error Type defining if the buffer was null or the entire string was not filled up
00142  */
00143 
00144 IoT_Error_t aws_iot_fill_with_client_token(char *pBufferToBeUpdatedWithClientToken, size_t maxSizeOfJsonDocument);
00145 
00146 #ifdef __cplusplus
00147 }
00148 #endif
00149 
00150 #endif /* SRC_SHADOW_AWS_IOT_SHADOW_JSON_DATA_H_ */