shadow.h

Go to the documentation of this file.

/*
 * AWS IoT Device Shadow v1.0.2
 * Copyright (C) 2020 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 SHADOW_H_
#define SHADOW_H_
 
/* Standard includes. */
#include <stdint.h>
 
/* SHADOW_DO_NOT_USE_CUSTOM_CONFIG allows building the Shadow library
 * without a custom config. If a custom config is provided, the
 * SHADOW_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
#ifndef SHADOW_DO_NOT_USE_CUSTOM_CONFIG
    /* Include custom config file before other headers. */
    #include "shadow_config.h"
#endif
 
/* Include config defaults header to get default values of configs not
 * defined in shadow_config_defaults.h file. */
#include "shadow_config_defaults.h"
 
/*--------------------------- Shadow types ---------------------------*/
 
typedef enum ShadowMessageType
{
    ShadowMessageTypeGetAccepted = 0,
    ShadowMessageTypeGetRejected,
    ShadowMessageTypeDeleteAccepted,
    ShadowMessageTypeDeleteRejected,
    ShadowMessageTypeUpdateAccepted,
    ShadowMessageTypeUpdateRejected,
    ShadowMessageTypeUpdateDocuments,
    ShadowMessageTypeUpdateDelta,
    ShadowMessageTypeMaxNum
} ShadowMessageType_t;
 
typedef enum ShadowTopicStringType
{
    ShadowTopicStringTypeGet = 0,
    ShadowTopicStringTypeGetAccepted,
    ShadowTopicStringTypeGetRejected,
    ShadowTopicStringTypeDelete,
    ShadowTopicStringTypeDeleteAccepted,
    ShadowTopicStringTypeDeleteRejected,
    ShadowTopicStringTypeUpdate,
    ShadowTopicStringTypeUpdateAccepted,
    ShadowTopicStringTypeUpdateRejected,
    ShadowTopicStringTypeUpdateDocuments,
    ShadowTopicStringTypeUpdateDelta,
    ShadowTopicStringTypeMaxNum
} ShadowTopicStringType_t;
 
typedef enum ShadowStatus
{
    SHADOW_SUCCESS = 0,                     
    SHADOW_FAIL,                            
    SHADOW_BAD_PARAMETER,                   
    SHADOW_BUFFER_TOO_SMALL,                
    SHADOW_THINGNAME_PARSE_FAILED,          
    SHADOW_SHADOW_MESSAGE_TYPE_PARSE_FAILED 
} ShadowStatus_t;
 
/*------------------------ Shadow library functions -------------------------*/
 
#define SHADOW_PREFIX                     "$aws/things/"
 
#define SHADOW_PREFIX_LENGTH              ( ( uint16_t ) ( sizeof( SHADOW_PREFIX ) - 1U ) )
 
#define SHADOW_OP_DELETE                  "/shadow/delete"
 
#define SHADOW_OP_DELETE_LENGTH           ( ( uint16_t ) ( sizeof( SHADOW_OP_DELETE ) - 1U ) )
 
#define SHADOW_OP_GET                     "/shadow/get"
 
#define SHADOW_OP_GET_LENGTH              ( ( uint16_t ) ( sizeof( SHADOW_OP_GET ) - 1U ) )
 
#define SHADOW_OP_UPDATE                  "/shadow/update"
 
#define SHADOW_OP_UPDATE_LENGTH           ( ( uint16_t ) ( sizeof( SHADOW_OP_UPDATE ) - 1U ) )
 
#define SHADOW_SUFFIX_ACCEPTED            "/accepted"
 
#define SHADOW_SUFFIX_ACCEPTED_LENGTH     ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_ACCEPTED ) - 1U ) )
 
#define SHADOW_SUFFIX_REJECTED            "/rejected"
 
#define SHADOW_SUFFIX_REJECTED_LENGTH     ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_REJECTED ) - 1U ) )
 
#define SHADOW_SUFFIX_DELTA               "/delta"
 
#define SHADOW_SUFFIX_DELTA_LENGTH        ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DELTA ) - 1U ) )
 
#define SHADOW_SUFFIX_DOCUMENTS           "/documents"
 
#define SHADOW_SUFFIX_DOCUMENTS_LENGTH    ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DOCUMENTS ) - 1U ) )
 
#define SHADOW_SUFFIX_NULL
 
#define SHADOW_SUFFIX_NULL_LENGTH      ( 0U )
 
#define SHADOW_THINGNAME_LENGTH_MAX    ( 128U )
 
#define SHADOW_TOPIC_LENGTH( operationLength, suffixLength, thingNameLength ) \
    ( operationLength + suffixLength + thingNameLength + SHADOW_PREFIX_LENGTH )
 
#define SHADOW_TOPIC_LENGTH_UPDATE( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_UPDATE_DELTA( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DELTA_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_GET( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_GET_ACCEPTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_GET_REJECTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_DELETE( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_DELETE_REJECTED( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_LENGTH_MAX( thingNameLength ) \
    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
 
#define SHADOW_TOPIC_STRING( thingName, operation, suffix ) \
    ( SHADOW_PREFIX thingName operation suffix )
 
#define SHADOW_TOPIC_STRING_UPDATE( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_NULL )
 
#define SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_ACCEPTED )
 
#define SHADOW_TOPIC_STRING_UPDATE_REJECTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_REJECTED )
 
#define SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DOCUMENTS )
 
#define SHADOW_TOPIC_STRING_UPDATE_DELTA( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DELTA )
 
#define SHADOW_TOPIC_STRING_GET( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_NULL )
 
#define SHADOW_TOPIC_STRING_GET_ACCEPTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_ACCEPTED )
 
#define SHADOW_TOPIC_STRING_GET_REJECTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_REJECTED )
 
#define SHADOW_TOPIC_STRING_DELETE( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_NULL )
 
#define SHADOW_TOPIC_STRING_DELETE_ACCEPTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_ACCEPTED )
 
#define SHADOW_TOPIC_STRING_DELETE_REJECTED( thingName ) \
    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_REJECTED )
 
/* @[declare_shadow_gettopicstring] */
ShadowStatus_t Shadow_GetTopicString( ShadowTopicStringType_t topicType,
                                      const char * pThingName,
                                      uint8_t thingNameLength,
                                      char * pTopicBuffer,
                                      uint16_t bufferSize,
                                      uint16_t * pOutLength );
/* @[declare_shadow_gettopicstring] */
 
/* @[declare_shadow_matchtopic] */
ShadowStatus_t Shadow_MatchTopic( const char * pTopic,
                                  uint16_t topicLength,
                                  ShadowMessageType_t * pMessageType,
                                  const char ** pThingName,
                                  uint16_t * pThingNameLength );
/* @[declare_shadow_matchtopic] */
 
#endif /* ifndef SHADOW_H_ */