path: root/README.md

# libecbor

CBOR library with no dependencies, small memory footprint and code size, developed for both desktop and embedded applications.

## Compiling

Compiling the library:

```
cmake .
make
```

This will generate the following files:
* `lib/libecbor.so` - dynamic linking version
* `lib/libecbor.a` - static linking version
* `include/ecbor.h` - header file for library
* `ecbor-describe` - describe tool, loads CBOR contents from file and displays them

## Testing

Unit tests can be run by performing:

```
cd test/
./runtests.sh
```

## Installation

Installing can be performed with:

```
cmake . -DCMAKE_INSTALL_PREFIX=<install_prefix>
make
make install
```

If `<install_prefix>` is omitted, then the default install path is used (usually `/usr/local`).

## Guide

### Memory usage

`libecbor` guarantees that no memory other than the buffers provided by the caller is used; it has no dependency on any memory manager or standard library, other than the standard type definitions. While this can be sometimes cumbersome, it is a desired trait for memory-constrained devices.

Moreover, both encoding and decoding have an *absolute upper bound* on stack usage, regardless of the depth or size of the CBOR object. Actual numbers depend on the compiler and flags.

### Error handling

Most `libecbor` API calls return an error code. It is a good practice to check it consistently, especially when building for embedded targets where debugging may be more difficult.

Usually you would look for a return code of `ECBOR_OK`. The full error list can be found in the header file `include/ecbor.h` under the `ecbor_error_t` enum.

### Encoder

Each encoding operation must use an encode context (`ecbor_encode_context_t`), usually defined on the stack:

```c
ecbor_encode_context_t context;
```

The encoder must be initialized either in *normal* encoding mode

```c
uint8_t buffer[BUFFER_SIZE];
ecbor_error_t rc = ecbor_initialize_encode(&context, buffer, BUFFER_SIZE);
```

or in *streamed* mode

```c
uint8_t buffer[BUFFER_SIZE];
ecbor_error_t rc = ecbor_initialize_encode_streamed(&context, buffer, BUFFER_SIZE);
```

While in *normal* mode the user can encode a whole item tree at once (including children), it lacks support for encoding indefinite strings, maps and arrays, since it is assumed the item is pre-built and the size is already known.

If support for indefinite items is mandatory then the *streamed* mode can be used, but the user must encode the children manually. Please be attentive that the desired CBOR structure is followed in this case.

`buffer` is simply an output buffer of size `BUFFER_SIZE` where the encoder will place the resulting CBOR object.

Once the context has been initialized, items can be encoded with

```c
ecbor_error_t rc = ecbor_encode (&context, &item);
```

where `item` is of type `ecbor_item_t`. If the item is too large for the context output buffer, then `ECBOR_ERR_INVALID_END_OF_BUFFER` will be returned.

Simple items can be built by using one of the following APIs:

```c
ecbor_item_t item = ecbor_int (uint_value);
ecbor_item_t item = ecbor_uint (int_value);

ecbor_item_t item = ecbor_fp32 (float_value);
ecbor_item_t item = ecbor_fp64 (double_value);

ecbor_item_t item = ecbor_bool (bool_or_int_value);

ecbor_item_t item = ecbor_bstr (bin_buffer_ptr, BIN_BUFFER_SIZE);
ecbor_item_t item = ecbor_str (c_str_ptr, strlen(c_str_ptr));
ecbor_item_t item = ecbor_tag (&child_item, tag_int_value);

ecbor_item_t item = ecbor_null ();
ecbor_item_t item = ecbor_undefined ();
```

Arrays can be created with

```c
ecbor_error_t rc = ecbor_array (&arr, array_items, item_count);
```

where `arr` is the output `ecbor_item_t`, `array_items` is a `ecbor_item_t*` pointing to the children and `item_count` is the size of `array_items`.

Maps can be created with

```c
ecbor_error_t rc = ecbor_map (&map, keys, values, keyval_count);
```

where `map` is the output `ecbor_item_t`, `keys` and `values` are `ecbor_item_t*`, and `keyval_count` is the size of `keys` and `values`. Note that the *i*-th key-value pair is composed of `keys[i]` and `values[i]`.

If using *streamed* encoding mode, then only the placeholder (token) items must be built:

```c
ecbor_item_t item = ecbor_array_token (item_count);
ecbor_item_t item = ecbor_indefinite_array_token ();

ecbor_item_t item = ecbor_map_token (keyval_count);
ecbor_item_t item = ecbor_indefinite_map_token ();

ecbor_item_t item = ecbor_stop_code ();
```

but the user must subsequently encode the correct amount of child items (for definite-size arrays and maps) or the stop code (for indefinite arrays and maps).

Once all the items have been encoded, the length of the output buffer can be obtained either by calling 
```c
size_t sz;
ecbor_error_t rc = ecbor_get_encoded_buffer_size(&context, &sz);
```

or by using the `ECBOR_GET_ENCODED_BUFFER_SIZE` macro.

### Decoder

Just like encoding, the decoding operation must use a decode context (`ecbor_decode_context_t`), usually defined on the stack:

```c
ecbor_decode_context_t context;
```

The decoder must be initialized either in *normal* decoding mode

```c
ecbor_error_t rc = ecbor_initialize_decode (&context, buffer, buffer_size);
```

in *streamed* mode

```c
ecbor_error_t rc = ecbor_initialize_decode_streamed (&context, buffer, buffer_size);
```

or in *tree* mode

```c
ecbor_item_t item_buffer[MAX_ITEMS];
ecbor_error_t rc = ecbor_initialize_decode_streamed (&context, buffer, buffer_size, item_buffer, MAX_ITEMS);
```

where `buffer` is the input `uint8_t*` buffer of size `buffer_size`, and `item_buffer` is an output item buffer.

In *streamed* mode, any decoding API call will parse and retrieve *one* item from the buffer, without children, in the order specified in the buffer. This is a *dumb* but fast mode where absolutely no semantic checking is performed. Linking parents to children is left to the user, hence this mode is recommended only for very simple scenarios.

In *normal* mode, any decoding API call will parse one *whole* item, including it's children, but will *not* store the parsed children. Children can later be retrieved with special API calls, but each of them will trigger a re-parsing of part of the subtree. This mode only uses one instance of *ecbor_item_t*, and has no limit on the size of the parsed CBOR, but may be heavy on CPU usage since no parsing results are cached.

In *tree* mode, any decoding API call will parse one *whole* item, including its children, and all parsing results are cached in `item_buffer`. User must make sure this buffer is sufficiently large to store all items. Subsequent API calls to retrieve children will simply explore the parsed tree.

**IMPORTANT:** String items will *not* copy the payload from the original CBOR buffer. Moreover, in *normal* mode children are being re-parsed from the CBOR buffer as well. Do *not* destroy this buffer until *all* manipulation on the CBOR items has been finished.

In *normal* and *streamed* mode, one item can be decoded with

```c
ecbor_item_t item;
ecbor_error_t rc = ecbor_decode (&context, &item);
```

while in *tree* mode, the root item can be decoded with

```c
ecbor_item_t *root = NULL;
ecbor_error_t rc = ecbor_decode_tree (&context, &root);
```

After the call, `root` will point to the root item from the `item_buffer`.

For item manipulation there are two alternative APIs that can be used.

### Decoder - strict API

To retrieve the type of an item:

```c
ecbor_type_t type = ecbor_get_type (&item);
```

To retrieve the values of numerics and booleans:

```c
uint8_t val;
ecbor_error_t rc = ecbor_get_uint8 (item, &val);

uint16_t val;
ecbor_error_t rc = ecbor_get_uint16 (item, &val);

uint32_t val;
ecbor_error_t rc = ecbor_get_uint32 (item, &val);

uint64_t val;
ecbor_error_t rc = ecbor_get_uint64 (item, &val);


int8_t val;
ecbor_error_t rc = ecbor_get_int8 (item, &val);

int16_t val;
ecbor_error_t rc = ecbor_get_int16 (item, &val);

int32_t val;
ecbor_error_t rc = ecbor_get_int32 (item, &val);

int64_t val;
ecbor_error_t rc = ecbor_get_int64 (item, &val);


float val;
ecbor_error_t rc = ecbor_get_fp32 (item, &val);

double val;
ecbor_error_t rc = ecbor_get_fp64 (item, &val);


uint8_t val;
ecbor_error_t rc = ecbor_get_bool (item, &val);
```

To retrieve the *tag value* of a tag item:

```c
uint64_t tag_val;
ecbor_error_t rc = ecbor_get_tag_value (&tag_item, &tag_val);
```

To retrieve the length of a binary string, string, array or map:

```c
size_t length = 0;
ecbor_error_t rc = ecbor_get_length (&item, &length);
```

To retrieve a child of a tag, array or map:

```c
ecbor_item_t arr_item;
ecbor_error_t rc = ecbor_get_array_item (&array, index, &arr_item);

ecbor_item_t *arr_item_ptr = NULL;
ecbor_error_t rc = ecbor_get_array_item_ptr (&array, index, &arr_item_ptr);


ecbor_item_t key, val;
ecbor_error_t rc = ecbor_get_map_item (&map, index, &key, &val);

ecbor_item_t *key_ptr = NULL, *val_ptr = NULL;
ecbor_error_t rc = ecbor_get_map_item_ptr (&map, index, &key_ptr, &val_ptr);


ecbor_item_t item;
ecbor_error_t rc = ecbor_get_tag_item (&tag, &item);

ecbor_item_t *item_ptr = NULL;
ecbor_error_t rc = ecbor_get_tag_item_ptr (&tag, &item_ptr);
```

**IMPORTANT:** Note that the `*_ptr` versions of the APIs work only in *tree* mode.

To retrieve the payload of definite strings and binary strings:

```c
const char *c_str = NULL;
ecbor_error_t rc = ecbor_get_str (&str_item, &c_str);

const uint8_t *buffer = NULL;
ecbor_error_t rc = ecbor_get_bstr (&bstr_item, &buffer);
```

For *indefinite* strings and binary strings, each chunk must be parsed individually (a chunk is a child item of the same type, but with *definite* length):

```c
size_t chunk_count;
ecbor_error_t rc = ecbor_get_str_chunk_count (&str_item, &chunk_count);

ecbor_item_t chunk;
ecbor_error_t rc = ecbor_get_str_chunk (&str_item, index, &chunk);


size_t chunk_count;
ecbor_error_t rc = ecbor_get_bstr_chunk_count (&bstr_item, &chunk_count);

ecbor_item_t chunk;
ecbor_error_t rc = ecbor_get_bstr_chunk (&bstr_item, index, &chunk);
```

### Decoder - fast API

The following macros help to identify the type of the item:

```c
ecbor_item_t item;

ecbor_type_t type = ECBOR_GET_TYPE(&item)

ECBOR_IS_INDEFINITE(&item)
ECBOR_IS_DEFINITE(&item)

ECBOR_IS_NINT(&item)
ECBOR_IS_UINT(&item)
ECBOR_IS_INTEGER(&item)
ECBOR_IS_BSTR(&item)
ECBOR_IS_STR(&item)
ECBOR_IS_ARRAY(&item)
ECBOR_IS_MAP(&item)
ECBOR_IS_TAG(&item)
ECBOR_IS_FP32(&item)
ECBOR_IS_FLOAT(&item)
ECBOR_IS_FP64(&item)
ECBOR_IS_DOUBLE(&item)
ECBOR_IS_BOOL(&item)
ECBOR_IS_NULL(&item)
ECBOR_IS_UNDEFINED(&item)
```

In order to retrieve the value:

```c
ecbor_item_t item;

int64_t val = ECBOR_GET_INT(&item)
uint64_t val = ECBOR_GET_UINT(&item)

const char *c_str = ECBOR_GET_STRING(&item)

float val = ECBOR_GET_FP32(&item)
doube val = ECBOR_GET_FP64(&item)

uint8_t bool_value = ECBOR_GET_BOOL(&item)

uint64_t tag_value = ECBOR_GET_TAG_VALUE(&item)
ecbor_item_t tag_item = ECBOR_GET_TAG_ITEM(&item)
```

And finally, in order to retrieve the length of arrays, maps, strings:

```c
ecbor_item_t item;
size_t len = ECBOR_GET_LENGTH(&item)
```