CBOR

CBOR serializer/deserializer. More...

Detailed Description

CBOR serializer/deserializer.

This is an implementation suited for constrained devices Characteristics:

Supported types (categorized by major type (MT))

Notes about major type 3

Since we do not have a standardised C type for representing Unicode code points, we just provide API to serialize/deserialize char arrays. The user then has to transform that into a meaningful representation

Notes about major type 6

Encoding date and time: date/time strings that follow the standard format described in RFC3339, section 5.6:

Date/Time string Support
2003-12-13T18:30:02Z supported
2003-12-13T18:30:02.25Z not supported
2003-12-13T18:30:02+01:00 not supported
2003-12-13T18:30:02.25+01:00 not supported

Since we do not have C types for representing bignums/bigfloats/decimal-fraction we do not provide API to serialize/deserialize them at all. You can still read out the actual data item behind the tag (via cbor_deserialize_byte_string()) and interpret it yourself.

See also
RFC7049, section 2.4

Notes about major type 7 and simple values

Simple values:

Simple value types Support
0-19: (Unassigned) not supported
20,21: True, False supported (see cbor_serialize_bool(), cbor_deserialize_bool())
22,23: Null, Undefined not supported (what's the use-case?)
24-31: (Reserved) not supported
32-255: (Unassigned) not supported
See also
RFC7049, section 2.4
Todo:
API for Indefinite-Length Byte Strings and Text Strings (see https://tools.ietf.org/html/rfc7049#section-2.2.2)

Files

file  cbor.h
 CBOR definitions.
 

Data Structures

struct  cbor_stream_t
 Struct containing CBOR-encoded data. More...
 

Functions

void cbor_init (cbor_stream_t *stream, unsigned char *buffer, size_t size)
 Initialize cbor struct. More...
 
void cbor_clear (cbor_stream_t *stream)
 Clear cbor struct. More...
 
void cbor_destroy (cbor_stream_t *stream)
 Destroy the cbor struct. More...
 
void cbor_stream_print (const cbor_stream_t *stream)
 Print stream in hex representation. More...
 
void cbor_stream_decode (cbor_stream_t *stream)
 Decode CBOR from stream. More...
 
size_t cbor_serialize_int (cbor_stream_t *stream, int val)
 Serializes an integer. More...
 
size_t cbor_deserialize_int (const cbor_stream_t *stream, size_t offset, int *val)
 Deserialize integers from stream to val. More...
 
size_t cbor_serialize_uint64_t (cbor_stream_t *stream, uint64_t val)
 Serializes an unsigned 64 bit value. More...
 
size_t cbor_deserialize_uint64_t (const cbor_stream_t *stream, size_t offset, uint64_t *val)
 Deserialize unsigned 64 bit values from stream to val. More...
 
size_t cbor_serialize_int64_t (cbor_stream_t *stream, int64_t val)
 Serializes a signed 64 bit value. More...
 
size_t cbor_deserialize_int64_t (const cbor_stream_t *stream, size_t offset, int64_t *val)
 Deserialize signed 64 bit values from stream to val. More...
 
size_t cbor_serialize_bool (cbor_stream_t *stream, bool val)
 Serializes a boolean value. More...
 
size_t cbor_deserialize_bool (const cbor_stream_t *stream, size_t offset, bool *val)
 Deserialize boolean values from stream to val. More...
 
size_t cbor_serialize_byte_string (cbor_stream_t *stream, const char *val)
 Serializes a signed 64 bit value. More...
 
size_t cbor_serialize_byte_stringl (cbor_stream_t *stream, const char *val, size_t length)
 Serializes an arbitrary byte string. More...
 
size_t cbor_deserialize_byte_string (const cbor_stream_t *stream, size_t offset, char *val, size_t length)
 Deserialize bytes from stream to val. More...
 
size_t cbor_serialize_unicode_string (cbor_stream_t *stream, const char *val)
 Serializes a unicode string. More...
 
size_t cbor_deserialize_byte_string_no_copy (const cbor_stream_t *stream, size_t offset, unsigned char **val, size_t *length)
 Deserialize bytes from stream to val (without copy) More...
 
size_t cbor_deserialize_unicode_string_no_copy (const cbor_stream_t *stream, size_t offset, unsigned char **val, size_t *length)
 Deserialize unicode string from stream to val (without copy) More...
 
size_t cbor_deserialize_unicode_string (const cbor_stream_t *stream, size_t offset, char *val, size_t length)
 Deserialize unicode string from stream to val. More...
 
size_t cbor_serialize_array (cbor_stream_t *stream, size_t array_length)
 Serialize array of length array_length. More...
 
size_t cbor_deserialize_array (const cbor_stream_t *stream, size_t offset, size_t *array_length)
 Deserialize array of items. More...
 
size_t cbor_serialize_array_indefinite (cbor_stream_t *stream)
 Serialize array of infite length. More...
 
size_t cbor_deserialize_array_indefinite (const cbor_stream_t *stream, size_t offset)
 Deserialize array of items. More...
 
size_t cbor_serialize_map (cbor_stream_t *stream, size_t map_length)
 Serialize map of length map_length. More...
 
size_t cbor_deserialize_map (const cbor_stream_t *stream, size_t offset, size_t *map_length)
 Deserialize map of items. More...
 
size_t cbor_serialize_map_indefinite (cbor_stream_t *stream)
 Serialize map of infite length. More...
 
size_t cbor_deserialize_map_indefinite (const cbor_stream_t *stream, size_t offset)
 Deserialize map of items. More...
 
size_t cbor_write_break (cbor_stream_t *stream)
 Write a break symbol at the current offset in stream stream. More...
 
bool cbor_at_break (const cbor_stream_t *stream, size_t offset)
 Whether we are at a break symbol in stream stream at offset offset. More...
 
bool cbor_at_end (const cbor_stream_t *stream, size_t offset)
 Whether we are at the end of the stream stream at offset offset. More...
 

Function Documentation

◆ cbor_at_break()

bool cbor_at_break ( const cbor_stream_t stream,
size_t  offset 
)

Whether we are at a break symbol in stream stream at offset offset.

Parameters
[in]streamPointer to the cbor struct
[in]offsetThe offset within stream
Returns
True in case the there is a break symbol at the current offset

◆ cbor_at_end()

bool cbor_at_end ( const cbor_stream_t stream,
size_t  offset 
)

Whether we are at the end of the stream stream at offset offset.

Useful for abort conditions in loops while deserializing CBOR items

Parameters
[in]streamPointer to the cbor struct
[in]offsetThe offset within stream
Returns
True in case offset marks the end of the stream

◆ cbor_clear()

void cbor_clear ( cbor_stream_t stream)

Clear cbor struct.

Sets pos to zero

Parameters
[in,out]streamPointer to the cbor struct

◆ cbor_deserialize_array()

size_t cbor_deserialize_array ( const cbor_stream_t stream,
size_t  offset,
size_t array_length 
)

Deserialize array of items.

Basic usage:

size_t array_length;
// read out length of the array
size_t offset = cbor_deserialize_array(&stream, 0, &array_length);
int i1, i2;
offset += cbor_deserialize_int(&stream, offset, &i1); // read item 1
offset += cbor_deserialize_int(&stream, offset, &i2); // read item 2
Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream
[in]array_lengthWhere the array length is stored
Returns
Number of deserialized bytes from stream

◆ cbor_deserialize_array_indefinite()

size_t cbor_deserialize_array_indefinite ( const cbor_stream_t stream,
size_t  offset 
)

Deserialize array of items.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream
Returns
Number of deserialized bytes from stream

◆ cbor_deserialize_bool()

size_t cbor_deserialize_bool ( const cbor_stream_t stream,
size_t  offset,
bool *  val 
)

Deserialize boolean values from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_byte_string()

size_t cbor_deserialize_byte_string ( const cbor_stream_t stream,
size_t  offset,
char *  val,
size_t  length 
)

Deserialize bytes from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
[in]lengthLength of destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_byte_string_no_copy()

size_t cbor_deserialize_byte_string_no_copy ( const cbor_stream_t stream,
size_t  offset,
unsigned char **  val,
size_t length 
)

Deserialize bytes from stream to val (without copy)

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to a char *
[out]lengthPointer to a size_t to store the size of the string
Returns
Number of bytes written into val

◆ cbor_deserialize_int()

size_t cbor_deserialize_int ( const cbor_stream_t stream,
size_t  offset,
int *  val 
)

Deserialize integers from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_int64_t()

size_t cbor_deserialize_int64_t ( const cbor_stream_t stream,
size_t  offset,
int64_t *  val 
)

Deserialize signed 64 bit values from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_map()

size_t cbor_deserialize_map ( const cbor_stream_t stream,
size_t  offset,
size_t map_length 
)

Deserialize map of items.

Basic usage:

size_t map_length;
// read out length of the map
size_t offset = cbor_deserialize_map(&stream, 0, &map_length);
int key1, key1;
char value1[8], value2[8];
// read key 1
offset += cbor_deserialize_int(&stream, offset, &key1);
// read value 1
offset += cbor_deserialize_byte_string(&stream, offset, value1, sizeof(value));
// read key 2
offset += cbor_deserialize_int(&stream, offset, &key2);
// read value 2
offset += cbor_deserialize_byte_string(&stream, offset, value2, sizeof(value));
Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[in]map_lengthWhere the array length is stored
Returns
Number of deserialized bytes from stream

◆ cbor_deserialize_map_indefinite()

size_t cbor_deserialize_map_indefinite ( const cbor_stream_t stream,
size_t  offset 
)

Deserialize map of items.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream
Returns
Number of deserialized bytes from stream

◆ cbor_deserialize_uint64_t()

size_t cbor_deserialize_uint64_t ( const cbor_stream_t stream,
size_t  offset,
uint64_t *  val 
)

Deserialize unsigned 64 bit values from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_unicode_string()

size_t cbor_deserialize_unicode_string ( const cbor_stream_t stream,
size_t  offset,
char *  val,
size_t  length 
)

Deserialize unicode string from stream to val.

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to destination array
[in]lengthLength of destination array
Returns
Number of bytes read from stream

◆ cbor_deserialize_unicode_string_no_copy()

size_t cbor_deserialize_unicode_string_no_copy ( const cbor_stream_t stream,
size_t  offset,
unsigned char **  val,
size_t length 
)

Deserialize unicode string from stream to val (without copy)

Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valPointer to a char *
[out]lengthPointer to a size_t to store the size of the string
Returns
Number of bytes written into val

◆ cbor_destroy()

void cbor_destroy ( cbor_stream_t stream)

Destroy the cbor struct.

Note
Does not free data
Parameters
[in,out]streamPointer to the cbor struct

◆ cbor_init()

void cbor_init ( cbor_stream_t stream,
unsigned char *  buffer,
size_t  size 
)

Initialize cbor struct.

Note
Does not take ownership of buffer
Parameters
[in]streamThe cbor struct to initialize
[in]bufferThe buffer used for storing CBOR-encoded data
[in]sizeThe size of buffer buffer

◆ cbor_serialize_array()

size_t cbor_serialize_array ( cbor_stream_t stream,
size_t  array_length 
)

Serialize array of length array_length.

Basic usage:

cbor_serialize_array(&stream, 2); // array of length 2 follows
cbor_serialize_int(&stream, 1)); // write item 1
cbor_serialize_int(&stream, 2)); // write item 2
Note
You have to make sure to serialize the correct amount of items. If you exceed the length array_length, items will just be appened as normal
Parameters
[out]streamThe destination stream for serializing the array
[in]array_lengthLength of the array of items which follows
Returns
Number of bytes written to stream stream

◆ cbor_serialize_array_indefinite()

size_t cbor_serialize_array_indefinite ( cbor_stream_t stream)

Serialize array of infite length.

Parameters
[out]streamThe destination stream for serializing the array
Returns
Number of bytes written to stream stream

◆ cbor_serialize_bool()

size_t cbor_serialize_bool ( cbor_stream_t stream,
bool  val 
)

Serializes a boolean value.

Parameters
[out]streamThe destination stream for serializing the array
[in]valThe boolean value to serialize
Returns
Number of bytes written to stream stream

◆ cbor_serialize_byte_string()

size_t cbor_serialize_byte_string ( cbor_stream_t stream,
const char *  val 
)

Serializes a signed 64 bit value.

Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream

◆ cbor_serialize_byte_stringl()

size_t cbor_serialize_byte_stringl ( cbor_stream_t stream,
const char *  val,
size_t  length 
)

Serializes an arbitrary byte string.

Parameters
[out]streamThe destination stream for serializing the byte stream
[in]valThe arbitrary byte string which may include null bytes
[in]lengthThe size of the byte string in bytes
Returns
Number of bytes written to stream stream

◆ cbor_serialize_int()

size_t cbor_serialize_int ( cbor_stream_t stream,
int  val 
)

Serializes an integer.

Parameters
[out]streamThe destination stream for serializing the array
[in]valThe integer to serialize
Returns
Number of bytes written to stream stream

◆ cbor_serialize_int64_t()

size_t cbor_serialize_int64_t ( cbor_stream_t stream,
int64_t  val 
)

Serializes a signed 64 bit value.

Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream

◆ cbor_serialize_map()

size_t cbor_serialize_map ( cbor_stream_t stream,
size_t  map_length 
)

Serialize map of length map_length.

Basic usage:

cbor_serialize_map(&stream, 2); // map of length 2 follows
cbor_serialize_int(&stream, 1)); // write key 1
cbor_serialize_byte_string(&stream, "1")); // write value 1
cbor_serialize_int(&stream, 2)); // write key 2
cbor_serialize_byte_string(&stream, "2")); // write value 2
Parameters
[out]streamThe destination stream for serializing the map
map_lengthLength of the map of items which follows
Returns
Number of bytes written to stream stream

◆ cbor_serialize_map_indefinite()

size_t cbor_serialize_map_indefinite ( cbor_stream_t stream)

Serialize map of infite length.

Parameters
[out]streamThe destination stream for serializing the map
Returns
Number of bytes written to stream stream

◆ cbor_serialize_uint64_t()

size_t cbor_serialize_uint64_t ( cbor_stream_t stream,
uint64_t  val 
)

Serializes an unsigned 64 bit value.

Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream

◆ cbor_serialize_unicode_string()

size_t cbor_serialize_unicode_string ( cbor_stream_t stream,
const char *  val 
)

Serializes a unicode string.

Parameters
[out]streamThe destination stream for serializing the unicode string
[out]valThe zero-terminated unicode string to serialize.
Returns
Number of bytes written to stream stream

◆ cbor_stream_decode()

void cbor_stream_decode ( cbor_stream_t stream)

Decode CBOR from stream.

This method interprets the data and prints each item in its natural representation

Example output:

Data:
(int, 1)
(bool, 1)
(float, 1.099609)
(tag: 0, date/time string: "Mon Jul 14 19:07:40 2014")
(tag: 1, date/time epoch: 1405357660)
Parameters
[in]streamPointer to the cbor struct

◆ cbor_stream_print()

void cbor_stream_print ( const cbor_stream_t stream)

Print stream in hex representation.

Parameters
[in]streamPointer to the cbor struct

◆ cbor_write_break()

size_t cbor_write_break ( cbor_stream_t stream)

Write a break symbol at the current offset in stream stream.

Used for marking the end of indefinite length CBOR items

Parameters
[in]streamPointer to the cbor struct
Returns
Always 1