astarte_bson_serializer.h File Reference

Astarte BSON serializer functions. More...

#include "astarte.h"
#include <stdbool.h>
#include <stdint.h>
#include <string.h>

Include dependency graph for astarte_bson_serializer.h:

Go to the source code of this file.

Data Structures
struct	astarte_byte_array_t
struct	astarte_bson_serializer_handle_t

Functions
struct astarte_byte_array_t	__attribute__ ((deprecated("This sould never be used directly, use astarte_bson_serializer_handle_t")))
struct astarte_bson_serializer_t	__attribute__ ((deprecated("Use the new typedefined astarte_bson_serializer_handle_t")))
void	astarte_bson_serializer_init (astarte_bson_serializer_handle_t bson) __attribute__((deprecated("Use astarte_bson_serializer_new instead")))
	initialize given BSON serializer. More...
astarte_bson_serializer_handle_t	astarte_bson_serializer_new (void)
	create a new instance of the BSON serializer. More...
void	astarte_bson_serializer_destroy (astarte_bson_serializer_handle_t bson)
	destroy given BSON serializer instance. More...
const void *	astarte_bson_serializer_get_document (astarte_bson_serializer_handle_t bson, int *size)
	getter for the BSON serializer internal buffer. More...
astarte_err_t	astarte_bson_serializer_write_document (astarte_bson_serializer_handle_t bson, void *out_buf, int out_buf_len, int *out_doc_size)
	copy BSON serializer internal buffer to a different buffer. More...
size_t	astarte_bson_serializer_document_size (astarte_bson_serializer_handle_t bson)
	return the document size More...
void	astarte_bson_serializer_append_end_of_document (astarte_bson_serializer_handle_t bson)
	append end of document marker. More...
void	astarte_bson_serializer_append_double (astarte_bson_serializer_handle_t bson, const char *name, double value)
	append a double value More...
void	astarte_bson_serializer_append_int32 (astarte_bson_serializer_handle_t bson, const char *name, int32_t value)
	append an int32 value More...
void	astarte_bson_serializer_append_int64 (astarte_bson_serializer_handle_t bson, const char *name, int64_t value)
	append an int64 value More...
void	astarte_bson_serializer_append_binary (astarte_bson_serializer_handle_t bson, const char *name, const void *value, size_t size)
	append a binary blob value More...
void	astarte_bson_serializer_append_string (astarte_bson_serializer_handle_t bson, const char *name, const char *string)
	append an UTF-8 string More...
void	astarte_bson_serializer_append_datetime (astarte_bson_serializer_handle_t bson, const char *name, uint64_t epoch_millis)
	append a date time value More...
void	astarte_bson_serializer_append_boolean (astarte_bson_serializer_handle_t bson, const char *name, bool value)
	append a boolean value More...
void	astarte_bson_serializer_append_document (astarte_bson_serializer_handle_t bson, const char *name, const void *document)
	append a sub-BSON document. More...
astarte_err_t	astarte_bson_serializer_append_double_array (astarte_bson_serializer_handle_t bson, const char *name, const double *arr, int count)
	append a double array More...
astarte_err_t	astarte_bson_serializer_append_int32_array (astarte_bson_serializer_handle_t bson, const char *name, const int32_t *arr, int count)
	append an int32 array More...
astarte_err_t	astarte_bson_serializer_append_int64_array (astarte_bson_serializer_handle_t bson, const char *name, const int64_t *arr, int count)
	append an int64 array More...
astarte_err_t	astarte_bson_serializer_append_string_array (astarte_bson_serializer_handle_t bson, const char *name, const char *const *arr, int count)
	append a string array More...
astarte_err_t	astarte_bson_serializer_append_binary_array (astarte_bson_serializer_handle_t bson, const char *name, const void *const *arr, const int *sizes, int count)
	append a binary blob array More...
astarte_err_t	astarte_bson_serializer_append_datetime_array (astarte_bson_serializer_handle_t bson, const char *name, const int64_t *arr, int count)
	append a date time array More...
astarte_err_t	astarte_bson_serializer_append_boolean_array (astarte_bson_serializer_handle_t bson, const char *name, const bool *arr, int count)
	append a boolean array More...

Variables
size_t	capacity
size_t	size
uint8_t *	buf
struct astarte_byte_array_t	ba

Detailed Description

Astarte BSON serializer functions.

Function Documentation

astarte_bson_serializer_append_binary()

void astarte_bson_serializer_append_binary	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const void *	value,
		size_t	size
	)

append a binary blob value

This function appends a binary blob to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	value	the buffer that holds the binary blob.
[in]	size	blob size in bytes.

astarte_bson_serializer_append_binary_array()

astarte_err_t astarte_bson_serializer_append_binary_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const void *const *	arr,
		const int *	sizes,
		int	count
	)

append a binary blob array

This function appends a binary blob array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	binarty_array	an array of binary blobs (void *).
[in]	sizes	an array with the sizes of each binary in binary_array parameter.
[in]	count	the number of items stored in binary_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_boolean()

void astarte_bson_serializer_append_boolean	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		bool	value
	)

append a boolean value

This function appends a boolean value to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	value	0 as false value, not 0 as true value.

astarte_bson_serializer_append_boolean_array()

astarte_err_t astarte_bson_serializer_append_boolean_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const bool *	arr,
		int	count
	)

append a boolean array

This function appends a boolean array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	boolean_array	an array of stdbool booleans.
[in]	count	the number of items stored in boolean_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_datetime()

void astarte_bson_serializer_append_datetime	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		uint64_t	epoch_millis
	)

append a date time value

This function appends a date time value to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	epoch_millis	a 64 bits unsigned integer storing date time in milliseconds since epoch.

astarte_bson_serializer_append_datetime_array()

astarte_err_t astarte_bson_serializer_append_datetime_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const int64_t *	arr,
		int	count
	)

append a date time array

This function appends a date time array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	epoch_millis_array	an array of 64 bits unsigned integer storing date time in milliseconds since epoch.
[in]	count	the number of items stored in epoch_millis_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_document()

void astarte_bson_serializer_append_document	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const void *	document
	)

append a sub-BSON document.

This function appends a BSON subdocument to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	document	a valid BSON document (that has been already terminated).

astarte_bson_serializer_append_double()

void astarte_bson_serializer_append_double	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		double	value
	)

append a double value

This function appends a double value to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	value	a double floating point value.

astarte_bson_serializer_append_double_array()

astarte_err_t astarte_bson_serializer_append_double_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const double *	arr,
		int	count
	)

append a double array

This function appends a double array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	double_array	an array of doubles.
[in]	count	the number of items stored in double_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_end_of_document()

void astarte_bson_serializer_append_end_of_document

(

astarte_bson_serializer_handle_t

bson

)

append end of document marker.

BSON document MUST be manually terminated with an end of document marker.

Parameters

[in,out]

bson

a valid handle for the serializer instance.

astarte_bson_serializer_append_int32()

void astarte_bson_serializer_append_int32	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		int32_t	value
	)

append an int32 value

This function appends an int32 value to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	value	a 32 bits signed integer value.

astarte_bson_serializer_append_int32_array()

astarte_err_t astarte_bson_serializer_append_int32_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const int32_t *	arr,
		int	count
	)

append an int32 array

This function appends an int32 array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	int32_array	an array of signed 32 bit integers.
[in]	count	the number of items stored in int32_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_int64()

void astarte_bson_serializer_append_int64	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		int64_t	value
	)

append an int64 value

This function appends an int64 value to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	value	a 64 bits signed integer value.

astarte_bson_serializer_append_int64_array()

astarte_err_t astarte_bson_serializer_append_int64_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const int64_t *	arr,
		int	count
	)

append an int64 array

This function appends an int64 array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	int64_array	an array of signed 64 bit integers.
[in]	count	the number of items stored in int64_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_append_string()

void astarte_bson_serializer_append_string	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const char *	string
	)

append an UTF-8 string

This function appends an UTF-8 string to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	string	a 0 terminated UTF-8 string.

astarte_bson_serializer_append_string_array()

astarte_err_t astarte_bson_serializer_append_string_array	(	astarte_bson_serializer_handle_t	bson,
		const char *	name,
		const char *const *	arr,
		int	count
	)

append a string array

This function appends a string array to the document.

Parameters

[in,out]	bson	a valid handle for the serializer instance.
[in]	name	BSON element name, which is a C string.
[in]	string_array	an array of 0 terminated UTF-8 strings.
[in]	count	the number of items stored in string_array.

Returns

ASTARTE_ERR upon serialization failure. ASTARTE_OK otherwise.

astarte_bson_serializer_destroy()

void astarte_bson_serializer_destroy

(

astarte_bson_serializer_handle_t

bson

)

destroy given BSON serializer instance.

This function has to be called to destroy and free the memory used by a serializer instance.

Parameters

[in]

bson

a valid handle for the serializer instance that will be destroyed.

astarte_bson_serializer_document_size()

size_t astarte_bson_serializer_document_size

(

astarte_bson_serializer_handle_t

bson

)

return the document size

This function returns BSON document size in bytes.

Parameters

[in]

bson

a valid handle for the serializer instance.

astarte_bson_serializer_get_document()

const void* astarte_bson_serializer_get_document	(	astarte_bson_serializer_handle_t	bson,
		int *	size
	)

getter for the BSON serializer internal buffer.

This function might be used to get internal buffer without any data copy. The returned buffer will be invalid after serializer destruction.

Parameters

[in]	bson	a valid handle for the serializer instance.
[out]	size	the size of the internal buffer. Optional, pass NULL if not used.

Returns

Reference to the internal buffer.

astarte_bson_serializer_init()

void astarte_bson_serializer_init

(

astarte_bson_serializer_handle_t

bson

)

initialize given BSON serializer.

This function has to be called to initialize and allocate memory for a serializer instance.

Parameters

[out]

bson

the astarte_bson_serializer_handle_t that will be initialized.

astarte_bson_serializer_new()

astarte_bson_serializer_handle_t astarte_bson_serializer_new

(

void

)

create a new instance of the BSON serializer.

This function has to be called to initialize and allocate memory for an instance of the BSON serializer.

Returns

The handle to the initialized BSON serializer instance.

astarte_bson_serializer_write_document()

astarte_err_t astarte_bson_serializer_write_document	(	astarte_bson_serializer_handle_t	bson,
		void *	out_buf,
		int	out_buf_len,
		int *	out_doc_size
	)

copy BSON serializer internal buffer to a different buffer.

This function should be used to get a copy of the BSON document data. The document should be terminated by calling the append end of document function before calling this function.

Parameters

[in]	bson	a valid handle for the serializer instance.
[out]	out_buf	destination buffer, previously allocated.
[in]	out_buf_len	destination buffer length.
[out]	out_doc_size	BSON document size (that is <= out_buf_len). Optional, pass NULL if not used.

Returns

astarte_err_t ASTARTE_OK on success, otherwise an error is returned.