aws_iot_shadow_internal.h

Go to the documentation of this file.

/*
 * AWS IoT Shadow V2.1.0
 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef AWS_IOT_SHADOW_INTERNAL_H_
#define AWS_IOT_SHADOW_INTERNAL_H_

/* The config header is always included first. */
#include "iot_config.h"

/* Linear containers (lists and queues) include. */
#include "iot_linear_containers.h"

/* Platform layer types include. */
#include "types/iot_platform_types.h"

/* Shadow include. */
#include "aws_iot_shadow.h"

/* AWS IoT include. */
#include "aws_iot.h"

#if AWS_IOT_SHADOW_ENABLE_ASSERTS == 1
    #ifndef AwsIotShadow_Assert
        #ifdef Iot_DefaultAssert
            #define AwsIotShadow_Assert( expression )    Iot_DefaultAssert( expression )
        #else
            #error "Asserts are enabled for Shadow, but AwsIotShadow_Assert is not defined"
        #endif
    #endif
#else /* if AWS_IOT_SHADOW_ENABLE_ASSERTS == 1 */
    #define AwsIotShadow_Assert( expression )
#endif /* if AWS_IOT_SHADOW_ENABLE_ASSERTS == 1 */

/* Configure logs for Shadow functions. */
#ifdef AWS_IOT_LOG_LEVEL_SHADOW
    #define LIBRARY_LOG_LEVEL        AWS_IOT_LOG_LEVEL_SHADOW
#else
    #ifdef IOT_LOG_LEVEL_GLOBAL
        #define LIBRARY_LOG_LEVEL    IOT_LOG_LEVEL_GLOBAL
    #else
        #define LIBRARY_LOG_LEVEL    IOT_LOG_NONE
    #endif
#endif

#define LIBRARY_LOG_NAME    ( "Shadow" )
#include "iot_logging_setup.h"

/*
 * Provide default values for undefined memory allocation functions based on
 * the usage of dynamic memory allocation.
 */
#if IOT_STATIC_MEMORY_ONLY == 1
    #include "iot_static_memory.h"

    void * AwsIotShadow_MallocOperation( size_t size );

    void AwsIotShadow_FreeOperation( void * ptr );

    #define AwsIotShadow_MallocString    Iot_MallocMessageBuffer

    #define AwsIotShadow_FreeString      Iot_FreeMessageBuffer

    void * AwsIotShadow_MallocSubscription( size_t size );

    void AwsIotShadow_FreeSubscription( void * ptr );
#else /* if IOT_STATIC_MEMORY_ONLY == 1 */
    #ifndef AwsIotShadow_MallocOperation
        #ifdef Iot_DefaultMalloc
            #define AwsIotShadow_MallocOperation    Iot_DefaultMalloc
        #else
            #error "No malloc function defined for AwsIotShadow_MallocOperation"
        #endif
    #endif

    #ifndef AwsIotShadow_FreeOperation
        #ifdef Iot_DefaultFree
            #define AwsIotShadow_FreeOperation    Iot_DefaultFree
        #else
            #error "No free function defined for AwsIotShadow_FreeOperation"
        #endif
    #endif

    #ifndef AwsIotShadow_MallocString
        #ifdef Iot_DefaultMalloc
            #define AwsIotShadow_MallocString    Iot_DefaultMalloc
        #else
            #error "No malloc function defined for AwsIotShadow_MallocString"
        #endif
    #endif

    #ifndef AwsIotShadow_FreeString
        #ifdef Iot_DefaultFree
            #define AwsIotShadow_FreeString    Iot_DefaultFree
        #else
            #error "No free function defined for AwsIotShadow_FreeString"
        #endif
    #endif

    #ifndef AwsIotShadow_MallocSubscription
        #ifdef Iot_DefaultMalloc
            #define AwsIotShadow_MallocSubscription    Iot_DefaultMalloc
        #else
            #error "No malloc function defined for AwsIotShadow_MallocSubscription"
        #endif
    #endif

    #ifndef AwsIotShadow_FreeSubscription
        #ifdef Iot_DefaultFree
            #define AwsIotShadow_FreeSubscription    Iot_DefaultFree
        #else
            #error "No free function defined for AwsIotShadow_FreeSubscription"
        #endif
    #endif
#endif /* if IOT_STATIC_MEMORY_ONLY == 1 */

#ifndef AWS_IOT_SHADOW_DEFAULT_MQTT_TIMEOUT_MS
    #define AWS_IOT_SHADOW_DEFAULT_MQTT_TIMEOUT_MS    ( 5000 )
#endif

#define SHADOW_OPERATION_COUNT                   ( 3U )

#define SHADOW_CALLBACK_COUNT                    ( 2 )

#define SHADOW_DELETE_OPERATION_STRING           "/shadow/delete"

#define SHADOW_DELETE_OPERATION_STRING_LENGTH    ( ( uint16_t ) ( sizeof( SHADOW_DELETE_OPERATION_STRING ) - 1U ) )

#define SHADOW_GET_OPERATION_STRING              "/shadow/get"

#define SHADOW_GET_OPERATION_STRING_LENGTH       ( ( uint16_t ) ( sizeof( SHADOW_GET_OPERATION_STRING ) - 1U ) )

#define SHADOW_UPDATE_OPERATION_STRING           "/shadow/update"

#define SHADOW_UPDATE_OPERATION_STRING_LENGTH    ( ( uint16_t ) ( sizeof( SHADOW_UPDATE_OPERATION_STRING ) - 1U ) )

#define SHADOW_DELTA_SUFFIX                      "/delta"

#define SHADOW_DELTA_SUFFIX_LENGTH               ( ( uint16_t ) ( sizeof( SHADOW_DELTA_SUFFIX ) - 1U ) )

#define SHADOW_UPDATED_SUFFIX                    "/documents"

#define SHADOW_UPDATED_SUFFIX_LENGTH             ( ( uint16_t ) ( sizeof( SHADOW_UPDATED_SUFFIX ) - 1U ) )

#define SHADOW_LONGEST_SUFFIX_LENGTH             SHADOW_UPDATED_SUFFIX_LENGTH

#define SHADOW_CONVERT_STATUS_CODE_MQTT_TO_SHADOW( X )           \
    ( ( X ) == IOT_MQTT_SUCCESS ) ? AWS_IOT_SHADOW_SUCCESS :     \
    ( ( X ) == IOT_MQTT_NO_MEMORY ) ? AWS_IOT_SHADOW_NO_MEMORY : \
    AWS_IOT_SHADOW_MQTT_ERROR

/*----------------------- Shadow internal data types ------------------------*/

typedef enum _shadowOperationType
{
    /* Shadow operations. */
    SHADOW_DELETE = 0, 
    SHADOW_GET = 1,    
    SHADOW_UPDATE = 2, 
    /* Shadow callbacks. */
    SET_DELTA_CALLBACK = 3,  
    SET_UPDATED_CALLBACK = 4 
} _shadowOperationType_t;

typedef enum _shadowCallbackType
{
    DELTA_CALLBACK = 0,  
    UPDATED_CALLBACK = 1 
} _shadowCallbackType_t;

typedef struct _shadowSubscription
{
    IotLink_t link;                                                
    int32_t references[ SHADOW_OPERATION_COUNT ];                  
    AwsIotShadowCallbackInfo_t callbacks[ SHADOW_CALLBACK_COUNT ]; 
    char * pTopicBuffer;

    size_t thingNameLength; 
    char pThingName[];      
} _shadowSubscription_t;

typedef struct _shadowOperation
{
    IotLink_t link; 
    /* Basic operation information. */
    _shadowOperationType_t type;           
    uint32_t flags;                        
    AwsIotShadowError_t status;            
    IotMqttConnection_t mqttConnection;    
    _shadowSubscription_t * pSubscription; 
    union
    {
        /* Members valid only for a GET operation. */
        struct
        {
            void *( *mallocDocument )( size_t );

            const char * pDocument; 
            size_t documentLength;  
        } get;

        /* Members valid only for an UPDATE operation. */
        struct
        {
            const char * pClientToken; 
            size_t clientTokenLength;  
        } update;
    } u;                               
    /* How to notify of an operation's completion. */
    union
    {
        IotSemaphore_t waitSemaphore;        
        AwsIotShadowCallbackInfo_t callback; 
    } notify;                                
} _shadowOperation_t;

/* Declarations of names printed in logs. */
#if LIBRARY_LOG_LEVEL > IOT_LOG_NONE
    extern const char * const _pAwsIotShadowOperationNames[];
    extern const char * const _pAwsIotShadowCallbackNames[];
#endif

/* Declarations of variables for internal Shadow files. */
extern uint32_t _AwsIotShadowMqttTimeoutMs;
extern IotListDouble_t _AwsIotShadowPendingOperations;
extern IotListDouble_t _AwsIotShadowSubscriptions;
extern IotMutex_t _AwsIotShadowPendingOperationsMutex;
extern IotMutex_t _AwsIotShadowSubscriptionsMutex;

/*----------------------- Shadow operation functions ------------------------*/

AwsIotShadowError_t _AwsIotShadow_CreateOperation( _shadowOperation_t ** pNewOperation,
                                                   _shadowOperationType_t type,
                                                   uint32_t flags,
                                                   const AwsIotShadowCallbackInfo_t * pCallbackInfo );

void _AwsIotShadow_DestroyOperation( void * pData );

AwsIotShadowError_t _AwsIotShadow_GenerateShadowTopic( _shadowOperationType_t type,
                                                       const char * pThingName,
                                                       size_t thingNameLength,
                                                       char ** pTopicBuffer,
                                                       uint16_t * pOperationTopicLength );

AwsIotShadowError_t _AwsIotShadow_ProcessOperation( IotMqttConnection_t mqttConnection,
                                                    const char * pThingName,
                                                    size_t thingNameLength,
                                                    _shadowOperation_t * pOperation,
                                                    const AwsIotShadowDocumentInfo_t * pDocumentInfo );



_shadowOperationType_t _AwsIotShadow_IntToShadowOperationType( uint32_t n );

AwsIotShadowCallbackType_t _AwsIotShadow_IntToShadowCallbackType( uint32_t n );

/*---------------------- Shadow subscription functions ----------------------*/

_shadowSubscription_t * _AwsIotShadow_FindSubscription( const char * pThingName,
                                                        size_t thingNameLength,
                                                        bool createIfNotFound );

void _AwsIotShadow_RemoveSubscription( _shadowSubscription_t * pSubscription,
                                       _shadowSubscription_t ** pRemovedSubscription );

void _AwsIotShadow_DestroySubscription( void * pData );

AwsIotShadowError_t _AwsIotShadow_IncrementReferences( _shadowOperation_t * pOperation,
                                                       char * pTopicBuffer,
                                                       uint16_t operationTopicLength,
                                                       AwsIotMqttCallbackFunction_t callback );

void _AwsIotShadow_DecrementReferences( _shadowOperation_t * pOperation,
                                        char * pTopicBuffer,
                                        _shadowSubscription_t ** pRemovedSubscription );

/*------------------------- Shadow parser functions -------------------------*/

AwsIotShadowError_t _AwsIotShadow_ParseErrorDocument( const char * pErrorDocument,
                                                      size_t errorDocumentLength );

#endif /* ifndef AWS_IOT_SHADOW_INTERNAL_H_ */