cbor.h File Reference

Implementation of a CBOR serializer/deserializer in C. More...

Detailed Description

Author
Kevin Funk kfunk.nosp@m.@kde.nosp@m..org
Jana Cavojska jana..nosp@m.cavo.nosp@m.jska9.nosp@m.@gma.nosp@m.il.co.nosp@m.m
Oliver Hahm olive.nosp@m.r.ha.nosp@m.hm@in.nosp@m.ria..nosp@m.fr

This is an implementation suited for constrained devices Characteristics:

  • No dynamic memory allocation (i.e. no calls to malloc, free) used throughout the implementation
  • User may allocate static buffers, this implementation uses the space provided by them (cf. cbor_stream_t)
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 (cf. https://tools.ietf.org/html/rfc7049#section-2.4):
Encoding date and time: date/time strings that follow the standard format described in Section 3.3 of [RFC3339]: 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.
Notes about major type 7 and simple values
(cf. https://tools.ietf.org/html/rfc7049#section-2.3) Simple values:
  • 0-19: (Unassigned) - No support
  • 20,21: True, False - Supported (see cbor_serialize_bool(), cbor_deserialize_bool())
  • 22,23: Null, Undefined - No support (what's the use-case?)
  • 24-31: (Reserved) - No support
  • 32-255: (Unassigned) - No support
Todo:
API for Indefinite-Length Byte Strings and Text Strings (see https://tools.ietf.org/html/rfc7049#section-2.2.2)

Definition in file cbor.h.

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <time.h>
+ Include dependency graph for cbor.h:

Go to the source code of this file.

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_float_half (cbor_stream_t *stream, float val)
 Serializes a half-width floating point value. More...
 
size_t cbor_deserialize_float_half (const cbor_stream_t *stream, size_t offset, float *val)
 Deserialize half-width floating point values values from stream to val. More...
 
size_t cbor_serialize_float (cbor_stream_t *stream, float val)
 Serializes a floating point value. More...
 
size_t cbor_deserialize_float (const cbor_stream_t *stream, size_t offset, float *val)
 Deserialize floating point values values from stream to val. More...
 
size_t cbor_serialize_double (cbor_stream_t *stream, double val)
 Serializes a double precision floating point value. More...
 
size_t cbor_deserialize_double (const cbor_stream_t *stream, size_t offset, double *val)
 Deserialize double precision floating point valeus 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)
 
size_t cbor_deserialize_byte_string_no_copy (const cbor_stream_t *stream, size_t offset, unsigned char **val, size_t *length)
 Deserialize bytes/unicode 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)
 
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_serialize_date_time (cbor_stream_t *stream, struct tm *val)
 Serialize date and time. More...
 
size_t cbor_deserialize_date_time (const cbor_stream_t *stream, size_t offset, struct tm *val)
 Deserialize date and time. More...
 
size_t cbor_serialize_date_time_epoch (cbor_stream_t *stream, time_t val)
 
size_t cbor_deserialize_date_time_epoch (const cbor_stream_t *stream, size_t offset, time_t *val)
 
size_t cbor_write_tag (cbor_stream_t *stream, unsigned char tag)
 Write a tag to give the next CBOR item additional semantics. More...
 
bool cbor_at_tag (const cbor_stream_t *stream, size_t offset)
 Whether we are at a tag symbol in stream stream at offset offset. 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

bool cbor_at_break ( const cbor_stream_t stream,
size_t  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
bool cbor_at_end ( const cbor_stream_t stream,
size_t  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
bool cbor_at_tag ( const cbor_stream_t stream,
size_t  offset 
)
Parameters
[in]streamPointer to the cbor struct
[in]offsetThe offset within stream
Returns
True in case there is a tag symbol at the current offset
void cbor_clear ( cbor_stream_t stream)

Sets pos to zero

Parameters
[in,out]streamPointer to the cbor struct
size_t cbor_deserialize_array ( const cbor_stream_t stream,
size_t  offset,
size_t *  array_length 
)

Basic usage:

1 size_t array_length;
2 // read out length of the array
3 size_t offset = cbor_deserialize_array(&stream, 0, &array_length);
4 int i1, i2;
5 offset += cbor_deserialize_int(&stream, offset, &i1); // read item 1
6 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
size_t cbor_deserialize_array_indefinite ( const cbor_stream_t stream,
size_t  offset 
)
Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream
Returns
Number of deserialized bytes from stream
size_t cbor_deserialize_bool ( const cbor_stream_t stream,
size_t  offset,
bool *  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
size_t cbor_deserialize_byte_string ( const cbor_stream_t stream,
size_t  offset,
char *  val,
size_t  length 
)
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
size_t cbor_deserialize_byte_string_no_copy ( const cbor_stream_t stream,
size_t  offset,
unsigned char **  val,
size_t *  length 
)
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
size_t cbor_deserialize_date_time ( const cbor_stream_t stream,
size_t  offset,
struct tm val 
)

Basic usage:

1 struct tm val;
2 cbor_deserialize_date_time(&stream, 0, &val);
Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream where to start deserializing
[out]valtm struct where the decoded date/time will be stored
Returns
The number of deserialized bytes
size_t cbor_deserialize_double ( const cbor_stream_t stream,
size_t  offset,
double *  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
size_t cbor_deserialize_float ( const cbor_stream_t stream,
size_t  offset,
float *  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
size_t cbor_deserialize_float_half ( const cbor_stream_t stream,
size_t  offset,
float *  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
size_t cbor_deserialize_int ( const cbor_stream_t stream,
size_t  offset,
int *  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
size_t cbor_deserialize_int64_t ( const cbor_stream_t stream,
size_t  offset,
int64_t *  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
size_t cbor_deserialize_map ( const cbor_stream_t stream,
size_t  offset,
size_t *  map_length 
)

Basic usage:

1 size_t map_length;
2 // read out length of the map
3 size_t offset = cbor_deserialize_map(&stream, 0, &map_length);
4 int key1, key1;
5 char value1[8], value2[8];
6 // read key 1
7 offset += cbor_deserialize_int(&stream, offset, &key1);
8 // read value 1
9 offset += cbor_deserialize_byte_string(&stream, offset, value1, sizeof(value));
10 // read key 2
11 offset += cbor_deserialize_int(&stream, offset, &key2);
12 // read value 2
13 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
size_t cbor_deserialize_map_indefinite ( const cbor_stream_t stream,
size_t  offset 
)
Parameters
[in]streamThe stream to deserialize
[in]offsetThe offset within the stream
Returns
Number of deserialized bytes from stream
size_t cbor_deserialize_uint64_t ( const cbor_stream_t stream,
size_t  offset,
uint64_t *  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
size_t cbor_deserialize_unicode_string ( const cbor_stream_t stream,
size_t  offset,
char *  val,
size_t  length 
)
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
void cbor_destroy ( cbor_stream_t stream)
Note
Does not free data
Parameters
[in,out]streamPointer to the cbor struct
void cbor_init ( cbor_stream_t stream,
unsigned char *  buffer,
size_t  size 
)
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
size_t cbor_serialize_array ( cbor_stream_t stream,
size_t  array_length 
)

Basic usage:

1 cbor_serialize_array(&stream, 2); // array of length 2 follows
2 cbor_serialize_int(&stream, 1)); // write item 1
3 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
size_t cbor_serialize_array_indefinite ( cbor_stream_t stream)
Parameters
[out]streamThe destination stream for serializing the array
Returns
Number of bytes written to stream stream
size_t cbor_serialize_bool ( cbor_stream_t stream,
bool  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe boolean value to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_byte_string ( cbor_stream_t stream,
const char *  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_byte_stringl ( cbor_stream_t stream,
const char *  val,
size_t  length 
)
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
size_t cbor_serialize_date_time ( cbor_stream_t stream,
struct tm val 
)

Basic usage:

1 struct tm val;
2 val.tm_year = 114;
3 val.tm_mon = 6;
4 val.tm_mday = 1;
5 val.tm_hour = 15;
6 val.tm_min = 0;
7 val.tm_sec = 0;
8 mktime(&val);
9 cbor_serialize_date_time(&stream, &val);
Parameters
[out]streamThe destination stream for serializing the date_time
[in]valtm struct containing the date/time info to be encoded
Returns
Number of bytes written to stream stream
size_t cbor_serialize_double ( cbor_stream_t stream,
double  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe double to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_float ( cbor_stream_t stream,
float  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe float to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_float_half ( cbor_stream_t stream,
float  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe half-width floating point value to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_int ( cbor_stream_t stream,
int  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe integer to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_int64_t ( cbor_stream_t stream,
int64_t  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream
size_t cbor_serialize_map ( cbor_stream_t stream,
size_t  map_length 
)

Basic usage:

1 cbor_serialize_map(&stream, 2); // map of length 2 follows
2 cbor_serialize_int(&stream, 1)); // write key 1
3 cbor_serialize_byte_string(&stream, "1")); // write value 1
4 cbor_serialize_int(&stream, 2)); // write key 2
5 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
size_t cbor_serialize_map_indefinite ( cbor_stream_t stream)
Parameters
[out]streamThe destination stream for serializing the map
Returns
Number of bytes written to stream stream
size_t cbor_serialize_uint64_t ( cbor_stream_t stream,
uint64_t  val 
)
Parameters
[out]streamThe destination stream for serializing the array
[in]valThe 64 bit integer to serialize
Returns
Number of bytes written to stream stream
void cbor_stream_decode ( cbor_stream_t stream)

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

Example output:

1 Data:
2 (int, 1)
3 (bool, 1)
4 (float, 1.099609)
5 (tag: 0, date/time string: "Mon Jul 14 19:07:40 2014")
6 (tag: 1, date/time epoch: 1405357660)
Parameters
[in]streamPointer to the cbor struct
void cbor_stream_print ( const cbor_stream_t stream)
Parameters
[in]streamPointer to the cbor struct
size_t cbor_write_break ( cbor_stream_t stream)

Used for marking the end of indefinite length CBOR items

Parameters
[in]streamPointer to the cbor struct
Returns
Always 1
size_t cbor_write_tag ( cbor_stream_t stream,
unsigned char  tag 
)

Also see https://tools.ietf.org/html/rfc7049#section-2.4 (Optional Tagging of Items)

Parameters
[in,out]streamPointer to the cbor struct
[in]tagThe tag to write
Returns
Always 1