lib/include/aws_shadow.h

/*
 * Amazon FreeRTOS
 * Copyright (C) 2017 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.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */

/**
 * @file aws_shadow.h
 * @brief Shadow API configuration, functions, and parameter structs.
 */

#ifndef _AWS_SHADOW_H_
#define _AWS_SHADOW_H_

#include "FreeRTOS.h"

#include "aws_mqtt_agent.h"


/**
 * @brief The handle of a Shadow Client.
 */
typedef void * ShadowClientHandle_t;

/**
 * @brief Return values of Shadow API functions.
 *
 * Negative values indicate jsmn (JSON parser) errors, and @c 0 indicates
 * success. Positive values indicate other errors. Values in the range of @c 400
 * to @c 500 correspond to Shadow service rejection reasons.
 *
 * Refer to jsmn.h for jsmn errors.
 *
 * Refer to
 * http://docs.aws.amazon.com/iot/latest/developerguide/thing-shadow-error-messages.html
 * for Shadow service rejection reasons.
 */
#define eShadowJSMNPart     ( -3 )
#define eShadowJSMNInval    ( -2 )
#define eShadowJSMNNoMem    ( -1 )

/** An operation was accepted by the Shadow service, and all subroutines
 * completed successfully. */
#define eShadowSuccess      ( 0 )

/** Timeout signifies that at least one of the API call's subroutines failed to
 * complete within the given time. This error can usually be fixed by increasing
 * the timeout parameter.
 * @note
 * - Timeout doesn't always imply rejection. An operation may still be accepted
 * after a timeout. However, the Shadow Client will not notify of acceptance or
 * rejection after a timeout.
 * - If an update fails because of incorrect JSON syntax in the update document,
 * the update API call will return this code instead of @c eShadowRejectedBadRequest
 * and print an error message if #shadowENABLE_DEBUG_LOGS is @c 1. */
#define eShadowTimeout      ( 1 )

/** Failure code; signifies that at least one subroutine failed to complete
 * and did not time out. */
#define eShadowFailure      ( 2 )

/** Indicates neither failure nor success. This value should never be returned
 * by a Shadow API function, but is used internally. */
#define eShadowUnknown      ( 3 )

/**
 * @brief Shadow service rejection reasons. */
/** @{ */
#define eShadowRejectedBadRequest              ( 400 )
#define eShadowRejectedUnauthorized            ( 401 )
#define eShadowRejectedForbidden               ( 403 )
#define eShadowRejectedNotFound                ( 404 )
#define eShadowRejectedConflict                ( 409 )
#define eShadowRejectedPayloadTooLarge         ( 413 )
#define eShadowRejectedUnsupportedMediaType    ( 415 )
#define eShadowRejectedTooManyRequests         ( 429 )
#define eShadowRejectedInternalServerError     ( 500 )
typedef int16_t ShadowReturnCode_t;
/** @} */

/**
 * @brief Type of MQTT client in a new Shadow Client.
 *
 * The possible values of #ShadowCreateParams_t.xMQTTClientType; determines
 * whether to initialize a shared or dedicated MQTT client.
 * @note Only #eDedicatedMQTTClient is supported at this time.
 */
typedef enum ShadowMQTTClientType
{
    /** A shared MQTT client that may be used for purposes other than Shadow
     * Client. Currently unsupported. */
    eSharedMQTTClient,
    /** A dedicated MQTT client to be used only by Shadow Client. */
    eDedicatedMQTTClient
} ShadowMQTTClientType_t;

/**
 * @brief Parameters to pass into #SHADOW_ClientCreate.
 */
typedef struct ShadowCreateParams
{
    /**
     * @brief MQTT Client type.
     *
     * Whether the new Shadow Client will use a shared or dedicated MQTT Client.
     * Currently, only #eDedicatedMQTTClient is supported.
     * @see ShadowMQTTClientType. */
    ShadowMQTTClientType_t xMQTTClientType;

    /**
     * @brief Handle of a shared MQTT client.
     *
     * If #ShadowCreateParams_t.xMQTTClientType is #eSharedMQTTClient, set this to
     * the handle of the shared client. This member is ignored if
     #ShadowCreateParams_t.xMQTTClientType is #eDedicatedMQTTClient. */
    MQTTAgentHandle_t xMQTTClientHandle;
} ShadowCreateParams_t;

/**
 * @brief Parameters for a Shadow API operation.
 *
 * Pass this struct as one of the arguments for #SHADOW_Update, #SHADOW_Get, or
 * #SHADOW_Delete.
 */
typedef struct ShadowOperationParams
{
    /** @brief Thing name of Shadow. */
    const char * pcThingName;

    /**
     * @brief Input parameter for #SHADOW_Update; output parameter of #SHADOW_Get.
     * - For #SHADOW_Update, set this to point to the Shadow update document.
     * - For #SHADOW_Get, this is the output parameter pointing to a buffer which
     * holds the Shadow document. If #SHADOW_Get fails, this will be set to NULL.
     * - This member is ignored by #SHADOW_Delete. */
    const char * pcData;

    /**
     * @brief Input parameter for #SHADOW_Update; output parameter of #SHADOW_Get.
     * - For #SHADOW_Update, set this to length of the Shadow update document.
     * - For #SHADOW_Get, this is the output parameter specifying the length of
     #ShadowOperationParams_t.pcData. If #SHADOW_Get fails, this will be set
     * to @c 0.
     * @note If the received Shadow document is longer than this value, the
     * document will be truncated. A warning message will be printed if
     #shadowENABLE_DEBUG_LOGS is @c 1.
     * - This member is ignored by #SHADOW_Delete. */
    uint32_t ulDataLength;

    /**
     * @brief Output parameter of #SHADOW_Get.
     * - This member is ignored by #SHADOW_Update.
     * - For #SHADOW_Get, this is the output parameter for the MQTT Buffer Handle.
     * This buffer must be returned to the MQTT Client after the user is done
     * with the received document by calling #SHADOW_ReturnMQTTBuffer.
     * - This member is ignored by #SHADOW_Delete. */
    MQTTBufferHandle_t xBuffer;

    /**
     * @brief Controls whether topic subscriptions remain active after a Shadow
     * operation completes.
     *
     * Allows the MQTT subscriptions of the operation to remain active if set
     * to @c 1, saving time if the same operation is performed again. Set this
     * value to @c 0 to deactivate the operation's MQTT subscriptions after the
     * operation completes.
     * @warning Users may be billed for extraneous messages received on an
     * operation's MQTT topics. If other clients are publishing to the same topics,
     * it is best to deactivate the subscriptions. */
    uint8_t ucKeepSubscriptions;

    /**
     * @brief MQTT QoS when publishing from the Shadow Client @b to the Shadow Service.
     * @note The Shadow services always publishes to the Shadow Client with QoS 1. */
    MQTTQoS_t xQoS;
} ShadowOperationParams_t;

/**
 * @brief Function signature of a callback function registered for /update/documents.
 *
 * @param in: Custom user data.
 * @param pcThingName The Thing Name of the updated Shadow.
 * @param pcUpdateDocument The update document, a JSON string.
 * @param ulDocumentLength The length of the update document.
 * @param xBuffer The MQTT buffer containing @p pcUpdateDocument. This buffer
 * must eventually be returned by calling #SHADOW_ReturnMQTTBuffer if taken.
 *
 * @return
 * - pdTRUE to take ownership of the MQTT buffer containing pcUpdateDocument
 * - pdFALSE to leave pcUpdateDocument with the MQTT client. The MQTT client
 *   may overwrite pcUpdateDocument.
 *
 * @note Callback functions are called from the MQTT task.
 * @warning
 * - <b> Do not make any blocking calls (including #SHADOW_Update, #SHADOW_Get, or
 * #SHADOW_Delete) in a callback function! </b>
 * - The MQTT client does not guarantee that messages on /update/documents
 * will be received in the order they were published. If updates are being
 * performed frequently, it is possible to receive newer update documents
 * before older ones.
 */
typedef BaseType_t ( * ShadowUpdatedCallback_t )( void * pvUserData,
                                                  const char * const pcThingName,
                                                  const char * const pcUpdateDocument,
                                                  uint32_t ulDocumentLength,
                                                  MQTTBufferHandle_t xBuffer );

/**
 * @brief Function header of a callback function registered for /delete/accepted.
 *
 * @param in: Custom user data.
 * @param pcThingName The Name of the Thing whose Shadow was deleted.
 *
 * @note Callback functions are called from the MQTT task.
 * @warning <b> Do not make any blocking calls (including #SHADOW_Update, #SHADOW_Get, or
 * #SHADOW_Delete) in a callback function! </b>
 */
typedef void ( * ShadowDeletedCallback_t )( void * pvUserData,
                                            const char * const pcThingName );

/**
 * @brief Function header of a callback function registered for /update/delta.
 *
 * @param in: Custom user data.
 * @param pcThingName The Thing Name of the delta document.
 * @param pcDeltaDocument The delta document, a JSON string.
 * @param ulDocumentLength The length of the delta document.
 * @param xBuffer The MQTT buffer containing @p pcDeltaDocument. This buffer
 * must eventually be returned by calling #SHADOW_ReturnMQTTBuffer if taken.
 *
 * @return
 * - pdTRUE to take ownership of the MQTT buffer containing pcDeltaDocument
 * - pdFALSE to leave pcDeltaDocument with the MQTT client. The MQTT client
 *   may overwrite pcDeltaDocument.
 *
 * @note Callback functions are called from the MQTT task.
 * @warning
 * - <b> Do not make any blocking calls (including #SHADOW_Update, #SHADOW_Get, or
 * #SHADOW_Delete) in a callback function! </b>
 * - The MQTT client does not guarantee that messages on /update/delta
 * will be received in the order they were published. If updates are being
 * performed frequently, it is possible to receive newer delta documents
 * before older ones.
 */
typedef BaseType_t ( * ShadowDeltaCallback_t )( void * pvUserData,
                                                const char * const pcThingName,
                                                const char * const pcDeltaDocument,
                                                uint32_t ulDocumentLength,
                                                MQTTBufferHandle_t xBuffer );

/**
 * @brief Parameters to #SHADOW_RegisterCallbacks.
 */
typedef struct ShadowCallbackParams
{
    /** @brief Thing Name for which callbacks are registered. */
    const char * pcThingName;

    /**
     * @brief Called to notify users that a Thing Shadow has been updated.
     *
     * Callback for a message on /update/documents. Set to NULL for no callback.
     * @note This function @b will be called if the same Shadow Client that registered
     * the callback function updated the Thing Shadow. */
    ShadowUpdatedCallback_t xShadowUpdatedCallback;

    /**
     * @brief Called to notify users that @b another client has deleted the Thing Shadow.
     *
     * Callback for a message on /delete/accepted. Set to NULL for no callback.
     * @note This function <b>will not</b> be called if the same Shadow Client that
     * registered the callback function deleted the Thing Shadow. */
    ShadowDeletedCallback_t xShadowDeletedCallback;

    /**
     * @brief Called to notify users that a delta document has been generated.
     *
     * Callback for a message on /delete/accepted. Set to NULL for no callback.
     * @note This function @b will be called whenever a delta document is generated,
     * regardless of which client performed an update. */
    ShadowDeltaCallback_t xShadowDeltaCallback;
} ShadowCallbackParams_t;

/**
 * @brief Create a new Shadow Client.
 *
 * @param[out] pxShadowClientHandle Output parameter for the handle of the
 * newly-created Shadow Client. Only valid if the return code is #eShadowSuccess.
 * @param[in] pxShadowCreateParams Pointer to a #ShadowCreateParams struct.
 * @param[in] xTimeoutTicks Number of ticks this function may block before
 * timeout.
 *
 * @return #ShadowReturnCode. The value of output parameter pxShadowClientHandle
 * is valid only if the return code is #eShadowSuccess.
 *
 * @note
 * - If xTimeoutTicks is insufficient time for initialization, this function
 * will timeout and stop Shadow Client initialization. However, this function
 * may block for up to (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it
 * cleans up a partially-initialized Shadow Client.
 */
ShadowReturnCode_t SHADOW_ClientCreate( ShadowClientHandle_t * pxShadowClientHandle,
                                        const ShadowCreateParams_t * const pxShadowCreateParams );

/**
 * @brief Connect to the Shadow service.
 *
 * For a Shadow Client with a dedicated MQTT Client (#eDedicatedMQTTClient), calling
 * this function is the only way to connect to the Shadow service. For a Shadow
 * Client with a shared MQTT Client (#eSharedMQTTClient), calling this function is
 * equivalent to calling @c MQTT_AGENT_Connect with the corresponding shared
 * MQTT Client handle.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to connect.
 * @param[in] pxConnectParams Pointer to a @c TradstoneMQTTConnectParams_t struct.
 * Note: ClientHandle should be at the top of user data passed in pxConnectParams
 * @param[in] xTimeoutTicks Number of ticks this function may block before timeout.
 *
 * @return #ShadowReturnCode.
 */
ShadowReturnCode_t SHADOW_ClientConnect( ShadowClientHandle_t xShadowClientHandle,
                                         MQTTAgentConnectParams_t * const pxConnectParams,
                                         TickType_t xTimeoutTicks );

/**
 * @brief Disconnect from the Shadow service.
 *
 * For a Shadow Client with a dedicated MQTT Client (#eDedicatedMQTTClient), calling
 * this function is the only way to disconnect from the Shadow service. For a Shadow
 * Client with a shared MQTT Client (#eSharedMQTTClient), calling this function is
 * equivalent to calling @c MQTT_AGENT_Disconnect with the corresponding shared
 * MQTT Client handle.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to disconnect.
 *
 * @return Unless #shadowCLEANUP_TIME_MS is insufficient to disconnect a Shadow
 * Client, this function always returns #eShadowSuccess.
 */
ShadowReturnCode_t SHADOW_ClientDisconnect( ShadowClientHandle_t xShadowClientHandle );

/**
 * @brief Free resources used by a Shadow Client.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to be deleted.
 *
 * @return #ShadowReturnCode.
 *
 * @warning Do not call while another operation is in progress on the Shadow Client.
 * A Shadow Client must be re-initialized after this function completes if it is
 * to be used again.
 */
ShadowReturnCode_t SHADOW_ClientDelete( ShadowClientHandle_t xShadowClientHandle );

/**
 * @brief Update a Thing Shadow.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to use for update.
 * @param[in] pxUpdateParams A pointer to a #ShadowOperationParams struct.
 * @param[in] xTimeoutTicks Number of ticks this function may block before timeout.
 *
 * @return #ShadowReturnCode.
 *
 * @note
 * - If xTimeoutTicks is insufficient time for the update, this function will
 * timeout and stop the update. However, this function may block for up to
 * (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
 * - A timeout does not always mean that the update failed. The Shadow Service
 * may still accept an update after this function times out. However, the user
 * will not be notified if acceptance occurs after a timeout. The user may
 * intentionally set a short timeout if the result of the update isn't relevant,
 * but the timeout must still be long enough for the update to be published.
 */
ShadowReturnCode_t SHADOW_Update( ShadowClientHandle_t xShadowClientHandle,
                                  ShadowOperationParams_t * const pxUpdateParams,
                                  TickType_t xTimeoutTicks );

/**
 * @brief Get a Thing Shadow from the cloud.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to use for get.
 * @param pxGetParams A pointer to a #ShadowOperationParams struct. This is used
 * as both an input and output parameter.
 * @param[in] xTimeoutTicks Number of ticks this function may block before timeout.
 *
 * @return #ShadowReturnCode.
 *
 * @note
 * - If xTimeoutTicks is insufficient time for the get, this function will
 * timeout and stop the get. However, this function may block for up to
 * (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
 * - Documents received from the cloud after a timeout are ignored.
 * - A call to #SHADOW_ReturnMQTTBuffer should follow a call to #SHADOW_Get to
 *   return the MQTT Buffer taken by #SHADOW_Get. #ShadowOperationParams_t.xBuffer
 *   should be passed as @p xBufferHandle.
 */
ShadowReturnCode_t SHADOW_Get( ShadowClientHandle_t xShadowClientHandle,
                               ShadowOperationParams_t * const pxGetParams,
                               TickType_t xTimeoutTicks );

/**
 * @brief Delete a Thing Shadow in the cloud.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to use for delete.
 * @param[in] pxDeleteParams A pointer to a #ShadowOperationParams struct.
 * @param[in] xTimeoutTicks Number of ticks this function may block before timeout.
 *
 * @return #ShadowReturnCode.
 *
 * @note
 * - If xTimeoutTicks is insufficient time for the delete, this function will
 * timeout and stop the delete. However, this function may block for up to
 * (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
 * - A timeout does not always mean that the delete failed. The Shadow Service
 * may still accept the delete after this function times out. However, the user
 * will not be notified if acceptance occurs after a timeout. The user may
 * intentionally set a short timeout if the result of the delete isn't relevant,
 * but the timeout must still be long enough for the delete to be published.
 */
ShadowReturnCode_t SHADOW_Delete( ShadowClientHandle_t xShadowClientHandle,
                                  ShadowOperationParams_t * const pxDeleteParams,
                                  TickType_t xTimeoutTicks );

/**
 * @brief Register callback functions.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client to use for registering callbacks.
 * @param[in] pxCallbackParams A pointer to a #ShadowCallbackParams struct.
 * @param[in] xTimeoutTicks Number of ticks this function may block before timeout.
 *
 * @return
 * - #eShadowSuccess if all callbacks registered successfully.
 * - #eShadowFailure if the Shadow Client failed to subscribe to at least one
 *   callback topic and did not time out.
 * - #eShadowTimeout if the Shadow Client timed out when subscribing to at least
 *   one callback topic.
 *
 * @note
 * - This function will register as many callbacks as it can before xTimeoutTicks
 * elapses.
 * - Callbacks are registered in the order Updated, Deleted, Delta.
 * - If a callback fails to register, this function will print a debug message if
 * #shadowENABLE_DEBUG_LOGS is @c 1 and attempt to register the next callback.
 */
ShadowReturnCode_t SHADOW_RegisterCallbacks( ShadowClientHandle_t xShadowClientHandle,
                                             ShadowCallbackParams_t * const pxCallbackParams,
                                             TickType_t xTimeoutTicks );

/**
 * @brief Return an MQTT Buffer to the MQTT client.
 *
 * For a Shadow Client with a dedicated MQTT Client (#eDedicatedMQTTClient), calling
 * this function is the only way to return an MQTT Buffer. For a Shadow Client with
 * a shared MQTT Client (#eSharedMQTTClient), calling this function is equivalent
 * to calling @c MQTT_AGENT_ReturnBuffer with the corresponding shared MQTT
 * Client handle.
 *
 * @param[in] xShadowClientHandle Handle of Shadow Client for MQTT Buffer return.
 * @param[in] xBufferHandle Handle of MQTT Buffer to return.
 *
 * @return #ShadowReturnCode.
 *
 * @note
 * - This function should be called after every #SHADOW_Get call to return the
 *   MQTT buffer taken by #SHADOW_Get. Otherwise, the MQTT client will run out
 *   of buffers after repeated calls to #SHADOW_Get.
 * - This function should also be called to return buffers taken in callback
 *   functions #ShadowUpdatedCallback_t and #ShadowDeltaCallback_t.
 */
ShadowReturnCode_t SHADOW_ReturnMQTTBuffer( ShadowClientHandle_t xShadowClientHandle,
                                            MQTTBufferHandle_t xBufferHandle );

#endif /* _AWS_SHADOW_H_ */