qcbor_decode.h

Go to the documentation of this file.

/* ===========================================================================
 * Copyright (c) 2016-2018, The Linux Foundation.
 * Copyright (c) 2018-2025, Laurence Lundblade.
 * Copyright (c) 2021, Arm Limited.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 *       copyright notice, this list of conditions and the following
 *       disclaimer in the documentation and/or other materials provided
 *       with the distribution.
 *     * Neither the name of The Linux Foundation nor the names of its
 *       contributors, nor the name "Laurence Lundblade" may be used to
 *       endorse or promote products derived from this software without
 *       specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ========================================================================= */
 
 
#ifndef qcbor_decode_h
#define qcbor_decode_h
 
 
#include "qcbor/qcbor_common.h"
#include "qcbor/qcbor_private.h"
#include <stdbool.h>
 
 
#ifdef __cplusplus
extern "C" {
#if 0
} /* Keep editor indention formatting happy */
#endif
#endif
 
 
typedef enum {
   QCBOR_DECODE_MODE_NORMAL = 0,
   QCBOR_DECODE_MODE_MAP_STRINGS_ONLY = 1,
   QCBOR_DECODE_MODE_MAP_AS_ARRAY = 2
   /* This is stored in uint8_t in places; never add values > 255 */
} QCBORDecodeMode;
 
#define QCBOR_MAX_DECODE_INPUT_SIZE (UINT32_MAX - 2)
 
#define QCBOR_MAX_TAGS_PER_ITEM QCBOR_MAX_TAGS_PER_ITEM1
 
 
 
/* Do not renumber these. Code depends on some of these values. */
#define QCBOR_TYPE_NONE           0
 
#define QCBOR_TYPE_ANY            1
 
#define QCBOR_TYPE_INT64          2
 
#define QCBOR_TYPE_UINT64         3
 
#define QCBOR_TYPE_ARRAY          4
 
#define QCBOR_TYPE_MAP            5
 
#define QCBOR_TYPE_BYTE_STRING    6
 
#define QCBOR_TYPE_TEXT_STRING    7
 
#define QCBOR_TYPE_POSBIGNUM      9
 
#define QCBOR_TYPE_NEGBIGNUM     10
 
#define QCBOR_TYPE_DATE_STRING   11
 
#define QCBOR_TYPE_DATE_EPOCH    12
 
#define QCBOR_TYPE_UKNOWN_SIMPLE 13
 
#define QCBOR_TYPE_DECIMAL_FRACTION            14
 
#define QCBOR_TYPE_DECIMAL_FRACTION_POS_BIGNUM 15
 
#define QCBOR_TYPE_DECIMAL_FRACTION_NEG_BIGNUM 16
 
#define QCBOR_TYPE_BIGFLOAT                    17
 
#define QCBOR_TYPE_BIGFLOAT_POS_BIGNUM         18
 
#define QCBOR_TYPE_BIGFLOAT_NEG_BIGNUM         19
 
#define QCBOR_TYPE_FALSE         20
 
#define QCBOR_TYPE_TRUE          21
 
#define QCBOR_TYPE_NULL          22
 
#define QCBOR_TYPE_UNDEF         23
 
#define QCBOR_TYPE_FLOAT         26
 
#define QCBOR_TYPE_DOUBLE        27
 
#define QCBOR_TYPE_BREAK         31 /* Used internally; never returned */
 
#define QCBOR_TYPE_MAP_AS_ARRAY  32
 
#define QBCOR_TYPE_WRAPPED_CBOR  36
 
#define QCBOR_TYPE_URI           44
 
#define QCBOR_TYPE_BASE64URL     45
 
#define QCBOR_TYPE_BASE64        46
 
#define QCBOR_TYPE_REGEX         47
 
#define QCBOR_TYPE_MIME          48
 
#define QCBOR_TYPE_UUID          49
 
#define QBCOR_TYPE_WRAPPED_CBOR_SEQUENCE  75
 
#define QCBOR_TYPE_BINARY_MIME   76
 
#define QCBOR_TYPE_DAYS_STRING   77
 
#define QCBOR_TYPE_DAYS_EPOCH    78
 
#define QCBOR_TYPE_TAG          254 /* Used internally; never returned */
 
#define QCBOR_TYPE_OPTTAG   QCBOR_TYPE_TAG /* Depricated. See QCBOR_TYPE_TAG */
 
 
 
#define QCBOR_LAST_UNMAPPED_TAG (CBOR_TAG_INVALID16 - QCBOR_NUM_MAPPED_TAGS - 1)
 
 
typedef struct  {
   int64_t nExponent;
   union {
      int64_t    nInt;
      UsefulBufC bigNum;
   } Mantissa;
} QCBORExpAndMantissa;
 
 
typedef struct _QCBORItem {
   uint8_t  uDataType;
 
   uint8_t  uLabelType;
 
   uint8_t  uNestingLevel;
 
   uint8_t  uNextNestLevel;
 
   uint8_t  uDataAlloc;
 
   uint8_t  uLabelAlloc;
 
   union {
      int64_t     int64;
      uint64_t    uint64;
      UsefulBufC  string;
      uint16_t    uCount;
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
      double      dfnum;
      float       fnum;
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
      struct {
         int64_t  nSeconds;
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
         double   fSecondsFraction;
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
      } epochDate;
 
      int64_t     epochDays;
      UsefulBufC  dateString;
      UsefulBufC  bigNum;
      uint8_t     uSimple;
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
      QCBORExpAndMantissa expAndMantissa;
#endif /* ! QCBOR_DISABLE_EXP_AND_MANTISSA */
      uint64_t    uTagV;  /* Used internally during decoding */
 
   } val;
 
   union {
      int64_t     int64;
#ifndef QCBOR_DISABLE_NON_INTEGER_LABELS
      uint64_t    uint64;
      UsefulBufC  string;
#endif /* ! QCBOR_DISABLE_NON_INTEGER_LABELS */
   } label;
 
#ifndef QCBOR_DISABLE_TAGS
   uint16_t uTags[QCBOR_MAX_TAGS_PER_ITEM];
#endif
 
} QCBORItem;
 
#define QCBOR_COUNT_INDICATES_INDEFINITE_LENGTH UINT16_MAX
 
 
 
 
typedef UsefulBuf (* QCBORStringAllocate)(void   *pAllocateCxt,
                                          void   *pOldMem,
                                          size_t  uNewSize);
 
 
#define QCBOR_DECODE_MIN_MEM_POOL_SIZE 8
 
 
 
 
typedef struct _QCBORDecodeContext QCBORDecodeContext;
 
 
void
QCBORDecode_Init(QCBORDecodeContext *pCtx, UsefulBufC EncodedCBOR, QCBORDecodeMode nMode);
 
 
QCBORError
QCBORDecode_SetMemPool(QCBORDecodeContext *pCtx,
                       UsefulBuf           MemPool,
                       bool                bAllStrings);
 
 
void
QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
                           QCBORStringAllocate pfAllocateFunction,
                           void               *pAllocateContext,
                           bool                bAllStrings);
 
 
void
QCBORDecode_VGetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
QCBORError
QCBORDecode_GetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
void
QCBORDecode_VGetNextConsume(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
void
QCBORDecode_VPeekNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
QCBORError
QCBORDecode_PeekNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
static uint32_t
QCBORDecode_Tell(QCBORDecodeContext *pCtx);
 
 
QCBORError
QCBORDecode_EndCheck(QCBORDecodeContext *pCtx);
 
 
uint64_t
QCBORDecode_GetNthTag(QCBORDecodeContext *pCtx, const QCBORItem *pItem, uint32_t uIndex);
 
 
uint64_t
QCBORDecode_GetNthTagOfLast(const QCBORDecodeContext *pCtx, uint32_t uIndex);
 
 
QCBORError
QCBORDecode_Finish(QCBORDecodeContext *pCtx);
 
 
QCBORError
QCBORDecode_PartialFinish(QCBORDecodeContext *pCtx, size_t *puConsumed);
 
 
static UsefulBufC
QCBORDecode_RetrieveUndecodedInput(QCBORDecodeContext *pCtx);
 
 
static QCBORError
QCBORDecode_GetError(QCBORDecodeContext *pCtx);
 
 
static QCBORError
QCBORDecode_GetAndResetError(QCBORDecodeContext *pCtx);
 
 
static bool
QCBORDecode_IsNotWellFormedError(QCBORError uErr);
 
 
static bool
QCBORDecode_IsUnrecoverableError(QCBORError uErr);
 
 
static void
QCBORDecode_SetError(QCBORDecodeContext *pCtx, QCBORError uError);
 
 
 
 
static inline int
QCBOR_Int64ToInt32(int64_t src, int32_t *dest)
{
   if(src > INT32_MAX || src < INT32_MIN) {
      return -1;
   } else {
      *dest = (int32_t) src;
   }
   return 0;
}
 
static inline int
QCBOR_Int64ToInt16(int64_t src, int16_t *dest)
{
   if(src > INT16_MAX || src < INT16_MIN) {
      return -1;
   } else {
      *dest = (int16_t) src;
   }
   return 0;
}
 
static inline int
QCBOR_Int64ToInt8(int64_t src, int8_t *dest)
{
   if(src > INT8_MAX || src < INT8_MIN) {
      return -1;
   } else {
      *dest = (int8_t) src;
   }
   return 0;
}
 
static inline int
QCBOR_Int64ToUInt32(int64_t src, uint32_t *dest)
{
   if(src > UINT32_MAX || src < 0) {
      return -1;
   } else {
      *dest = (uint32_t) src;
   }
   return 0;
}
 
#define QCBOR_Int64UToInt16 QCBOR_Int64ToUInt16
 
static inline int
QCBOR_Int64ToUInt16(int64_t src, uint16_t *dest)
{
   if(src > UINT16_MAX || src < 0) {
      return -1;
   } else {
      *dest = (uint16_t) src;
   }
   return 0;
}
 
static inline int
QCBOR_Int64ToUInt8(int64_t src, uint8_t *dest)
{
   if(src > UINT8_MAX || src < 0) {
      return -1;
   } else {
      *dest = (uint8_t) src;
   }
   return 0;
}
 
static inline int
QCBOR_Int64ToUInt64(int64_t src, uint64_t *dest)
{
   if(src < 0) {
      return -1;
   } else {
      *dest = (uint64_t) src;
   }
   return 0;
}
 
 
 
 
/* ========================================================================= *
 *    BEGINNING OF DEPRECATED FUNCTIONS                                      *
 *                                                                           *
 *    There is no plan to remove these in future versions.                   *
 *    They just have been replaced by something better.                      *
 * ========================================================================= */
 
typedef struct {
   uint8_t         uNumTags;
   const uint64_t *puTags;
} QCBORTagListIn;
 
 
typedef struct {
   uint8_t   uNumUsed;
   uint8_t   uNumAllocated;
   uint64_t *puTags;
} QCBORTagListOut;
 
 
void
QCBORDecode_SetCallerConfiguredTagList(QCBORDecodeContext   *pCtx,
                                       const QCBORTagListIn *pTagList);
 
 
bool
QCBORDecode_IsTagged(QCBORDecodeContext *pCtx,
                     const QCBORItem    *pItem,
                     uint64_t            uTag);
 
 
QCBORError
QCBORDecode_GetNextWithTags(QCBORDecodeContext *pCtx,
                            QCBORItem          *pDecodedItem,
                            QCBORTagListOut    *pTagList);
 
 
/* ========================================================================= *
 *    END OF DEPRECATED FUNCTIONS                                            *
 * ========================================================================= */
 
 
 
 
/* ========================================================================= *
 *    BEGINNING OF PRIVATE INLINE IMPLEMENTATION                             *
 * ========================================================================= */
 
static inline uint32_t
QCBORDecode_Tell(QCBORDecodeContext *pMe)
{
   if(pMe->uLastError) {
      return UINT32_MAX;
   }
 
   /* Cast is safe because decoder input size is restricted. */
   return (uint32_t)UsefulInputBuf_Tell(&(pMe->InBuf));
}
 
static inline UsefulBufC
QCBORDecode_RetrieveUndecodedInput(QCBORDecodeContext *pMe)
{
   return UsefulInputBuf_RetrieveUndecodedInput(&(pMe->InBuf));
}
 
static inline QCBORError
QCBORDecode_GetError(QCBORDecodeContext *pMe)
{
    return (QCBORError)pMe->uLastError;
}
 
static inline QCBORError
QCBORDecode_GetAndResetError(QCBORDecodeContext *pMe)
{
    const QCBORError uReturn = (QCBORError)pMe->uLastError;
    pMe->uLastError = QCBOR_SUCCESS;
    return uReturn;
}
 
static inline bool
QCBORDecode_IsNotWellFormedError(const QCBORError uErr)
{
   if(uErr >= QCBOR_START_OF_NOT_WELL_FORMED_ERRORS &&
      uErr <= QCBOR_END_OF_NOT_WELL_FORMED_ERRORS) {
      return true;
   } else {
      return false;
   }
}
 
static inline bool
QCBORDecode_IsUnrecoverableError(const QCBORError uErr)
{
   if(uErr >= QCBOR_START_OF_UNRECOVERABLE_DECODE_ERRORS &&
      uErr <= QCBOR_END_OF_UNRECOVERABLE_DECODE_ERRORS) {
      return true;
   } else {
      return false;
   }
}
 
 
static inline void
QCBORDecode_SetError(QCBORDecodeContext *pMe, QCBORError uError)
{
   pMe->uLastError = (uint8_t)uError;
}
 
/* ======================================================================== *
 *    END OF PRIVATE INLINE IMPLEMENTATION                                  *
 * ======================================================================== */
 
 
/* A few cross checks on size constants and special value lengths */
#if  QCBOR_MAP_OFFSET_CACHE_INVALID < QCBOR_MAX_DECODE_INPUT_SIZE
#error QCBOR_MAP_OFFSET_CACHE_INVALID is too large
#endif
 
#if QCBOR_NON_BOUNDED_OFFSET < QCBOR_MAX_DECODE_INPUT_SIZE
#error QCBOR_NON_BOUNDED_OFFSET is too large
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* qcbor_decode_h */