output/html/ota__private_8h_source.html

/*

 * AWS IoT Over-the-air Update v2.0.0 (Release Candidate)

 * 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 OTA_PRIVATE_H

#define OTA_PRIVATE_H


/* Standard includes. */

/* For FILE type in OtaFileContext_t.*/

#include <stdio.h>

#include <stdint.h>

#include <stdbool.h>


/* OTA_DO_NOT_USE_CUSTOM_CONFIG allows building the OTA library

 * without a custom config. If a custom config is provided, the

 * OTA_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */

#ifndef OTA_DO_NOT_USE_CUSTOM_CONFIG

    #include "ota_config.h"

#endif


/* Include config defaults header to get default values of configs not defined

 * in ota_config.h file. */

#include "ota_config_defaults.h"


/* General constants. */

#define LOG2_BITS_PER_BYTE           3U

#define BITS_PER_BYTE                ( ( uint32_t ) 1U << LOG2_BITS_PER_BYTE )

#define OTA_FILE_BLOCK_SIZE          ( ( uint32_t ) 1U << otaconfigLOG2_FILE_BLOCK_SIZE )

#define OTA_MAX_FILES                1U

#define OTA_MAX_BLOCK_BITMAP_SIZE    128U

#define OTA_REQUEST_MSG_MAX_SIZE     ( 3U * OTA_MAX_BLOCK_BITMAP_SIZE )

#define OTA_REQUEST_URL_MAX_SIZE     ( 1500 )

#define OTA_ERASED_BLOCKS_VAL        0xffU

#ifdef configOTA_NUM_MSG_Q_ENTRIES

    #define OTA_NUM_MSG_Q_ENTRIES    configOTA_NUM_MSG_Q_ENTRIES

#else

    #define OTA_NUM_MSG_Q_ENTRIES    20U

#endif


/* Job document parser constants. */

#define OTA_MAX_JSON_TOKENS         64U

#define OTA_MAX_JSON_STR_LEN        256U

#define OTA_DOC_MODEL_MAX_PARAMS    32U

#define OTA_JOB_PARAM_REQUIRED      true

#define OTA_JOB_PARAM_OPTIONAL      false

#define OTA_DONT_STORE_PARAM        0xffff

#define OTA_STORE_NESTED_JSON       0x1fffU

#define OTA_DATA_BLOCK_SIZE         ( ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) + OTA_REQUEST_URL_MAX_SIZE + 30 )

/* OTA Agent task event flags. */

#define OTA_EVT_MASK_JOB_MSG_READY     0x00000001UL

#define OTA_EVT_MASK_DATA_MSG_READY    0x00000002UL

#define OTA_EVT_MASK_SHUTDOWN          0x00000004UL

#define OTA_EVT_MASK_REQ_TIMEOUT       0x00000008UL

#define OTA_EVT_MASK_USER_ABORT        0x000000016UL

#define OTA_EVT_MASK_ALL_EVENTS        ( OTA_EVT_MASK_JOB_MSG_READY | OTA_EVT_MASK_DATA_MSG_READY | OTA_EVT_MASK_SHUTDOWN | OTA_EVT_MASK_REQ_TIMEOUT | OTA_EVT_MASK_USER_ABORT )

#define OTA_NUM_JOB_PARAMS     ( 21 )


#define OTA_JOB_ID_MAX_SIZE    ( 72UL + 1UL )


#define kOTA_MaxSignatureSize           256 /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */


#define OTA_JSON_SEPARATOR              "."

#define OTA_JSON_CLIENT_TOKEN_KEY       "clientToken"

#define OTA_JSON_TIMESTAMP_KEY          "timestamp"

#define OTA_JSON_EXECUTION_KEY          "execution"

#define OTA_JSON_JOB_ID_KEY             OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobId"

#define OTA_JSON_STATUS_DETAILS_KEY     OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "statusDetails"

#define OTA_JSON_SELF_TEST_KEY          OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "self_test"

#define OTA_JSON_UPDATED_BY_KEY         OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "updatedBy"

#define OTA_JSON_UPDATED_BY_KEY_ONLY    "updatedBy"

#define OTA_JSON_SELF_TEST_KEY_ONLY     "self_test"

#define OTA_JSON_JOB_DOC_KEY            OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobDocument"

#define OTA_JSON_OTA_UNIT_KEY           OTA_JSON_JOB_DOC_KEY OTA_JSON_SEPARATOR "afr_ota"

#define OTA_JSON_PROTOCOLS_KEY          OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "protocols"

#define OTA_JSON_FILE_GROUP_KEY         OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "files"

#define OTA_JSON_STREAM_NAME_KEY        OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "streamname"

#define OTA_JSON_FILE_PATH_KEY          "filepath"

#define OTA_JSON_FILE_SIZE_KEY          "filesize"

#define OTA_JSON_FILE_ID_KEY            "fileid"

#define OTA_JSON_FILE_ATTRIBUTE_KEY     "attr"

#define OTA_JSON_FILE_CERT_NAME_KEY     "certfile"

#define OTA_JSON_UPDATE_DATA_URL_KEY    "update_data_url"

#define OTA_JSON_AUTH_SCHEME_KEY        "auth_scheme"

#define OTA_JSON_FILETYPE_KEY           "fileType"

typedef enum

{

    IngestResultFileComplete = -1,

    IngestResultSigCheckFail = -2,

    IngestResultFileCloseFail = -3,

    IngestResultNullContext = -4,

    IngestResultBadFileHandle = -5,

    IngestResultUnexpectedBlock = -6,

    IngestResultBlockOutOfRange = -7,

    IngestResultBadData = -8,

    IngestResultWriteBlockFailed = -9,

    IngestResultNullResultPointer = -10,

    IngestResultNoDecodeMemory = -11,

    IngestResultUninitialized = -127,

    IngestResultAccepted_Continue = 0,

    IngestResultDuplicate_Continue = 1

} IngestResult_t;


typedef enum

{

    DocParseErrUnknown = -1,

    DocParseErrNone = 0,

    DocParseErrOutOfMemory,

    DocParseErrUserBufferInsuffcient,

    DocParseErrFieldTypeMismatch,

    DocParseErrBase64Decode,

    DocParseErrInvalidNumChar,

    DocParseErrDuplicatesNotAllowed,

    DocParseErrMalformedDoc,

    DocParseErr_InvalidJSONBuffer,

    DocParseErrNullModelPointer,

    DocParseErrNullBodyPointer,

    DocParseErrNullDocPointer,

    DocParseErrTooManyParams,

    DocParseErrParamKeyNotInModel,

    DocParseErrInvalidModelParamType,

    DocParseErrInvalidToken

} DocParseErr_t;


typedef enum

{

    ModelParamTypeStringCopy,

    ModelParamTypeStringInDoc, /* Only use this type if you can process before freeing the document memory. */

    ModelParamTypeObject,

    ModelParamTypeArray,

    ModelParamTypeUInt32,

    ModelParamTypeSigBase64,

    ModelParamTypeIdent,

    ModelParamTypeArrayCopy

} ModelParamType_t;


typedef enum

{

    JobStatusInProgress = 0,

    JobStatusFailed,

    JobStatusSucceeded,

    JobStatusRejected,      /* Not possible today using the "get next job" feature. FUTURE! */

    JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */

    NumJobStatusMappings

} OtaJobStatus_t;


typedef enum

{

    JobReasonReceiving = 0,  /* Update progress status. */

    JobReasonSigCheckPassed, /* Set status details to Self Test Ready. */

    JobReasonSelfTestActive, /* Set status details to Self Test Active. */

    JobReasonAccepted,       /* Set job state to Succeeded. */

    JobReasonRejected,       /* Set job state to Failed. */

    JobReasonAborted,        /* Set job state to Failed. */

    NumJobReasons

} OtaJobReason_t;


typedef struct

{

    const char * pSrcKey;

    const bool required;

    uint16_t pDestOffset;

    uint16_t pDestSizeOffset;

    const ModelParamType_t modelParamType;

} JsonDocParam_t;


typedef struct

{

    void * contextBase;

    uint32_t contextSize;

    const JsonDocParam_t * pBodyDef;

    uint16_t numModelParams;

    uint32_t paramsReceivedBitmap;

    uint32_t paramsRequiredBitmap;

} JsonDocModel_t;


typedef struct OtaAgentStatistics

{

    uint32_t otaPacketsReceived;

    uint32_t otaPacketsQueued;

    uint32_t otaPacketsProcessed;

    uint32_t otaPacketsDropped;

} OtaAgentStatistics_t;


typedef enum OtaImageState

{

    OtaImageStateUnknown = 0,

    OtaImageStateTesting = 1,

    OtaImageStateAccepted = 2,

    OtaImageStateRejected = 3,

    OtaImageStateAborted = 4,

    OtaLastImageState = OtaImageStateAborted

} OtaImageState_t;


typedef enum OtaPalImageState

{

    OtaPalImageStateUnknown = 0,

    OtaPalImageStatePendingCommit,

    OtaPalImageStateValid,

    OtaPalImageStateInvalid

} OtaPalImageState_t;


typedef enum OtaEvent

{

    OtaAgentEventStart = 0,

    OtaAgentEventStartSelfTest,

    OtaAgentEventRequestJobDocument,

    OtaAgentEventReceivedJobDocument,

    OtaAgentEventCreateFile,

    OtaAgentEventRequestFileBlock,

    OtaAgentEventReceivedFileBlock,

    OtaAgentEventRequestTimer,

    OtaAgentEventCloseFile,

    OtaAgentEventSuspend,

    OtaAgentEventResume,

    OtaAgentEventUserAbort,

    OtaAgentEventShutdown,

    OtaAgentEventMax

} OtaEvent_t;


typedef struct

{

    uint16_t size;

    uint8_t data[ kOTA_MaxSignatureSize ];

} Sig256_t;


typedef struct OtaFileContext

{

    uint8_t * pFilePath;

    uint16_t filePathMaxSize;

    #if defined( WIN32 ) || defined( __linux__ )

        FILE * pFile;

    #else

        uint8_t * pFile;

    #endif

    uint32_t fileSize;

    uint32_t blocksRemaining;

    uint32_t fileAttributes;

    uint32_t serverFileID;

    uint8_t * pJobName;

    uint16_t jobNameMaxSize;

    uint8_t * pStreamName;

    uint16_t streamNameMaxSize;

    uint8_t * pRxBlockBitmap;

    uint16_t blockBitmapMaxSize;

    uint8_t * pCertFilepath;

    uint16_t certFilePathMaxSize;

    uint8_t * pUpdateUrlPath;

    uint16_t updateUrlMaxSize;

    uint8_t * pAuthScheme;

    uint16_t authSchemeMaxSize;

    uint32_t updaterVersion;

    bool isInSelfTest;

    uint8_t * pProtocols;

    uint16_t protocolMaxSize;

    uint8_t * pDecodeMem;

    uint32_t decodeMemMaxSize;

    uint32_t fileType;

    Sig256_t * pSignature;

} OtaFileContext_t;


typedef struct OtaEventData

{

    uint8_t data[ OTA_DATA_BLOCK_SIZE ];

    uint32_t dataLength;

    bool bufferUsed;

} OtaEventData_t;


typedef struct OtaEventMsg

{

    OtaEventData_t * pEventData;

    OtaEvent_t eventId;

} OtaEventMsg_t;


#endif /* ifndef OTA_PRIVATE_H */