TinyCBOR

https://intel.github.io/tinycbor/current/
Admin
TinyCBOR is a small CBOR encoder and decoder library, optimized for very fast operation with a very...
Tokens:24,912
Snippets:239
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize and encode an integer with CborEncoder

Source: https://intel.github.io/tinycbor/current/a00046.html

Demonstrates the basic setup of a CborEncoder and the encoding of a single integer value.

```C
uint8_t buf[16];
CborEncoder encoder;
cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
cbor_encode_int(&encoder, some_value);
```

--------------------------------

### Extracting an integer with error checking

Source: https://intel.github.io/tinycbor/current/a00047.html

Performs the same extraction as the basic example but includes validation for parsing errors and type checking.

```c
int extract_int(const uint8_t *buffer, size_t len)
{
CborParser parser;
CborValue value;
int result;
if (cbor_parser_init(buffer, len, 0, &parser, &value) != CborNoError)
return 0;
if (!cbor_value_is_integer(&value) ||
cbor_value_get_int(&value, &result) != CborNoError)
return 0;
return result;
}
```

--------------------------------

### String Operations

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for checking string types, getting lengths, and copying or duplicating string data.

```c
405 CBOR_INLINE_API bool cbor_value_is_byte_string(const CborValue *value)
406 { return value->type == CborByteStringType; }
407 CBOR_INLINE_API bool cbor_value_is_text_string(const CborValue *value)
408 { return value->type == CborTextStringType; }
409
410 CBOR_INLINE_API CborError cbor_value_get_string_length(const CborValue *value, size_t *length)
411 {
412 assert(cbor_value_is_byte_string(value) || cbor_value_is_text_string(value));
413 if (!cbor_value_is_length_known(value))
414 return CborErrorUnknownLength;
415 uint64_t v = _cbor_value_extract_int64_helper(value);
416 *length = (size_t)v;
417 if (*length != v)
418 return CborErrorDataTooLarge;
419 return CborNoError;
420 }
421
422 CBOR_PRIVATE_API CborError _cbor_value_copy_string(const CborValue *value, void *buffer,
423 size_t *buflen, CborValue *next);
424 CBOR_PRIVATE_API CborError _cbor_value_dup_string(const CborValue *value, void **buffer,
425 size_t *buflen, CborValue *next);
426
427 CBOR_API CborError cbor_value_calculate_string_length(const CborValue *value, size_t *length);
428
429 CBOR_INLINE_API CborError cbor_value_copy_text_string(const CborValue *value, char *buffer,
430 size_t *buflen, CborValue *next)
431 {
432 assert(cbor_value_is_text_string(value));
433 return _cbor_value_copy_string(value, buffer, buflen, next);
434 }
435 CBOR_INLINE_API CborError cbor_value_copy_byte_string(const CborValue *value, uint8_t *buffer,
436 size_t *buflen, CborValue *next)
437 {
438 assert(cbor_value_is_byte_string(value));
439 return _cbor_value_copy_string(value, buffer, buflen, next);
440 }
441
442 CBOR_INLINE_API CborError cbor_value_dup_text_string(const CborValue *value, char **buffer,
443 size_t *buflen, CborValue *next)
444 {
445 assert(cbor_value_is_text_string(value));
446 return _cbor_value_dup_string(value, (void **)buffer, buflen, next);
447 }
448 CBOR_INLINE_API CborError cbor_value_dup_byte_string(const CborValue *value, uint8_t **buffer,
449 size_t *buflen, CborValue *next)
450 {
451 assert(cbor_value_is_byte_string(value));
452 return _cbor_value_dup_string(value, (void **)buffer, buflen, next);
453 }
454
455 CBOR_API CborError cbor_value_text_string_equals(const CborValue *value, const char *string, bool *result);
```

--------------------------------

### Get buffer size

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Returns the total size of the buffer after encoding.

```c
size_t cbor_encoder_get_buffer_size(const CborEncoder *encoder, const uint8_t *buffer)
```

--------------------------------

### Include standard headers for TinyCBOR

Source: https://intel.github.io/tinycbor/current/a00005.html

Standard C headers and the TinyCBOR version header required for library functionality.

```c
#include <assert.h>
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <stdio.h>
#include "tinycbor-version.h"
#include <stdbool.h>
```

--------------------------------

### Create a CBOR map with CborEncoder

Source: https://intel.github.io/tinycbor/current/a00046.html

Shows how to nest a map within an encoder, add key-value pairs, and close the container.

```C
uint8_t buf[16];
CborEncoder encoder, mapEncoder;
cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
cbor_encoder_create_map(&encoder, &mapEncoder, 1);
cbor_encode_text_stringz(&mapEncoder, "foo");
cbor_encode_boolean(&mapEncoder, some_value);
cbor_encoder_close_container(&encoder, &mapEncoder);
```

--------------------------------

### Initialize encoder

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Initializes a CborEncoder structure with a buffer and size.

```c
CBOR_API void cbor_encoder_init(CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)
```

--------------------------------

### cbor_encoder_init

Source: https://intel.github.io/tinycbor/current/a00005.html

Initializes a CborEncoder structure by pointing it to a buffer.

```APIDOC
## cbor_encoder_init

### Description
Initializes a CborEncoder structure `encoder` by pointing it to buffer `buffer` of size `size`.

### Signature
`void cbor_encoder_init (CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)`
```

--------------------------------

### cbor_parser_init

Source: https://intel.github.io/tinycbor/current/a00005.html

Initializes the CBOR parser for a given buffer.

```APIDOC
## cbor_parser_init

### Description
Initializes the CBOR parser for parsing `size` bytes beginning at `buffer`.

### Signature
`CborError cbor_parser_init (const uint8_t *buffer, size_t size, int flags, CborParser *parser, CborValue *it)`
```

--------------------------------

### Extracting an integer from a CBOR stream

Source: https://intel.github.io/tinycbor/current/a00047.html

Demonstrates basic initialization and extraction of an integer from a CBOR buffer without error checking.

```c
int extract_int(const uint8_t *buffer, size_t len)
{
CborParser parser;
CborValue value;
int result;
cbor_parser_init(buffer, len, 0, &parser, &value);
cbor_value_get_int(&value, &result);
return result;
}
```

--------------------------------

### Include cbor.h header

Source: https://intel.github.io/tinycbor/current/a00017.html

Required header inclusion for accessing TinyCBOR functionality.

```c
#include "cbor.h"
```

--------------------------------

### Convert to pretty format

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Converts a CBOR value to its textual representation and writes it to a file.

```c
CBOR_API CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value)
```

--------------------------------

### TinyCBOR Header Definitions

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Core definitions for the TinyCBOR library, including versioning, API macros, and data type enumerations.

```c
/****************************************************************************
**
** Copyright (C) 2017 Intel Corporation
**
** 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 CBOR_H
#define CBOR_H

#ifndef assert
#include <assert.h>
#endif
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <stdio.h>

#include "tinycbor-version.h"

#define TINYCBOR_VERSION ((TINYCBOR_VERSION_MAJOR << 16) | (TINYCBOR_VERSION_MINOR << 8) | TINYCBOR_VERSION_PATCH)

#ifdef __cplusplus
extern "C" {
#else
#include <stdbool.h>
#endif

#ifndef SIZE_MAX
/* Some systems fail to define SIZE_MAX in <stdint.h>, even though C99 requires it...
* Conversion from signed to unsigned is defined in 6.3.1.3 (Signed and unsigned integers) p2,
* which says: "the value is converted by repeatedly adding or subtracting one more than the
* maximum value that can be represented in the new type until the value is in the range of the
* new type."
* So -1 gets converted to size_t by adding SIZE_MAX + 1, which results in SIZE_MAX.
*/
# define SIZE_MAX ((size_t)-1)
#endif

#ifndef CBOR_API
# define CBOR_API
#endif
#ifndef CBOR_PRIVATE_API
# define CBOR_PRIVATE_API
#endif
#ifndef CBOR_INLINE_API
# if defined(__cplusplus)
# define CBOR_INLINE inline
# define CBOR_INLINE_API inline
# else
# define CBOR_INLINE_API static CBOR_INLINE
# if defined(_MSC_VER)
# define CBOR_INLINE __inline
# elif defined(__GNUC__)
# define CBOR_INLINE __inline__
# elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
# define CBOR_INLINE inline
# else
# define CBOR_INLINE
# endif
# endif
#endif

typedef enum CborType {
CborIntegerType = 0x00,
CborByteStringType = 0x40,
CborTextStringType = 0x60,
CborArrayType = 0x80,
CborMapType = 0xa0,
CborTagType = 0xc0,
CborSimpleType = 0xe0,
CborBooleanType = 0xf5,
CborNullType = 0xf6,
CborUndefinedType = 0xf7,
CborHalfFloatType = 0xf9,
CborFloatType = 0xfa,
CborDoubleType = 0xfb,

CborInvalidType = 0xff /* equivalent to the break byte, so it will never be used */
} CborType;

typedef uint64_t CborTag;
typedef enum CborKnownTags {
CborDateTimeStringTag = 0,
CborUnixTime_tTag = 1,
CborPositiveBignumTag = 2,
CborNegativeBignumTag = 3,
CborDecimalTag = 4,
CborBigfloatTag = 5,
CborCOSE_Encrypt0Tag = 16,
CborCOSE_Mac0Tag = 17,
CborCOSE_Sign1Tag = 18,
CborExpectedBase64urlTag = 21,
CborExpectedBase64Tag = 22,
CborExpectedBase16Tag = 23,
CborEncodedCborTag = 24,
CborUrlTag = 32,
CborBase64urlTag = 33,
CborBase64Tag = 34,
CborRegularExpressionTag = 35,
CborMimeMessageTag = 36,
CborCOSE_EncryptTag = 96,
CborCOSE_MacTag = 97,
CborCOSE_SignTag = 98,
CborSignatureTag = 55799
} CborKnownTags;

/* #define the constants so we can check with #ifdef */
#define CborDateTimeStringTag CborDateTimeStringTag
#define CborUnixTime_tTag CborUnixTime_tTag
#define CborPositiveBignumTag CborPositiveBignumTag
#define CborNegativeBignumTag CborNegativeBignumTag
#define CborDecimalTag CborDecimalTag
#define CborBigfloatTag CborBigfloatTag
#define CborCOSE_Encrypt0Tag CborCOSE_Encrypt0Tag
#define CborCOSE_Mac0Tag CborCOSE_Mac0Tag
```

--------------------------------

### Define TinyCBOR Version Macros

Source: https://intel.github.io/tinycbor/current/a00041_source.html

These macros define the current version of the TinyCBOR library.

```c
#define TINYCBOR_VERSION_MAJOR 0
#define TINYCBOR_VERSION_MINOR 5
#define TINYCBOR_VERSION_PATCH 2
```

--------------------------------

### Pretty Printing API

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Utilities for converting CBOR values into human-readable formats, including stream-based and file-based output.

```c
enum CborPrettyFlags {
CborPrettyNumericEncodingIndicators = 0x01,
CborPrettyTextualEncodingIndicators = 0,
CborPrettyIndicateIndeterminateLength = 0x02,
CborPrettyIndicateIndetermineLength = CborPrettyIndicateIndeterminateLength,
CborPrettyIndicateOverlongNumbers = 0x04,
CborPrettyShowStringFragments = 0x100,
CborPrettyMergeStringFragments = 0,
CborPrettyDefaultFlags = CborPrettyIndicateIndeterminateLength
};
typedef CborError (*CborStreamFunction)(void *token, const char *fmt, ...)
#ifdef __GNUC__
__attribute__((__format__(printf, 2, 3)))
#endif
;
CBOR_API CborError cbor_value_to_pretty_stream(CborStreamFunction streamFunction, void *token, CborValue *value, int flags);
#if !defined(__STDC_HOSTED__) || __STDC_HOSTED__-0 == 1
CBOR_API CborError cbor_value_to_pretty_advance_flags(FILE *out, CborValue *value, int flags);
CBOR_API CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value);
CBOR_INLINE_API CborError cbor_value_to_pretty(FILE *out, const CborValue *value)
{
CborValue copy = *value;
return cbor_value_to_pretty_advance_flags(out, &copy, CborPrettyDefaultFlags);
}
#endif
```

--------------------------------

### Retrieve 64-bit integer checked

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Retrieves a CBOR integer with bounds checking.

```c
CBOR_API CborError cbor_value_get_int64_checked(const CborValue *value, int64_t *result)
```

--------------------------------

### Define CBOR to JSON conversion header

Source: https://intel.github.io/tinycbor/current/a00017_source.html

Header file defining the CborToJsonFlags enumeration and functions for converting CBOR values to JSON.

```c
/****************************************************************************
**
** Copyright (C) 2015 Intel Corporation
**
** 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 CBORJSON_H
#define CBORJSON_H

#include "cbor.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Conversion to JSON */
enum CborToJsonFlags
{
CborConvertAddMetadata = 1,
CborConvertTagsToObjects = 2,
CborConvertIgnoreTags = 0,

CborConvertObeyByteStringTags = 0,
CborConvertByteStringsToBase64Url = 4,

CborConvertRequireMapStringKeys = 0,
CborConvertStringifyMapKeys = 8,

CborConvertDefaultFlags = 0
};

CBOR_API CborError cbor_value_to_json_advance(FILE *out, CborValue *value, int flags);
CBOR_INLINE_API CborError cbor_value_to_json(FILE *out, const CborValue *value, int flags)
{
CborValue copy = *value;
return cbor_value_to_json_advance(out, &copy, flags);
}

#ifdef __cplusplus
}
#endif

#endif /* CBORJSON_H */
```

--------------------------------

### Define CBOR Tags

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Macros defining standard CBOR tags used in the library.

```c
#define CborCOSE_Sign1Tag CborCOSE_Sign1Tag
#define CborExpectedBase64urlTag CborExpectedBase64urlTag
#define CborExpectedBase64Tag CborExpectedBase64Tag
#define CborExpectedBase16Tag CborExpectedBase16Tag
#define CborEncodedCborTag CborEncodedCborTag
#define CborUrlTag CborUrlTag
#define CborBase64urlTag CborBase64urlTag
#define CborBase64Tag CborBase64Tag
#define CborRegularExpressionTag CborRegularExpressionTag
#define CborMimeMessageTag CborMimeMessageTag
#define CborCOSE_EncryptTag CborCOSE_EncryptTag
#define CborCOSE_MacTag CborCOSE_MacTag
#define CborCOSE_SignTag CborCOSE_SignTag
#define CborSignatureTag CborSignatureTag
```

--------------------------------

### cbor_value_enter_container()

Source: https://intel.github.io/tinycbor/current/a00047.html

Creates a CborValue iterator pointing to the first element of the container represented by the input iterator.

```APIDOC
## cbor_value_enter_container()

### Description
Creates a CborValue iterator pointing to the first element of the container represented by _it_ and saves it in _recursed_. The _it_ container object must be preserved and passed to cbor_value_leave_container() to continue iteration after the container.

### Signature
CborError cbor_value_enter_container(const CborValue *it, CborValue *recursed)

### Parameters
- **it** (const CborValue *) - Required - The iterator pointing to the container.
- **recursed** (CborValue *) - Required - Pointer to store the new iterator for the container's contents.
```

--------------------------------

### CborType

Source: https://intel.github.io/tinycbor/current/globals_enum.html

Enumeration of CBOR data types.

```APIDOC
## CborType

### Description
An enumeration type defined in `cbor.h` that identifies the underlying CBOR data type of a given element.
```

--------------------------------

### CborKnownTags

Source: https://intel.github.io/tinycbor/current/globals_enum.html

Enumeration of standard CBOR tags.

```APIDOC
## CborKnownTags

### Description
An enumeration type defined in `cbor.h` representing standard CBOR tags as defined in the CBOR specification.
```

--------------------------------

### Parser Structures and Flags

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Definitions for parser iterator flags and the core CborParser and CborValue structures.

```c
enum CborParserIteratorFlags
{
CborIteratorFlag_IntegerValueTooLarge = 0x01,
CborIteratorFlag_NegativeInteger = 0x02,
CborIteratorFlag_IteratingStringChunks = 0x02,
CborIteratorFlag_UnknownLength = 0x04,
CborIteratorFlag_ContainerIsMap = 0x20
};
```

```c
struct CborParser
{
const uint8_t *end;
int flags;
};
typedef struct CborParser CborParser;
```

```c
struct CborValue
{
const CborParser *parser;
const uint8_t *ptr;
uint32_t remaining;
uint16_t extra;
uint8_t type;
uint8_t flags;
};
typedef struct CborValue CborValue;
```

--------------------------------

### Duplicate text string

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Allocates memory and copies the string pointed to by the CBOR value.

```c
CborError cbor_value_dup_text_string(const CborValue *value, char **buffer, size_t *buflen, CborValue *next)
```

--------------------------------

### Parser Value Navigation

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for checking parser state, advancing the iterator, and entering or leaving containers.

```c
CBOR_INLINE_API bool cbor_value_at_end(const CborValue *it)
{ return it->remaining == 0; }
```

```c
CBOR_INLINE_API const uint8_t *cbor_value_get_next_byte(const CborValue *it)
{ return it->ptr; }
```

```c
CBOR_INLINE_API bool cbor_value_is_container(const CborValue *it)
{ return it->type == CborArrayType || it->type == CborMapType; }
```

--------------------------------

### Retrieve 64-bit integer

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Retrieves a CBOR integer value and stores it in the provided result pointer.

```c
CborError cbor_value_get_int64(const CborValue *value, int64_t *result)
```

--------------------------------

### Map and Array Operations

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for identifying containers and retrieving their lengths or finding map values.

```c
458 CBOR_INLINE_API bool cbor_value_is_array(const CborValue *value)
459 { return value->type == CborArrayType; }
460 CBOR_INLINE_API bool cbor_value_is_map(const CborValue *value)
461 { return value->type == CborMapType; }
462
463 CBOR_INLINE_API CborError cbor_value_get_array_length(const CborValue *value, size_t *length)
464 {
465 assert(cbor_value_is_array(value));
466 if (!cbor_value_is_length_known(value))
467 return CborErrorUnknownLength;
468 uint64_t v = _cbor_value_extract_int64_helper(value);
469 *length = (size_t)v;
470 if (*length != v)
471 return CborErrorDataTooLarge;
472 return CborNoError;
473 }
474
475 CBOR_INLINE_API CborError cbor_value_get_map_length(const CborValue *value, size_t *length)
476 {
477 assert(cbor_value_is_map(value));
478 if (!cbor_value_is_length_known(value))
479 return CborErrorUnknownLength;
480 uint64_t v = _cbor_value_extract_int64_helper(value);
481 *length = (size_t)v;
482 if (*length != v)
483 return CborErrorDataTooLarge;
484 return CborNoError;
485 }
486
487 CBOR_API CborError cbor_value_map_find_value(const CborValue *map, const char *string, CborValue *element);
```

--------------------------------

### cbor_encoder_create_map()

Source: https://intel.github.io/tinycbor/current/a00046.html

Creates a CBOR map in the provided encoder stream and initializes a map encoder for adding items.

```APIDOC
## cbor_encoder_create_map()

### Description
Creates a CBOR map in the CBOR stream provided by encoder and initializes mapEncoder so that items can be added to the map. The map must be terminated by calling cbor_encoder_close_container() or cbor_encoder_close_container_checked().

### Parameters
- **encoder** (CborEncoder*) - The encoder to use.
- **mapEncoder** (CborEncoder*) - The map encoder to initialize.
- **length** (size_t) - The number of key-value pairs to be inserted, or CborIndefiniteLength if unknown.

### Returns
- **CborError** - Returns CborErrorDataTooLarge if length exceeds SIZE_MAX/2.
```

--------------------------------

### Copy text string

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Copies a string from a CBOR value into a provided buffer.

```c
CborError cbor_value_copy_text_string(const CborValue *value, char *buffer, size_t *buflen, CborValue *next)
```

--------------------------------

### Compare text string

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Compares a CBOR value with a string and stores the boolean result.

```c
CBOR_API CborError cbor_value_text_string_equals(const CborValue *value, const char *string, bool *result)
```

--------------------------------

### cbor_value_copy_byte_string()

Source: https://intel.github.io/tinycbor/current/a00047.html

Copies the byte string pointed by _value_ into the buffer provided at _buffer_ of _buflen_ bytes.

```APIDOC
## cbor_value_copy_byte_string()

### Description
Copies the byte string pointed by _value_ into the buffer provided at _buffer_ of _buflen_ bytes. If the buffer is too small, it returns CborErrorOutOfMemory.

### Signature
CborError cbor_value_copy_byte_string(const CborValue *value, uint8_t *buffer, size_t *buflen, CborValue *next)

### Parameters
- **value** (const CborValue *) - The source CborValue iterator.
- **buffer** (uint8_t *) - Pointer to the destination buffer.
- **buflen** (size_t *) - Pointer to the size of the buffer; updated with the number of bytes copied on success.
- **next** (CborValue *) - Pointer to be updated to the next item after the string.

### Returns
- **CborError** - Returns CborErrorNone on success, or CborErrorOutOfMemory if the buffer is too small.
```

--------------------------------

### TinyCBOR Functional Modules

Source: https://intel.github.io/tinycbor/current/modules.html

The TinyCBOR library is organized into several functional modules that users can utilize for CBOR data processing.

```APIDOC
## TinyCBOR Functional Modules

### Global constants
Constants used by all TinyCBOR function groups.

### Encoding to CBOR
Group of functions used to encode data to CBOR.

### Parsing CBOR streams
Group of functions used to parse CBOR streams.

### Converting CBOR to text
Group of functions used to convert CBOR to text form.

### Converting CBOR to JSON
Group of functions used to convert CBOR to JSON.
```

--------------------------------

### CborEncoder Structure and API

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Structure definition for the encoder and the associated API functions for encoding various data types.

```c
struct CborEncoder
{
union {
uint8_t *ptr;
ptrdiff_t bytes_needed;
} data;
const uint8_t *end;
size_t remaining;
int flags;
};
typedef struct CborEncoder CborEncoder;

static const size_t CborIndefiniteLength = SIZE_MAX;

CBOR_API void cbor_encoder_init(CborEncoder *encoder, uint8_t *buffer, size_t size, int flags);
CBOR_API CborError cbor_encode_uint(CborEncoder *encoder, uint64_t value);
CBOR_API CborError cbor_encode_int(CborEncoder *encoder, int64_t value);
CBOR_API CborError cbor_encode_negative_int(CborEncoder *encoder, uint64_t absolute_value);
CBOR_API CborError cbor_encode_simple_value(CborEncoder *encoder, uint8_t value);
CBOR_API CborError cbor_encode_tag(CborEncoder *encoder, CborTag tag);
CBOR_API CborError cbor_encode_text_string(CborEncoder *encoder, const char *string, size_t length);
CBOR_INLINE_API CborError cbor_encode_text_stringz(CborEncoder *encoder, const char *string)
{ return cbor_encode_text_string(encoder, string, strlen(string)); }
CBOR_API CborError cbor_encode_byte_string(CborEncoder *encoder, const uint8_t *string, size_t length);
CBOR_API CborError cbor_encode_floating_point(CborEncoder *encoder, CborType fpType, const void *value);

CBOR_INLINE_API CborError cbor_encode_boolean(CborEncoder *encoder, bool value)
{ return cbor_encode_simple_value(encoder, (int)value - 1 + (CborBooleanType & 0x1f)); }
CBOR_INLINE_API CborError cbor_encode_null(CborEncoder *encoder)
{ return cbor_encode_simple_value(encoder, CborNullType & 0x1f); }
CBOR_INLINE_API CborError cbor_encode_undefined(CborEncoder *encoder)
{ return cbor_encode_simple_value(encoder, CborUndefinedType & 0x1f); }

CBOR_INLINE_API CborError cbor_encode_half_float(CborEncoder *encoder, const void *value)
{ return cbor_encode_floating_point(encoder, CborHalfFloatType, value); }
CBOR_INLINE_API CborError cbor_encode_float(CborEncoder *encoder, float value)
{ return cbor_encode_floating_point(encoder, CborFloatType, &value); }
CBOR_INLINE_API CborError cbor_encode_double(CborEncoder *encoder, double value)
{ return cbor_encode_floating_point(encoder, CborDoubleType, &value); }

CBOR_API CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEncoder, size_t length);
CBOR_API CborError cbor_encoder_create_map(CborEncoder *encoder, CborEncoder *mapEncoder, size_t length);
CBOR_API CborError cbor_encoder_close_container(CborEncoder *encoder, const CborEncoder *containerEncoder);
```

--------------------------------

### cbor_encoder_create_array

Source: https://intel.github.io/tinycbor/current/a00046.html

Initializes a new CBOR array within the encoder stream.

```APIDOC
## CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEncoder, size_t length)

### Description
Creates a CBOR array in the CBOR stream provided by encoder and initializes arrayEncoder for adding items. The array must be closed using cbor_encoder_close_container.

### Parameters
- **encoder** (CborEncoder*) - The encoder stream.
- **arrayEncoder** (CborEncoder*) - The encoder instance to initialize for the array.
- **length** (size_t) - The number of items to be inserted, or CborIndefiniteLength if unknown.
```

--------------------------------

### Encoder Buffer Management

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for retrieving buffer pointers, sizes, and tracking extra bytes required during encoding.

```c
CBOR_INLINE_API uint8_t *_cbor_encoder_get_buffer_pointer(const CborEncoder *encoder)
{
return encoder->data.ptr;
}
```

```c
CBOR_INLINE_API size_t cbor_encoder_get_buffer_size(const CborEncoder *encoder, const uint8_t *buffer)
{
return (size_t)(encoder->data.ptr - buffer);
}
```

```c
CBOR_INLINE_API size_t cbor_encoder_get_extra_bytes_needed(const CborEncoder *encoder)
{
return encoder->end ? 0 : (size_t)encoder->data.bytes_needed;
}
```

--------------------------------

### Value Type Checking and Extraction

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Helper functions to validate types and extract values like booleans, simple types, and integers.

```c
CBOR_INLINE_API bool cbor_value_is_valid(const CborValue *value)
{ return value && value->type != CborInvalidType; }
CBOR_INLINE_API CborType cbor_value_get_type(const CborValue *value)
{ return (CborType)value->type; }
```

```c
CBOR_INLINE_API bool cbor_value_is_null(const CborValue *value)
{ return value->type == CborNullType; }
CBOR_INLINE_API bool cbor_value_is_undefined(const CborValue *value)
{ return value->type == CborUndefinedType; }
```

```c
CBOR_INLINE_API bool cbor_value_is_boolean(const CborValue *value)
{ return value->type == CborBooleanType; }
CBOR_INLINE_API CborError cbor_value_get_boolean(const CborValue *value, bool *result)
{
assert(cbor_value_is_boolean(value));
*result = !!value->extra;
return CborNoError;
}
```

```c
CBOR_INLINE_API bool cbor_value_is_simple_type(const CborValue *value)
{ return value->type == CborSimpleType; }
CBOR_INLINE_API CborError cbor_value_get_simple_type(const CborValue *value, uint8_t *result)
{
assert(cbor_value_is_simple_type(value));
*result = (uint8_t)value->extra;
return CborNoError;
}
```

```c
CBOR_INLINE_API bool cbor_value_is_integer(const CborValue *value)
{ return value->type == CborIntegerType; }
CBOR_INLINE_API bool cbor_value_is_unsigned_integer(const CborValue *value)
{ return cbor_value_is_integer(value) && (value->flags & CborIteratorFlag_NegativeInteger) == 0; }
CBOR_INLINE_API bool cbor_value_is_negative_integer(const CborValue *value)
{ return cbor_value_is_integer(value) && (value->flags & CborIteratorFlag_NegativeInteger); }
```

```c
CBOR_INLINE_API CborError cbor_value_get_raw_integer(const CborValue *value, uint64_t *result)
{
assert(cbor_value_is_integer(value));
*result = _cbor_value_extract_int64_helper(value);
return CborNoError;
}
```

```c
CBOR_INLINE_API CborError cbor_value_get_uint64(const CborValue *value, uint64_t *result)
{
assert(cbor_value_is_unsigned_integer(value));
*result = _cbor_value_extract_int64_helper(value);
return CborNoError;
}
```

```c
CBOR_INLINE_API CborError cbor_value_get_int64(const CborValue *value, int64_t *result)
{
assert(cbor_value_is_integer(value));
*result = (int64_t) _cbor_value_extract_int64_helper(value);
if (value->flags & CborIteratorFlag_NegativeInteger)
*result = -*result - 1;
return CborNoError;
}
```

--------------------------------

### CborPrettyFlags

Source: https://intel.github.io/tinycbor/current/globals_enum.html

Flags for controlling the output of the pretty-printing functionality.

```APIDOC
## CborPrettyFlags

### Description
An enumeration type defined in `cbor.h` used to configure the behavior of the pretty-printing functions.
```

--------------------------------

### Tag Operations

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for identifying and retrieving tag values.

```c
394 CBOR_INLINE_API bool cbor_value_is_tag(const CborValue *value)
395 { return value->type == CborTagType; }
396 CBOR_INLINE_API CborError cbor_value_get_tag(const CborValue *value, CborTag *result)
397 {
398 assert(cbor_value_is_tag(value));
399 *result = _cbor_value_extract_int64_helper(value);
400 return CborNoError;
401 }
402 CBOR_API CborError cbor_value_skip_tag(CborValue *it);
```

--------------------------------

### cbor_value_to_pretty_advance_flags()

Source: https://intel.github.io/tinycbor/current/a00005.html

Converts the current CBOR type to its textual representation with configurable flags, writing to the out stream and advancing the value pointer.

```APIDOC
## cbor_value_to_pretty_advance_flags()

### Description
Converts the current CBOR type pointed to by _value_ to its textual representation and writes it to the _out_ stream, using _flags_ to control the output format. If successful, it advances _value_ to the next element.

### Signature
`CborError cbor_value_to_pretty_advance_flags(FILE *out, CborValue *value, int flags)`

### Parameters
- **out** (FILE *) - The output stream.
- **value** (CborValue *) - Pointer to the current CBOR value.
- **flags** (int) - Flags to control the textual representation (see CborPrettyFlags).

### Returns
- **CborError** - Returns an error code if parsing fails, otherwise returns success.
```

--------------------------------

### cbor_encoder_create_array

Source: https://intel.github.io/tinycbor/current/a00046.html

Creates a CBOR array container.

```APIDOC
## CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEncoder, size_t length)

### Description
Creates a CBOR array in the stream and initializes a new encoder for the array items.

### Parameters
- **encoder** (CborEncoder*) - The parent encoder.
- **arrayEncoder** (CborEncoder*) - The encoder to be initialized for the array.
- **length** (size_t) - The number of items in the array.
```

--------------------------------

### Retrieve raw integer

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Retrieves a CBOR integer value as a raw 64-bit unsigned integer.

```c
CborError cbor_value_get_raw_integer(const CborValue *value, uint64_t *result)
```

--------------------------------

### Floating Point Operations

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions for identifying and retrieving floating point values.

```c
490 CBOR_INLINE_API bool cbor_value_is_half_float(const CborValue *value)
491 { return value->type == CborHalfFloatType; }
492 CBOR_API CborError cbor_value_get_half_float(const CborValue *value, void *result);
493
494 CBOR_INLINE_API bool cbor_value_is_float(const CborValue *value)
495 { return value->type == CborFloatType; }
496 CBOR_INLINE_API CborError cbor_value_get_float(const CborValue *value, float *result)
497 {
498 assert(cbor_value_is_float(value));
```

--------------------------------

### cbor_value_copy_text_string()

Source: https://intel.github.io/tinycbor/current/a00047.html

Copies the string pointed to by value into the buffer provided at buffer of buflen bytes.

```APIDOC
## CborError cbor_value_copy_text_string(const CborValue *value, char *buffer, size_t *buflen, CborValue *next)

### Description
Copies the string pointed to by _value_ into the buffer provided at _buffer_ of _buflen_ bytes. If _buffer_ is a NULL pointer, this function will not copy anything and will only update the _next_ value.

### Parameters
- **value** (const CborValue *) - The iterator pointing to the text string.
- **buffer** (char *) - Pointer to the destination buffer.
- **buflen** (size_t *) - Pointer to the size of the buffer; updated with the number of bytes copied on success.
- **next** (CborValue *) - Pointer to be updated to the next item after this string.

### Return Value
- **CborError** - Returns CborErrorOutOfMemory if the buffer is too small, otherwise returns success status.
```

--------------------------------

### Retrieve simple type

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Retrieves the CBOR Simple Type value.

```c
CborError cbor_value_get_simple_type(const CborValue *value, uint8_t *result)
```

--------------------------------

### cbor_encoder_create_array / cbor_encoder_create_map

Source: https://intel.github.io/tinycbor/current/a00046.html

Creates a nested CborEncoder for an array or map.

```APIDOC
## cbor_encoder_create_array / cbor_encoder_create_map

### Description
Creates a nested CborEncoder object for encoding an array or a map within the current encoder.

### Signature
CborError cbor_encoder_create_array(const CborEncoder *parent, CborEncoder *arrayEncoder, size_t length)
CborError cbor_encoder_create_map(const CborEncoder *parent, CborEncoder *mapEncoder, size_t length)

### Parameters
- **parent** (const CborEncoder*) - The parent encoder.
- **arrayEncoder/mapEncoder** (CborEncoder*) - Pointer to the new nested encoder.
- **length** (size_t) - The number of elements in the container.
```

--------------------------------

### CborToJsonFlags

Source: https://intel.github.io/tinycbor/current/globals_enum.html

Flags for controlling the conversion of CBOR data to JSON format.

```APIDOC
## CborToJsonFlags

### Description
An enumeration type defined in `cborjson.h` used to specify options during the conversion of CBOR data into a JSON representation.
```

--------------------------------

### Length and Type Checks

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Utility functions to check if a value has a known length or is a specific type.

```c
390 CBOR_INLINE_API bool cbor_value_is_length_known(const CborValue *value)
391 { return (value->flags & CborIteratorFlag_UnknownLength) == 0; }
```

--------------------------------

### Type Checking and Value Retrieval Functions

Source: https://intel.github.io/tinycbor/current/a00047.html

The TinyCBOR library provides a set of functions to inspect the type of a CborValue and retrieve its underlying data.

```APIDOC
## Type Checking Functions

- `bool cbor_value_is_simple_type(const CborValue *value)`: Returns true if the iterator points to a CBOR Simple Type.
- `bool cbor_value_is_integer(const CborValue *value)`: Returns true if the iterator points to a CBOR integer type.
- `bool cbor_value_is_unsigned_integer(const CborValue *value)`: Returns true if the iterator points to a CBOR unsigned integer.
- `bool cbor_value_is_negative_integer(const CborValue *value)`: Returns true if the iterator points to a CBOR negative integer.
- `bool cbor_value_is_text_string(const CborValue *value)`: Returns true if the iterator points to a CBOR text string.
- `bool cbor_value_is_byte_string(const CborValue *value)`: Returns true if the iterator points to a CBOR byte string.
- `bool cbor_value_is_array(const CborValue *value)`: Returns true if the iterator points to a CBOR array.
- `bool cbor_value_is_map(const CborValue *value)`: Returns true if the iterator points to a CBOR map.
- `bool cbor_value_is_float(const CborValue *value)`: Returns true if the iterator points to a 32-bit float.
- `bool cbor_value_is_double(const CborValue *value)`: Returns true if the iterator points to a 64-bit double.
- `bool cbor_value_is_half_float(const CborValue *value)`: Returns true if the iterator points to a 16-bit float.

## Value Retrieval Functions

- `CborError cbor_value_get_simple_type(const CborValue *value, uint8_t *result)`
- `CborError cbor_value_get_int(const CborValue *value, int *result)`
- `CborError cbor_value_get_int64(const CborValue *value, int64_t *result)`
- `CborError cbor_value_get_uint64(const CborValue *value, uint64_t *result)`
- `CborError cbor_value_get_raw_integer(const CborValue *value, uint64_t *result)`
- `CborError cbor_value_get_string_length(const CborValue *value, size_t *length)`
- `CborError cbor_value_copy_text_string(const CborValue *value, char *buffer, size_t *buflen, CborValue *next)`
- `CborError cbor_value_copy_byte_string(const CborValue *value, uint8_t *buffer, size_t *buflen, CborValue *next)`
- `CborError cbor_value_get_array_length(const CborValue *value, size_t *length)`
- `CborError cbor_value_get_map_length(const CborValue *value, size_t *length)`
- `CborError cbor_value_get_float(const CborValue *value, float *result)`
```

--------------------------------

### cbor_value_to_pretty_advance()

Source: https://intel.github.io/tinycbor/current/a00005.html

Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream, then advances the value pointer.

```APIDOC
## cbor_value_to_pretty_advance()

### Description
Converts the current CBOR type pointed to by _value_ to its textual representation and writes it to the _out_ stream. If successful, it advances _value_ to the next element.

### Signature
`CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value)`

### Parameters
- **out** (FILE *) - The output stream.
- **value** (CborValue *) - Pointer to the current CBOR value.

### Returns
- **CborError** - Returns an error code if parsing fails, otherwise returns success.
```

--------------------------------

### Retrieve integer checked

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Retrieves a CBOR integer with bounds checking.

```c
CBOR_API CborError cbor_value_get_int_checked(const CborValue *value, int *result)
```

--------------------------------

### cbor_value_to_pretty()

Source: https://intel.github.io/tinycbor/current/a00005.html

Converts the current CBOR type to its textual representation and writes it to the provided stream.

```APIDOC
## cbor_value_to_pretty()

### Description
Converts the current CBOR type pointed to by _value_ to its textual representation and writes it to the _out_ stream.

### Signature
CborError cbor_value_to_pretty(FILE *out, const CborValue *value)

### Parameters
- **out** (FILE *) - The output stream.
- **value** (const CborValue *) - The CBOR value to convert.

### Returns
- **CborError** - Returns an error code if the conversion fails.
```

--------------------------------

### cbor_value_enter_container

Source: https://intel.github.io/tinycbor/current/a00005.html

Enters a container (array or map) to iterate its contents.

```APIDOC
## CborError cbor_value_enter_container(const CborValue *it, CborValue *recursed)

### Description
Creates a CborValue iterator pointing to the first element of the container represented by the current iterator and saves it in the recursed parameter.
```

--------------------------------

### Double Value Handling

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Functions to check for and retrieve double-precision floating-point values from a CborValue.

```c
CBOR_INLINE_API bool cbor_value_is_double(const CborValue *value)
{ return value->type == CborDoubleType; }
CBOR_INLINE_API CborError cbor_value_get_double(const CborValue *value, double *result)
{
assert(cbor_value_is_double(value));
assert(value->flags & CborIteratorFlag_IntegerValueTooLarge);
uint64_t data = _cbor_value_decode_int64_internal(value);
memcpy(result, &data, sizeof(*result));
return CborNoError;
}
```

--------------------------------

### cbor_value_to_pretty_stream()

Source: https://intel.github.io/tinycbor/current/a00048.html

Converts the current CBOR value to its textual representation and writes it to a stream using a provided callback function.

```APIDOC
## cbor_value_to_pretty_stream()

### Description
Converts the current CBOR type pointed by value to its textual representation and writes it to the stream by calling the streamFunction. If no error occurred, this function advances value to the next element.

### Signature
CborError cbor_value_to_pretty_stream(CborStreamFunction streamFunction, void *token, CborValue *value, int flags)

### Parameters
- **streamFunction** (CborStreamFunction) - The callback function used to write the output.
- **token** (void *) - A user-defined token passed to the streamFunction.
- **value** (CborValue *) - Pointer to the CBOR value to convert.
- **flags** (int) - Bitwise flags from CborPrettyFlags to control the output format.

### Returns
- **CborError** - Returns an error code if an error occurs, otherwise returns success.
```

--------------------------------

### cbor_value_to_pretty_advance

Source: https://intel.github.io/tinycbor/current/a00005_source.html

Converts a CBOR value to a human-readable format and writes it to a file stream.

```APIDOC
## CborError cbor_value_to_pretty_advance(FILE *out, CborValue *value)

### Description
Writes a human-readable representation of the CBOR value to the specified file stream and advances the iterator.

### Parameters
- **out** (FILE *) - Required - The file stream to write to.
- **value** (CborValue *) - Required - The CBOR value to convert.
```
Tokens:
Raw