blob: 187a55c1eaad9cec1dfbb2acd1797ff13fef9165 [file] [log] [blame]
/**
* \file
* \brief
* CBOR parsing
*/
#ifndef CN_CBOR_H
#define CN_CBOR_H
#ifdef __cplusplus
extern "C" {
#endif
#ifdef EMACS_INDENTATION_HELPER
} /* Duh. */
#endif
#include <stdbool.h>
#include <stdint.h>
#include <unistd.h>
/**
* All of the different kinds of CBOR values.
*/
typedef enum cn_cbor_type {
/** false */
CN_CBOR_FALSE,
/** true */
CN_CBOR_TRUE,
/** null */
CN_CBOR_NULL,
/** undefined */
CN_CBOR_UNDEF,
/** Positive integers */
CN_CBOR_UINT,
/** Negative integers */
CN_CBOR_INT,
/** Byte string */
CN_CBOR_BYTES,
/** UTF-8 string */
CN_CBOR_TEXT,
/** Byte string, in chunks. Each chunk is a child. */
CN_CBOR_BYTES_CHUNKED,
/** UTF-8 string, in chunks. Each chunk is a child */
CN_CBOR_TEXT_CHUNKED,
/** Array of CBOR values. Each array element is a child, in order */
CN_CBOR_ARRAY,
/** Map of key/value pairs. Each key and value is a child, alternating. */
CN_CBOR_MAP,
/** Tag describing the next value. The next value is the single child. */
CN_CBOR_TAG,
/** Simple value, other than the defined ones */
CN_CBOR_SIMPLE,
/** Doubles, floats, and half-floats */
CN_CBOR_DOUBLE,
/** Floats, and half-floats */
CN_CBOR_FLOAT,
/** An error has occurred */
CN_CBOR_INVALID
} cn_cbor_type;
/**
* Flags used during parsing. Not useful for consumers of the
* `cn_cbor` structure.
*/
typedef enum cn_cbor_flags {
/** The count field will be used for parsing */
CN_CBOR_FL_COUNT = 1,
/** An indefinite number of children */
CN_CBOR_FL_INDEF = 2,
/** Not used yet; the structure must free the v.str pointer when the
structure is freed */
CN_CBOR_FL_OWNER = 0x80, /* of str */
} cn_cbor_flags;
/**
* A CBOR value
*/
typedef struct cn_cbor {
/** The type of value */
cn_cbor_type type;
/** Flags used at parse time */
cn_cbor_flags flags;
/** Data associated with the value; different branches of the union are
used depending on the `type` field. */
union {
/** CN_CBOR_BYTES */
const uint8_t* bytes;
/** CN_CBOR_TEXT */
const char* str;
/** CN_CBOR_INT */
long sint;
/** CN_CBOR_UINT */
unsigned long uint;
/** CN_CBOR_DOUBLE */
double dbl;
/** CN_CBOR_FLOAT */
float f;
/** for use during parsing */
unsigned long count;
} v; /* TBD: optimize immediate */
/** Number of children.
* @note: for maps, this is 2x the number of entries */
int length;
/** The first child value */
struct cn_cbor* first_child;
/** The last child value */
struct cn_cbor* last_child;
/** The sibling after this one, or NULL if this is the last */
struct cn_cbor* next;
/** The parent of this value, or NULL if this is the root */
struct cn_cbor* parent;
} cn_cbor;
/**
* All of the different kinds of errors
*/
typedef enum cn_cbor_error {
/** No error has occurred */
CN_CBOR_NO_ERROR,
/** More data was expected while parsing */
CN_CBOR_ERR_OUT_OF_DATA,
/** Some extra data was left over at the end of parsing */
CN_CBOR_ERR_NOT_ALL_DATA_CONSUMED,
/** A map should be alternating keys and values. A break was found
when a value was expected */
CN_CBOR_ERR_ODD_SIZE_INDEF_MAP,
/** A break was found where it wasn't expected */
CN_CBOR_ERR_BREAK_OUTSIDE_INDEF,
/** Indefinite encoding works for bstrs, strings, arrays, and maps.
A different major type tried to use it. */
CN_CBOR_ERR_MT_UNDEF_FOR_INDEF,
/** Additional Information values 28-30 are reserved */
CN_CBOR_ERR_RESERVED_AI,
/** A chunked encoding was used for a string or bstr, and one of the elements
wasn't the expected (string/bstr) type */
CN_CBOR_ERR_WRONG_NESTING_IN_INDEF_STRING,
/** An invalid parameter was passed to a function */
CN_CBOR_ERR_INVALID_PARAMETER,
/** Allocation failed */
CN_CBOR_ERR_OUT_OF_MEMORY,
/** A float was encountered during parse but the library was built without
support for float types. */
CN_CBOR_ERR_FLOAT_NOT_SUPPORTED
} cn_cbor_error;
/**
* Strings matching the `cn_cbor_error` conditions.
*
* @todo: turn into a function to make the type safety more clear?
*/
extern const char *cn_cbor_error_str[];
/**
* Errors
*/
typedef struct cn_cbor_errback {
/** The position in the input where the erorr happened */
int pos;
/** The error, or CN_CBOR_NO_ERROR if none */
cn_cbor_error err;
} cn_cbor_errback;
#ifdef USE_CBOR_CONTEXT
/**
* Allocate and zero out memory. `count` elements of `size` are required,
* as for `calloc(3)`. The `context` is the `cn_cbor_context` passed in
* earlier to the CBOR routine.
*
* @param[in] count The number of items to allocate
* @param[in] size The size of each item
* @param[in] context The allocation context
*/
typedef void* (*cn_calloc_func)(size_t count, size_t size, void *context);
/**
* Free memory previously allocated with a context. If using a pool allocator,
* this function will often be a no-op, but it must be supplied in order to
* prevent the CBOR library from calling `free(3)`.
*
* @note: it may be that this is never needed; if so, it will be removed for
* clarity and speed.
*
* @param context [description]
* @return [description]
*/
typedef void (*cn_free_func)(void *ptr, void *context);
/**
* The allocation context.
*/
typedef struct cn_cbor_context {
/** The pool `calloc` routine. Must allocate and zero. */
cn_calloc_func calloc_func;
/** The pool `free` routine. Often a no-op, but required. */
cn_free_func free_func;
/** Typically, the pool object, to be used when calling `calloc_func`
* and `free_func` */
void *context;
} cn_cbor_context;
/** When USE_CBOR_CONTEXT is defined, many functions take an extra `context`
* parameter */
#define CBOR_CONTEXT , cn_cbor_context *context
/** When USE_CBOR_CONTEXT is defined, some functions take an extra `context`
* parameter at the beginning */
#define CBOR_CONTEXT_COMMA cn_cbor_context *context,
#else
#define CBOR_CONTEXT
#define CBOR_CONTEXT_COMMA
#endif
/**
* Decode an array of CBOR bytes into structures.
*
* @param[in] buf The array of bytes to parse
* @param[in] len The number of bytes in the array
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The parsed CBOR structure, or NULL on error
*/
cn_cbor* cn_cbor_decode(const uint8_t *buf, size_t len CBOR_CONTEXT, cn_cbor_errback *errp);
/**
* Get a value from a CBOR map that has the given string as a key.
*
* @param[in] cb The CBOR map
* @param[in] key The string to look up in the map
* @return The matching value, or NULL if the key is not found
*/
cn_cbor* cn_cbor_mapget_string(const cn_cbor* cb, const char* key);
/**
* Get a value from a CBOR map that has the given integer as a key.
*
* @param[in] cb The CBOR map
* @param[in] key The int to look up in the map
* @return The matching value, or NULL if the key is not found
*/
cn_cbor* cn_cbor_mapget_int(const cn_cbor* cb, int key);
/**
* Get the item with the given index from a CBOR array.
*
* @param[in] cb The CBOR map
* @param[in] idx The array index
* @return The matching value, or NULL if the index is invalid
*/
cn_cbor* cn_cbor_index(const cn_cbor* cb, unsigned int idx);
/**
* Free the given CBOR structure.
* You MUST NOT try to free a cn_cbor structure with a parent (i.e., one
* that is not a root in the tree).
*
* @param[in] cb The CBOR value to free. May be NULL, or a root object.
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
*/
void cn_cbor_free(cn_cbor* cb CBOR_CONTEXT);
/**
* Write a CBOR value and all of the child values.
*
* @param[in] buf The buffer into which to write
* @param[in] buf_offset The offset (in bytes) from the beginning of the buffer
* to start writing at
* @param[in] buf_size The total length (in bytes) of the buffer
* @param[in] cb [description]
* @return -1 on fail, or number of bytes written
*/
ssize_t cn_cbor_encoder_write(uint8_t *buf,
size_t buf_offset,
size_t buf_size,
const cn_cbor *cb);
/**
* Create a CBOR map.
*
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created map, or NULL on error
*/
cn_cbor* cn_cbor_map_create(CBOR_CONTEXT_COMMA cn_cbor_errback *errp);
/**
* Create a CBOR byte string. The data in the byte string is *not* owned
* by the CBOR object, so it is not freed automatically.
*
* @param[in] data The data
* @param[in] len The number of bytes of data
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_data_create(const uint8_t* data, int len
CBOR_CONTEXT,
cn_cbor_errback *errp);
/**
* Create a CBOR UTF-8 string. The data is not checked for UTF-8 correctness.
* The data being stored in the string is *not* owned the CBOR object, so it is
* not freed automatically.
*
* @note: Do NOT use this function with untrusted data. It calls strlen, and
* relies on proper NULL-termination.
*
* @param[in] data NULL-terminated UTF-8 string
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_string_create(const char* data
CBOR_CONTEXT,
cn_cbor_errback *errp);
/**
* Create a CBOR integer (either positive or negative).
*
* @param[in] value the value of the integer
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_int_create(int64_t value
CBOR_CONTEXT,
cn_cbor_errback *errp);
#ifndef CBOR_NO_FLOAT
/**
* Create a CBOR float.
*
* @param[in] value the value of the float
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_float_create(float value
CBOR_CONTEXT,
cn_cbor_errback *errp);
/**
* Create a CBOR double.
*
* @param[in] value the value of the double
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_double_create(double value
CBOR_CONTEXT,
cn_cbor_errback *errp);
#endif /* CBOR_NO_FLOAT */
/**
* Put a CBOR object into a map with a CBOR object key. Duplicate checks are NOT
* currently performed.
*
* @param[in] cb_map The map to insert into
* @param[in] key The key
* @param[in] cb_value The value
* @param[out] errp Error
* @return True on success
*/
bool cn_cbor_map_put(cn_cbor* cb_map,
cn_cbor *cb_key, cn_cbor *cb_value,
cn_cbor_errback *errp);
/**
* Put a CBOR object into a map with an integer key. Duplicate checks are NOT
* currently performed.
*
* @param[in] cb_map The map to insert into
* @param[in] key The integer key
* @param[in] cb_value The value
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error
* @return True on success
*/
bool cn_cbor_mapput_int(cn_cbor* cb_map,
int64_t key, cn_cbor* cb_value
CBOR_CONTEXT,
cn_cbor_errback *errp);
/**
* Put a CBOR object into a map with a string key. Duplicate checks are NOT
* currently performed.
*
* @note: do not call this routine with untrusted string data. It calls
* strlen, and requires a properly NULL-terminated key.
*
* @param[in] cb_map The map to insert into
* @param[in] key The string key
* @param[in] cb_value The value
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error
* @return True on success
*/
bool cn_cbor_mapput_string(cn_cbor* cb_map,
const char* key, cn_cbor* cb_value
CBOR_CONTEXT,
cn_cbor_errback *errp);
/**
* Create a CBOR array
*
* @param[in] CBOR_CONTEXT Allocation context (only if USE_CBOR_CONTEXT is defined)
* @param[out] errp Error, if NULL is returned
* @return The created object, or NULL on error
*/
cn_cbor* cn_cbor_array_create(CBOR_CONTEXT_COMMA cn_cbor_errback *errp);
/**
* Append an item to the end of a CBOR array.
*
* @param[in] cb_array The array into which to insert
* @param[in] cb_value The value to insert
* @param[out] errp Error
* @return True on success
*/
bool cn_cbor_array_append(cn_cbor* cb_array,
cn_cbor* cb_value,
cn_cbor_errback *errp);
#ifdef __cplusplus
}
#endif
#endif /* CN_CBOR_H */