aws_iot_jobs_internal.h

Go to the documentation of this file.

/*
 * AWS IoT Jobs V1.0.0
 * Copyright (C) 2019 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_JOBS_INTERNAL_H_
#define AWS_IOT_JOBS_INTERNAL_H_

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

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

/* Jobs include. */
#include "aws_iot_jobs.h"

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

#if AWS_IOT_JOBS_ENABLE_ASSERTS == 1
    #ifndef AwsIotJobs_Assert
        #ifdef Iot_DefaultAssert
            #define AwsIotJobs_Assert( expression )    Iot_DefaultAssert( expression )
        #else
            #error "Asserts are enabled for Jobs, but AwsIotJobs_Assert is not defined"
        #endif
    #endif
#else
    #define AwsIotJobs_Assert( expression )
#endif

/* Configure logs for Jobs functions. */
#ifdef AWS_IOT_LOG_LEVEL_JOBS
    #define LIBRARY_LOG_LEVEL        AWS_IOT_LOG_LEVEL_JOBS
#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    ( "Jobs" )
#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 * AwsIotJobs_MallocOperation( size_t size );

    void AwsIotJobs_FreeOperation( void * ptr );

    #define AwsIotJobs_MallocString    Iot_MallocMessageBuffer

    #define AwsIotJobs_FreeString      Iot_FreeMessageBuffer

    void * AwsIotJobs_MallocSubscription( size_t size );

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

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

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

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

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

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

#ifndef AWS_IOT_JOBS_DEFAULT_MQTT_TIMEOUT_MS
    #define AWS_IOT_JOBS_DEFAULT_MQTT_TIMEOUT_MS    ( 5000 )
#endif
#ifndef AWS_IOT_JOBS_NOTIFY_CALLBACKS
    #define AWS_IOT_JOBS_NOTIFY_CALLBACKS           ( 1 )
#endif

#define JOBS_OPERATION_COUNT                          ( 4 )

#define JOBS_CALLBACK_COUNT                           ( 2 )

#define JOBS_GET_PENDING_OPERATION_STRING             "/jobs/get"

#define JOBS_GET_PENDING_OPERATION_STRING_LENGTH      ( ( uint16_t ) ( sizeof( JOBS_GET_PENDING_OPERATION_STRING ) - 1 ) )

#define JOBS_START_NEXT_OPERATION_STRING              "/jobs/start-next"

#define JOBS_START_NEXT_OPERATION_STRING_LENGTH       ( ( uint16_t ) ( sizeof( JOBS_START_NEXT_OPERATION_STRING ) - 1 ) )

#define JOBS_DESCRIBE_OPERATION_STRING                "/get"

#define JOBS_DESCRIBE_OPERATION_STRING_LENGTH         ( ( uint16_t ) ( sizeof( JOBS_DESCRIBE_OPERATION_STRING ) - 1 ) )

#define JOBS_UPDATE_OPERATION_STRING                  "/update"

#define JOBS_UPDATE_OPERATION_STRING_LENGTH           ( ( uint16_t ) ( sizeof( JOBS_UPDATE_OPERATION_STRING ) - 1 ) )

#define JOBS_NOTIFY_PENDING_CALLBACK_STRING           "/jobs/notify"

#define JOBS_NOTIFY_PENDING_CALLBACK_STRING_LENGTH    ( ( uint16_t ) ( sizeof( JOBS_NOTIFY_PENDING_CALLBACK_STRING ) - 1 ) )

#define JOBS_NOTIFY_NEXT_CALLBACK_STRING              "/jobs/notify-next"

#define JOBS_NOTIFY_NEXT_CALLBACK_STRING_LENGTH       ( ( uint16_t ) ( sizeof( JOBS_NOTIFY_NEXT_CALLBACK_STRING ) - 1 ) )

#define JOBS_MAX_ID_LENGTH                            ( 64 )

#define JOBS_MAX_TIMEOUT                              ( 10080 )

#define JOBS_MAX_STATUS_DETAILS_LENGTH                ( 32768 )

#define JOBS_LONGEST_SUFFIX_LENGTH                    ( JOBS_MAX_ID_LENGTH + JOBS_UPDATE_OPERATION_STRING_LENGTH + 6 )

/*------------------------ Jobs internal data types -------------------------*/

typedef enum _jobsOperationType
{
    /* Jobs operations. */
    JOBS_GET_PENDING = 0, 
    JOBS_START_NEXT = 1,  
    JOBS_DESCRIBE = 2,    
    JOBS_UPDATE = 3,      
    /* Jobs callbacks. */
    SET_NOTIFY_PENDING_CALLBACK = 4, 
    SET_NOTIFY_NEXT_CALLBACK = 5     
} _jobsOperationType_t;

typedef enum _jobsCallbackType
{
    NOTIFY_PENDING_CALLBACK = 0, 
    NOTIFY_NEXT_CALLBACK = 1     
} _jobsCallbackType_t;

typedef union _jsonRequestContents
{
    const AwsIotJobsUpdateInfo_t * pUpdateInfo; 
    struct
    {
        int32_t executionNumber; 
        bool includeJobDocument; 
    } describe;                  
} _jsonRequestContents_t;

typedef struct _jobsSubscription
{
    IotLink_t link;                                      
    int32_t operationReferences[ JOBS_OPERATION_COUNT ]; 
    int32_t callbackReferences;                          
    AwsIotJobsCallbackInfo_t callbacks[ JOBS_CALLBACK_COUNT ][ AWS_IOT_JOBS_NOTIFY_CALLBACKS ];

    char * pTopicBuffer;

    size_t thingNameLength; 
    char pThingName[];      
} _jobsSubscription_t;

typedef struct _jobsOperation
{
    IotLink_t link; 
    /* Basic operation information. */
    _jobsOperationType_t type;           
    uint32_t flags;                      
    AwsIotJobsError_t status;            
    IotMqttConnection_t mqttConnection;  
    _jobsSubscription_t * pSubscription; 
    /* Jobs request information. */
    const char * pJobsRequest; 
    size_t jobsRequestLength;  
    const char * pClientToken; 
    size_t clientTokenLength;  
    /* Jobs response information. */
    const char * pJobsResponse; 
    size_t jobsResponseLength;  
    void * ( *mallocResponse )( size_t );

    /* How to notify of an operation's completion. */
    union
    {
        IotSemaphore_t waitSemaphore;      
        AwsIotJobsCallbackInfo_t callback; 
    } notify;                              
    size_t jobIdLength;                    
    char pJobId[];                         
} _jobsOperation_t;

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

/* Declarations of variables for internal Jobs files. */
extern uint32_t _AwsIotJobsMqttTimeoutMs;
extern IotListDouble_t _AwsIotJobsPendingOperations;
extern IotListDouble_t _AwsIotJobsSubscriptions;
extern IotMutex_t _AwsIotJobsPendingOperationsMutex;
extern IotMutex_t _AwsIotJobsSubscriptionsMutex;

/*------------------------ Jobs operation functions -------------------------*/

AwsIotJobsError_t _AwsIotJobs_CreateOperation( _jobsOperationType_t type,
                                               const AwsIotJobsRequestInfo_t * pRequestInfo,
                                               const _jsonRequestContents_t * pRequestContents,
                                               uint32_t flags,
                                               const AwsIotJobsCallbackInfo_t * pCallbackInfo,
                                               _jobsOperation_t ** pNewOperation );

void _AwsIotJobs_DestroyOperation( void * pData );

AwsIotJobsError_t _AwsIotJobs_GenerateJobsTopic( _jobsOperationType_t type,
                                                 const AwsIotJobsRequestInfo_t * pRequestInfo,
                                                 char ** pTopicBuffer,
                                                 uint16_t * pOperationTopicLength );

AwsIotJobsError_t _AwsIotJobs_ProcessOperation( const AwsIotJobsRequestInfo_t * pRequestInfo,
                                                _jobsOperation_t * pOperation );

/*----------------------- Jobs subscription functions -----------------------*/

_jobsSubscription_t * _AwsIotJobs_FindSubscription( const char * pThingName,
                                                    size_t thingNameLength,
                                                    bool createIfNotFound );

void _AwsIotJobs_RemoveSubscription( _jobsSubscription_t * pSubscription,
                                     _jobsSubscription_t ** pRemovedSubscription );

void _AwsIotJobs_DestroySubscription( void * pData );

AwsIotJobsError_t _AwsIotJobs_IncrementReferences( _jobsOperation_t * pOperation,
                                                   char * pTopicBuffer,
                                                   uint16_t operationTopicLength,
                                                   AwsIotMqttCallbackFunction_t callback );

void _AwsIotJobs_DecrementReferences( _jobsOperation_t * pOperation,
                                      char * pTopicBuffer,
                                      _jobsSubscription_t ** pRemovedSubscription );

/*------------------------ Jobs serializer functions ------------------------*/

AwsIotJobsError_t _AwsIotJobs_GenerateJsonRequest( _jobsOperationType_t type,
                                                   const AwsIotJobsRequestInfo_t * pRequestInfo,
                                                   const _jsonRequestContents_t * pRequestContents,
                                                   _jobsOperation_t * pOperation );

void _AwsIotJobs_ParseResponse( AwsIotStatus_t status,
                                const char * pResponse,
                                size_t responseLength,
                                _jobsOperation_t * pOperation );

#endif /* ifndef AWS_IOT_JOBS_INTERNAL_H_ */