# Decoding

The following diagram illustrates the relationship among different parts of libcbor from the decoding standpoint.

    ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
    │                                                                                              │
    │                                      Client application                                      │
    │                                                                                              │
    │                                                 ┌────────────────────────────────────────────┘
    │                                                 │                     ↕
    │                                                 │ ┌──────────────────────────────────────────┐
    │                                                 │ │                                          │
    │                                                 │ │          Manipulation routines           │
    │                                                 │ │                                          │
    │           ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
    │           │     ↑    ↑                  ↑                              ↑
    │           │     │    │    ┌─────────────╫──────────┬───────────────────┴─┐
    │           │     │   CDS   │             ║          │                     │
    │           │     │    │   PDS            ║         PDS                   PDS
    │           │     ↓    ↓    ↓             ↓          ↓                     ↓
    │           │ ┌─────────────────┐   ┌────────────────────┐   ┌────────────────────────────┐
    │           │ │                 │   │                    │   │                            │
    │           │ │  Custom driver  │ ↔ │  Streaming driver  │ ↔ │       Default driver       │ ↔ CD
    │           │ │                 │   │                    │   │                            │
    └───────────┘ └─────────────────┘   └────────────────────┘   └────────────────────────────┘
          ↕                ↕                        ↕                           ↕
    ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
    │                                                                                              │
    │                            Stateless event─driven decoder                                    │
    │                                                                                              │
    └──────────────────────────────────────────────────────────────────────────────────────────────┘

                  (PSD = Provided Data Structures, CDS = Custom Data Structures)

This section will deal with the API that is labeled as the “Default driver” in the diagram. That is, routines that decode complete libcbor data items

cbor_item_t *cbor_load(cbor_data source, size_t source_size, struct cbor_load_result *result)

  Loads data item from a buffer.

  param source:

    The buffer

  param source_size:

  param result:

    [out] Result indicator. CBOR_ERR_NONE on success

  return:

    Decoded CBOR item. The item’s reference count is initialized to one.

  return:

    `NULL` on failure. In that case, `result` contains the location and description of the error.

## Associated data structures

enum cbor_error_code

  Possible decoding errors.

  Values:

  enumerator CBOR_ERR_NONE
  enumerator CBOR_ERR_NOTENOUGHDATA
  enumerator CBOR_ERR_NODATA
  enumerator CBOR_ERR_MALFORMATED
  enumerator CBOR_ERR_MEMERROR

    Memory error - item allocation failed.

    Is it too big for your allocator?

  enumerator CBOR_ERR_SYNTAXERROR

    Stack parsing algorithm failed.

struct cbor_load_result

  High-level decoding result.

  Public Members

  struct cbor_error error

    Error indicator.

  size_t read

    Number of bytes read.

struct cbor_error

  High-level decoding error.

  Public Members

  size_t position

    Approximate position.

  cbor_error_code code

    Description.