BSON Declarations. More...

#include <time.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>
#include "common_decimal.h"
#include <stdint.h>

Go to the source code of this file.

Classes
struct	bson_iterator

struct	bson

union	bson_oid_t

struct	bson_timestamp_t

Macros
#define	SDB_EXPORT __declspec(dllimport)

#define	SDB_EXTERN_C_START

#define	SDB_EXTERN_C_END

#define	bson_little_endian64(out, in) ( memcpy(out, in, 8) )

#define	bson_little_endian32(out, in) ( memcpy(out, in, 4) )

#define	bson_little_endian16(out, in) ( memcpy(out, in, 2) )

#define	bson_big_endian64(out, in) ( bson_swap_endian64(out, in) )

#define	bson_big_endian32(out, in) ( bson_swap_endian32(out, in) )

#define	bson_big_endian16(out, in) ( bson_swap_endian16(out, in) )

#define	BSON_OK 0

#define	BSON_ERROR -1

#define	BSON_MAX_STACK_SIZE 32

Typedefs
typedef int	bson_bool_t

typedef int64_t	bson_date_t

typedef void(*	bson_err_handler )(const char *errmsg)

typedef int(*	bson_printf_func )(const char *,...)

typedef int(*	bson_fprintf_func )(FILE , const char ,...)

typedef int(*	bson_sprintf_func )(char , const char ,...)

typedef void (	bson_malloc_func_p )(size_t)

typedef void (	bson_realloc_func_p )(void *, size_t)

typedef void(*	bson_free_func_p )(void *)

Enumerations
enum	bson_error_t { BSON_SIZE_OVERFLOW = 1 }

enum	bson_validity_t { BSON_VALID = 0, BSON_NOT_UTF8 = ( 1<<1 ), BSON_FIELD_HAS_DOT = ( 1<<2 ), BSON_FIELD_INIT_DOLLAR = ( 1<<3 ), BSON_ALREADY_FINISHED = ( 1<<4 ) }

enum	bson_binary_subtype_t { BSON_BIN_BINARY = 0, BSON_BIN_FUNC = 1, BSON_BIN_BINARY_OLD = 2, BSON_BIN_UUID = 3, BSON_BIN_MD5 = 5, BSON_BIN_USER = 128 }

enum	bson_type { BSON_MINKEY = -1, BSON_EOO = 0, BSON_DOUBLE = 1, BSON_STRING = 2, BSON_OBJECT = 3, BSON_ARRAY = 4, BSON_BINDATA = 5, BSON_UNDEFINED = 6, BSON_OID = 7, BSON_BOOL = 8, BSON_DATE = 9, BSON_NULL = 10, BSON_REGEX = 11, BSON_DBREF = 12, BSON_CODE = 13, BSON_SYMBOL = 14, BSON_CODEWSCOPE = 15, BSON_INT = 16, BSON_TIMESTAMP = 17, BSON_LONG = 18, BSON_DECIMAL = 100, BSON_MAXKEY = 127 }

Functions
SDB_EXPORT bson *	bson_create (void)
	Create a BSON object and in initilize it.

SDB_EXPORT void	bson_dispose (bson *b)
	Free a BSON object.

SDB_EXPORT int	bson_size (const bson *b)
	Size of a BSON object.

SDB_EXPORT int	bson_buffer_size (const bson *b)
	Minimun finished size of an unfinished BSON object.

SDB_EXPORT void	bson_print (const bson *b)
	Print a string representation of a BSON object.

SDB_EXPORT int	bson_sprint_iterator (char *pbuf, int left, bson_iterator *i, char delChar)
	Print a string representation of BSON Iterator to buffer ( without key ).

SDB_EXPORT int	bson_sprint (char buffer, int bufsize, const bson b)
	Print a string representation of a BSON object to buffer.

SDB_EXPORT int	bson_sprint_length_iterator (bson_iterator *i)
	Estimate the length of a bson iterator.

SDB_EXPORT int	bson_sprint_length (const bson *b)
	Estimate the length of the string representation of the specified BSON object.

SDB_EXPORT const char *	bson_data (const bson *b)
	Return a pointer to the raw buffer stored by this bson object.

SDB_EXPORT int	bson_sprint_raw (char *pbuf, int left, const char *data, int isobj)
	Print a string representation of a BSON object.

SDB_EXPORT int	bson_sprint_length_raw (const char *data, int isobj)
	Estimate the length of the string representation of the specified BSON object.

SDB_EXPORT bson_type	bson_find (bson_iterator it, const bson obj, const char *name)
	Advance a bson_iterator to the named field.

SDB_EXPORT bson_iterator *	bson_iterator_create (void)
	Create a bson_iterator on the heap.

SDB_EXPORT void	bson_iterator_dispose (bson_iterator *)
	Free a bson_iterator which build on the heap.

SDB_EXPORT void	bson_iterator_init (bson_iterator i, const bson b)
	Initialize a bson_iterator.

SDB_EXPORT void	bson_iterator_from_buffer (bson_iterator i, const char buffer)
	Initialize a bson iterator from a const char* buffer.

SDB_EXPORT bson_bool_t	bson_iterator_more (const bson_iterator *i)
	Check to see if the bson_iterator has more data.

SDB_EXPORT bson_type	bson_iterator_next (bson_iterator *i)
	Point the iterator at the next BSON object.

SDB_EXPORT bson_type	bson_iterator_type (const bson_iterator *i)
	Get the type of the BSON object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_key (const bson_iterator *i)
	Get the key of the BSON object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_value (const bson_iterator *i)
	Get the value of the BSON object currently pointed to by the iterator.

SDB_EXPORT double	bson_iterator_double (const bson_iterator *i)
	Get the double value of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_int (const bson_iterator *i)
	Get the int value of the BSON object currently pointed to by the iterator.

SDB_EXPORT int64_t	bson_iterator_long (const bson_iterator *i)
	Get the long value of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_decimal_scale (const bson_iterator i, int sign, int *scale)
	Get the decimal's sign and scale of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_decimal_typemod (const bson_iterator i, int typemod)
	Get the decimal's typemod of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_decimal_weight (const bson_iterator i, int weight)
	Get the decimal's weight of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_decimal_size (const bson_iterator i, int size)
	Get the decimal's size of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_decimal (const bson_iterator i, bson_decimal decimal)
	Get the decimal value of the BSON object currently pointed to by the iterator.

SDB_EXPORT bson_timestamp_t	bson_iterator_timestamp (const bson_iterator *i)
	Get the timestamp value of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_timestamp_time (const bson_iterator *i)

SDB_EXPORT int	bson_iterator_timestamp_increment (const bson_iterator *i)

SDB_EXPORT bson_bool_t	bson_iterator_bool (const bson_iterator *i)
	Get the boolean value of the BSON object currently pointed to by the iterator.

double	bson_iterator_double_raw (const bson_iterator *i)
	Get the double value of the BSON object currently pointed to by the iterator.

int	bson_iterator_int_raw (const bson_iterator *i)
	Get the int value of the BSON object currently pointed to by the iterator.

int64_t	bson_iterator_long_raw (const bson_iterator *i)
	Get the long value of the BSON object currently pointed to by the iterator.

bson_bool_t	bson_iterator_bool_raw (const bson_iterator *i)
	Get the bson_bool_t value of the BSON object currently pointed to by the iterator.

SDB_EXPORT bson_oid_t *	bson_iterator_oid (const bson_iterator *i)
	Get the bson_oid_t value of the BSON object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_string (const bson_iterator *i)
	Get the string value of the BSON object currently pointed to by the iterator.

int	bson_iterator_string_len (const bson_iterator *i)
	Get the string length of the BSON object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_code (const bson_iterator *i)
	Get the code value of the BSON object currently pointed to by the iterator.

SDB_EXPORT void	bson_iterator_code_scope (const bson_iterator i, bson scope)
	Calls bson_empty on scope if not a bson_codewscope.

SDB_EXPORT bson_date_t	bson_iterator_date (const bson_iterator *i)
	Get the date value of the BSON object currently pointed to by the iterator.

SDB_EXPORT time_t	bson_iterator_time_t (const bson_iterator *i)
	Get the time value of the BSON object currently pointed to by the iterator.

SDB_EXPORT int	bson_iterator_bin_len (const bson_iterator *i)
	Get the length of the BSON binary object currently pointed to by the iterator.

SDB_EXPORT char	bson_iterator_bin_type (const bson_iterator *i)
	Get the type of the BSON binary object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_bin_data (const bson_iterator *i)
	Get the value of the BSON binary object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_regex (const bson_iterator *i)
	Get the value of the BSON regex object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_regex_opts (const bson_iterator *i)
	Get the options of the BSON regex object currently pointed to by the iterator.

SDB_EXPORT const char *	bson_iterator_dbref (const bson_iterator *i)
	Get the DB name of the BSON DBRef object currently pointed to by the iterator.

SDB_EXPORT bson_oid_t *	bson_iterator_dbref_oid (const bson_iterator *i)
	Get the DB OID of the BSON DBRef object currently pointed to by the iterator.

SDB_EXPORT void	bson_iterator_subobject (const bson_iterator i, bson sub)
	Get the BSON subobject currently pointed to by the iterator.

SDB_EXPORT void	bson_iterator_subiterator (const bson_iterator i, bson_iterator sub)
	Get a bson_iterator that on the BSON subobject.

SDB_EXPORT void	bson_oid_from_string (bson_oid_t oid, const char str)
	Create a bson_oid_t from a string.

SDB_EXPORT void	bson_oid_to_string (const bson_oid_t oid, char str)
	Create a string representation of the bson_oid_t.

SDB_EXPORT void	bson_oid_gen (bson_oid_t *oid)
	Create a bson_oid object.

SDB_EXPORT void	bson_set_oid_fuzz (int(*func)(void))
	Set a function to be used to generate the second four bytes of an object id.

SDB_EXPORT void	bson_set_oid_inc (int(*func)(void))
	Set a function to be used to generate the incrementing part of an object id (last four bytes).

SDB_EXPORT time_t	bson_oid_generated_time (bson_oid_t *oid)
	Get the time a bson_oid_t was created.

SDB_EXPORT void	bson_init (bson *b)
	Initialize a new bson object.

int	bson_init_data (bson b, const char data)
	Initialize a BSON object, and point its data pointer to the provided char*.

int	bson_init_finished_data (bson b, const char data)
	Initialize a BSON object, and point its data pointer to the provided char*, then finish building this BSON object.

SDB_EXPORT void	bson_init_size (bson *b, int size)
	Initialize a BSON object, and set its buffer to the given size.

int	bson_ensure_space (bson *b, const int bytesNeeded)
	Grow a bson object.

SDB_EXPORT int	bson_finish (bson *b)
	Finalize a bson object.

SDB_EXPORT void	bson_destroy (bson *b)
	Destroy a bson object.

SDB_EXPORT bson *	bson_empty (bson *obj)
	Returns a pointer to a static empty BSON object.

SDB_EXPORT bson_bool_t	bson_is_empty (bson *obj)
	Check BSON object is empty or not.

SDB_EXPORT int	bson_copy (bson out, const bson in)
	Make a complete copy of the a BSON object.

SDB_EXPORT int	bson_init_by_reset (bson *obj)
	Reset bson initialization, this can reuse bson's memory.

SDB_EXPORT int	bson_append_oid (bson b, const char name, const bson_oid_t *oid)
	Append a previously created bson_oid_t to a bson object.

SDB_EXPORT int	bson_append_new_oid (bson b, const char name)
	Append a bson_oid_t to a bson.

SDB_EXPORT int	bson_append_int (bson b, const char name, const int i)
	Append an int to a bson.

SDB_EXPORT int	bson_append_long (bson b, const char name, const int64_t i)
	Append an long to a bson.

SDB_EXPORT int	bson_append_decimal (bson b, const char name, const bson_decimal *decimal)
	Append an decimal to a bson.

SDB_EXPORT int	bson_append_decimal2 (bson b, const char name, const char *value, int precision, int scale)
	Append an decimal to a bson.

SDB_EXPORT int	bson_append_decimal3 (bson b, const char name, const char *value)
	Append an decimal to a bson.

SDB_EXPORT int	bson_append_double (bson b, const char name, const double d)
	Append an double to a bson.

SDB_EXPORT int	bson_append_string (bson b, const char name, const char *str)
	Append a string to a bson.

SDB_EXPORT int	bson_append_string_n (bson b, const char name, const char *str, int len)
	Append len bytes of a string to a bson.

SDB_EXPORT int	bson_append_symbol (bson b, const char name, const char *str)
	Append a symbol to a bson.

SDB_EXPORT int	bson_append_symbol_n (bson b, const char name, const char *str, int len)
	Append len bytes of a symbol to a bson.

SDB_EXPORT int	bson_append_code (bson b, const char name, const char *str)
	Append code to a bson.

SDB_EXPORT int	bson_append_code_n (bson b, const char name, const char *str, int len)
	Append len bytes of code to a bson.

SDB_EXPORT int	bson_append_code_w_scope (bson b, const char name, const char code, const bson scope)
	Append code to a bson with scope.

SDB_EXPORT int	bson_append_code_w_scope_n (bson b, const char name, const char code, int size, const bson scope)
	Append len bytes of code to a bson with scope.

SDB_EXPORT int	bson_append_binary (bson b, const char name, char type, const char *str, int len)
	Append binary data to a bson.

SDB_EXPORT int	bson_append_bool (bson b, const char name, const bson_bool_t v)
	Append a bson_bool_t to a bson.

SDB_EXPORT int	bson_append_null (bson b, const char name)
	Append a null value to a bson.

SDB_EXPORT int	bson_append_undefined (bson b, const char name)
	Append an undefined value to a bson.

SDB_EXPORT int	bson_append_regex (bson b, const char name, const char pattern, const char opts)
	Append a regex value to a bson.

SDB_EXPORT int	bson_append_minkey (bson b, const char name)
	Append a minkey to a bson.

SDB_EXPORT int	bson_append_maxkey (bson b, const char name)
	Append a maxkey to a bson.

SDB_EXPORT int	bson_append_bson (bson b, const char name, const bson *bson)
	Append bson data to a bson.

SDB_EXPORT int	bson_append_array (bson b, const char name, const bson *bson)
	Append array data to a bson.

SDB_EXPORT int	bson_append_element (bson b, const char name_or_null, const bson_iterator *elem)
	Append a BSON element to a bson from the current point of an iterator.

SDB_EXPORT int	bson_append_elements (bson dst, const bson src)
	Append all the elements of a bson to another bson.

SDB_EXPORT int	bson_append_timestamp (bson b, const char name, bson_timestamp_t *ts)
	Append a bson_timestamp_t value to a bson.

SDB_EXPORT int	bson_append_timestamp2 (bson b, const char name, int time, int increment)
	Append the timestamp value to a bson.

SDB_EXPORT int	bson_append_date (bson b, const char name, bson_date_t millis)
	Append a bson_date_t value to a bson.

SDB_EXPORT int	bson_append_time_t (bson b, const char name, time_t secs)
	Append a time_t value to a bson.

SDB_EXPORT int	bson_append_start_object (bson b, const char name)
	Start appending a new object to a bson.

SDB_EXPORT int	bson_append_start_array (bson b, const char name)
	Start appending a new array to a bson.

SDB_EXPORT int	bson_append_finish_object (bson *b)
	Finish appending a new object or array to a bson.

SDB_EXPORT int	bson_append_finish_array (bson *b)
	Finish appending a new object or array to a bson.

void	bson_numstr (char *str, int i)

void	bson_incnumstr (char *str)

void	bson_set_malloc_func (bson_malloc_func_p func)

void	bson_set_realloc_func (bson_realloc_func_p func)

void	bson_set_free_func (bson_free_func_p func)

SDB_EXPORT void	bson_free (void *ptr)

SDB_EXPORT void *	bson_malloc (int size)
	Allocates memory and checks return value, exiting fatally if malloc() fails.

void *	bson_realloc (void *ptr, int size)
	Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails.

SDB_EXPORT bson_err_handler	set_bson_err_handler (bson_err_handler func)
	Set a function for error handling.

void	bson_fatal (int ok)
	Exit fatally.

void	bson_fatal_msg (int ok, const char *msg)
	Exit fatally with an error message.

void	bson_builder_error (bson *b)
	Invoke the error handler, but do not exit.

SDB_EXPORT double	bson_int64_to_double (int64_t i64)
	Cast an int64_t to double.

SDB_EXPORT void	bson_swap_endian32 (void outp, const void inp)

SDB_EXPORT void	bson_swap_endian64 (void outp, const void inp)

SDB_EXPORT bson_bool_t	bson_is_inf (double d, int *pSign)

SDB_EXPORT void	bson_set_js_compatibility (int compatible)
	when this value is not zero, the bson_print method will show the string which is the same with that shows in sdb shell.

SDB_EXPORT int	bson_get_js_compatibility ()
	get whether bson_print method will show the string which is the same with that shows in sdb shell or not

Variables
bson_printf_func	bson_printf

bson_fprintf_func	bson_fprintf

bson_sprintf_func	bson_sprintf

bson_printf_func	bson_errprintf

Detailed Description

BSON Declarations.

Enumeration Type Documentation

enum bson_binary_subtype_t

Enumerator:

BSON_BIN_BINARY	Binary / Generic .
BSON_BIN_FUNC	Function .
BSON_BIN_BINARY_OLD	Binary(Old) .
BSON_BIN_UUID	UUID (Old).
BSON_BIN_MD5	MD5 .
BSON_BIN_USER	User defined.

enum bson_error_t

Enumerator:

BSON_SIZE_OVERFLOW

Trying to create a BSON object larger than INT_MAX.

enum bson_type

Enumerator:

BSON_MINKEY	Min key.
BSON_EOO	End of object.
BSON_DOUBLE	Floatint point.
BSON_STRING	UTF-8 string.
BSON_OBJECT	Embedded document.
BSON_ARRAY	Array.
BSON_BINDATA	Binary data.
BSON_UNDEFINED	Undefined-Deprecated.
BSON_OID	Objectid.
BSON_BOOL	BOOlean.
BSON_DATE	UTC datetime.
BSON_NULL	Null value.
BSON_REGEX	Regular expression.
BSON_DBREF	DBPointer-Deprecated.
BSON_CODE	JavaScript code.
BSON_SYMBOL	Symbol-Deprecated.
BSON_CODEWSCOPE	JavaScript code w/scope.
BSON_INT	32-bit integer.
BSON_TIMESTAMP	Timestamp.
BSON_LONG	64-bit integer.
BSON_MAXKEY	decimal type Max key.

enum bson_validity_t

Enumerator:

BSON_VALID	BSON is valid and UTF-8 compliant.
BSON_NOT_UTF8	A key or a string is not valid UTF-8.
BSON_FIELD_HAS_DOT	Warning: key contains '. ' character.
BSON_FIELD_INIT_DOLLAR	Warning: key starts with '$' character.
BSON_ALREADY_FINISHED	Trying to modify a finished BSON object.

Function Documentation

SDB_EXPORT int bson_append_array	(	bson *	b,
		const char *	name,
		const bson *	bson
	)

Append array data to a bson.

Parameters

b	the bson to append to.
name	the key for the bson data.
bson	the bson array to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_binary	(	bson *	b,
		const char *	name,
		char	type,
		const char *	str,
		int	len
	)

Append binary data to a bson.

Parameters

b	the bson to append to.
name	the key for the data.
type	the binary data type.
str	the binary data.
len	the length of the data.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_bool	(	bson *	b,
		const char *	name,
		const bson_bool_t	v
	)

Append a bson_bool_t to a bson.

Parameters

b	the bson to append to.
name	the key for the boolean value.
v	the bson_bool_t to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_bson	(	bson *	b,
		const char *	name,
		const bson *	bson
	)

Append bson data to a bson.

Parameters

b	the bson to append to.
name	the key for the bson data.
bson	the bson object to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_code	(	bson *	b,
		const char *	name,
		const char *	str
	)

Append code to a bson.

Parameters

b	the bson to append to.
name	the key for the code.
str	the code to append.
len	the number of bytes from str to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_code_n	(	bson *	b,
		const char *	name,
		const char *	str,
		int	len
	)

Append len bytes of code to a bson.

Parameters

b	the bson to append to.
name	the key for the code.
str	the code to append.
len	the number of bytes from str to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_code_w_scope	(	bson *	b,
		const char *	name,
		const char *	code,
		const bson *	scope
	)

Append code to a bson with scope.

Parameters

b	the bson to append to.
name	the key for the code.
str	the string to append.
scope	a BSON object containing the scope.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_code_w_scope_n	(	bson *	b,
		const char *	name,
		const char *	code,
		int	size,
		const bson *	scope
	)

Append len bytes of code to a bson with scope.

Parameters

b	the bson to append to.
name	the key for the code.
str	the string to append.
len	the number of bytes from str to append.
scope	a BSON object containing the scope.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_date	(	bson *	b,
		const char *	name,
		bson_date_t	millis
	)

Append a bson_date_t value to a bson.

Parameters

b	the bson to append to.
name	the key for the date value.
millis	the bson_date_t to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_decimal	(	bson *	b,
		const char *	name,
		const bson_decimal *	decimal
	)

Append an decimal to a bson.

Parameters

b	the bson to append to.
name	the key for the decimal.
decimal	the decimal to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_decimal2	(	bson *	b,
		const char *	name,
		const char *	value,
		int	precision,
		int	scale
	)

Append an decimal to a bson.

Parameters

b	the bson to append to.
name	the key for the decimal.
value	the string format of the decimal to append.
precision,the	precision of decimal
scale,the	scale of decimal

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_decimal3	(	bson *	b,
		const char *	name,
		const char *	value
	)

Append an decimal to a bson.

Parameters

b	the bson to append to.
name	the key for the decimal.
value	the string format of the decimal to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_double	(	bson *	b,
		const char *	name,
		const double	d
	)

Append an double to a bson.

Parameters

b	the bson to append to.
name	the key for the double.
d	the double to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_element	(	bson *	b,
		const char *	name_or_null,
		const bson_iterator *	elem
	)

Append a BSON element to a bson from the current point of an iterator.

Parameters

b	the bson to append to.
name_or_null	the key for the BSON element, or NULL.
elem	the bson_iterator.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_elements	(	bson *	dst,
		const bson *	src
	)

Append all the elements of a bson to another bson.

Parameters

dst	the destination bson.
src	the source bson.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_finish_array ( bson * b )

Finish appending a new object or array to a bson.

This is simply an alias for bson_append_finish_object.

Parameters

b	the bson to append to.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_finish_object ( bson * b )

Finish appending a new object or array to a bson.

Parameters

b	the bson to append to.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_int	(	bson *	b,
		const char *	name,
		const int	i
	)

Append an int to a bson.

Parameters

b	the bson to append to.
name	the key for the int.
i	the int to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_long	(	bson *	b,
		const char *	name,
		const int64_t	i
	)

Append an long to a bson.

Parameters

b	the bson to append to.
name	the key for the long.
i	the long to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_maxkey	(	bson *	b,
		const char *	name
	)

Append a maxkey to a bson.

Parameters

b	the bson to append to.
name	the key for the maxkey.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_minkey	(	bson *	b,
		const char *	name
	)

Append a minkey to a bson.

Parameters

b	the bson to append to.
name	the key for the minkey.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_new_oid	(	bson *	b,
		const char *	name
	)

Append a bson_oid_t to a bson.

Parameters

b	the bson to append to.
name	the key for the bson_oid_t.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_null	(	bson *	b,
		const char *	name
	)

Append a null value to a bson.

Parameters

b	the bson to append to.
name	the key for the null value.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_oid	(	bson *	b,
		const char *	name,
		const bson_oid_t *	oid
	)

Append a previously created bson_oid_t to a bson object.

Parameters

b	the bson to append to.
name	the key for the bson_oid_t.
oid	the bson_oid_t to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_regex	(	bson *	b,
		const char *	name,
		const char *	pattern,
		const char *	opts
	)

Append a regex value to a bson.

Parameters

b	the bson to append to.
name	the key for the regex value.
pattern	the regex pattern to append.
the	regex options.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_start_array	(	bson *	b,
		const char *	name
	)

Start appending a new array to a bson.

Parameters

b	the bson to append to.
name	the name of the new array.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_start_object	(	bson *	b,
		const char *	name
	)

Start appending a new object to a bson.

Parameters

b	the bson to append to.
name	the name of the new object.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_string	(	bson *	b,
		const char *	name,
		const char *	str
	)

Append a string to a bson.

Parameters

b	the bson to append to.
name	the key for the string.
str	the string to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_string_n	(	bson *	b,
		const char *	name,
		const char *	str,
		int	len
	)

Append len bytes of a string to a bson.

Parameters

b	the bson to append to.
name	the key for the string.
str	the string to append.
len	the number of bytes from str to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_symbol	(	bson *	b,
		const char *	name,
		const char *	str
	)

Append a symbol to a bson.

Parameters

b	the bson to append to.
name	the key for the symbol.
str	the symbol to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_symbol_n	(	bson *	b,
		const char *	name,
		const char *	str,
		int	len
	)

Append len bytes of a symbol to a bson.

Parameters

b	the bson to append to.
name	the key for the symbol.
str	the symbol to append.
len	the number of bytes from str to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_time_t	(	bson *	b,
		const char *	name,
		time_t	secs
	)

Append a time_t value to a bson.

Parameters

b	the bson to append to.
name	the key for the date value.
secs	the time_t to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_timestamp	(	bson *	b,
		const char *	name,
		bson_timestamp_t *	ts
	)

Append a bson_timestamp_t value to a bson.

Parameters

b	the bson to append to.
name	the key for the timestampe value.
ts	the bson_timestamp_t value to append.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_timestamp2	(	bson *	b,
		const char *	name,
		int	time,
		int	increment
	)

Append the timestamp value to a bson.

Parameters

b	the bson to append to.
name	the key for the timestampe value.
time	seconds since epoch.
increment	microseconds in range of [0us, 999999us].

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_append_undefined	(	bson *	b,
		const char *	name
	)

Append an undefined value to a bson.

Parameters

b	the bson to append to.
name	the key for the undefined value.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_buffer_size ( const bson * b )

Minimun finished size of an unfinished BSON object.

Parameters

b	the BSON object.

Returns: the BSON object's minimun finished size.

void bson_builder_error ( bson * b )

Invoke the error handler, but do not exit.

Parameters

b	the buffer object.

SDB_EXPORT int bson_copy	(	bson *	out,
		const bson *	in
	)

Make a complete copy of the a BSON object.

The source bson object must be in a finished state; otherwise, the copy will fail.

Parameters

out	the copy destination BSON object.
in	the copy source BSON object.

SDB_EXPORT bson* bson_create ( void )

Create a BSON object and in initilize it.

Returns: the newly created bson object.

SDB_EXPORT const char* bson_data ( const bson * b )

Return a pointer to the raw buffer stored by this bson object.

Parameters

b	a BSON object

SDB_EXPORT void bson_destroy ( bson * b )

Destroy a bson object.

Parameters

b	the bson object to destroy.

SDB_EXPORT void bson_dispose ( bson * b )

Free a BSON object.

Parameters

b	the BSON object.

SDB_EXPORT bson* bson_empty ( bson * obj )

Returns a pointer to a static empty BSON object.

Parameters

obj	the BSON object to initialize.

Returns: the empty initialized BSON object.

int bson_ensure_space	(	bson *	b,
		const int	bytesNeeded
	)

Grow a bson object.

Parameters

b	the bson to grow.
bytesNeeded	the additional number of bytes needed.

Returns: BSON_OK or BSON_ERROR with the bson error object set. Exits if allocation fails.

void bson_fatal ( int ok )

Exit fatally.

Parameters

ok	exits if ok is equal to 0.

void bson_fatal_msg	(	int	ok,
		const char *	msg
	)

Exit fatally with an error message.

Parameters

ok	exits if ok is equal to 0.
msg	prints to stderr before exiting.

SDB_EXPORT bson_type bson_find	(	bson_iterator *	it,
		const bson *	obj,
		const char *	name
	)

Advance a bson_iterator to the named field.

Parameters

it	the bson_iterator to use.
obj	the BSON object to use.
name	the name of the field to find.

Returns: the type of the found object or BSON_EOO if it is not found.

SDB_EXPORT int bson_finish ( bson * b )

Finalize a bson object.

Parameters

b	the bson object to finalize.

Returns: the standard error code. To deallocate memory, call bson_destroy on the bson object.

SDB_EXPORT void bson_init ( bson * b )

Initialize a new bson object.

If not created with bson_new, you must initialize each new bson object using this function.

Note: When finished, you must pass the bson object to bson_destroy( ).

SDB_EXPORT int bson_init_by_reset ( bson * obj )

Reset bson initialization, this can reuse bson's memory.

Parameters

in	the BSON object.

int bson_init_data	(	bson *	b,
		const char *	data
	)

Initialize a BSON object, and point its data pointer to the provided char*.

Parameters

b	the BSON object to initialize.
data	the raw BSON data.

Returns: BSON_OK or BSON_ERROR.

int bson_init_finished_data	(	bson *	b,
		const char *	data
	)

Initialize a BSON object, and point its data pointer to the provided char*, then finish building this BSON object.

Parameters

b	the BSON object to initialize.
data	the raw BSON data.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT void bson_init_size	(	bson *	b,
		int	size
	)

Initialize a BSON object, and set its buffer to the given size.

Parameters

b	the BSON object to initialize.
size	the initial size of the buffer.

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT double bson_int64_to_double ( int64_t i64 )

Cast an int64_t to double.

This is necessary for embedding in certain environments.

SDB_EXPORT bson_bool_t bson_is_empty ( bson * obj )

Check BSON object is empty or not.

Parameters

obj	the BSON object.

Returns: true or false.

SDB_EXPORT const char* bson_iterator_bin_data ( const bson_iterator * i )

Get the value of the BSON binary object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON binary object.

SDB_EXPORT int bson_iterator_bin_len ( const bson_iterator * i )

Get the length of the BSON binary object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the length of the current BSON binary object.

SDB_EXPORT char bson_iterator_bin_type ( const bson_iterator * i )

Get the type of the BSON binary object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the type of the current BSON binary object.

SDB_EXPORT bson_bool_t bson_iterator_bool ( const bson_iterator * i )

Get the boolean value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

bson_bool_t bson_iterator_bool_raw ( const bson_iterator * i )

Get the bson_bool_t value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT const char* bson_iterator_code ( const bson_iterator * i )

Get the code value of the BSON object currently pointed to by the iterator.

Works with bson_code, bson_codewscope, and BSON_STRING returns NULL for everything else.

Parameters

i	the bson_iterator

Returns: the code value of the current BSON object.

SDB_EXPORT void bson_iterator_code_scope	(	const bson_iterator *	i,
		bson *	scope
	)

Calls bson_empty on scope if not a bson_codewscope.

Parameters

i	the bson_iterator.
scope	the bson scope.

SDB_EXPORT bson_iterator* bson_iterator_create ( void )

Create a bson_iterator on the heap.

Returns: the newly created iterator.

SDB_EXPORT bson_date_t bson_iterator_date ( const bson_iterator * i )

Get the date value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the date value of the current BSON object.

SDB_EXPORT const char* bson_iterator_dbref ( const bson_iterator * i )

Get the DB name of the BSON DBRef object currently pointed to by the iterator.

Parameters

i	the bson_iterator.

Returns: the DB name of the current BSON DBRef object.

SDB_EXPORT bson_oid_t* bson_iterator_dbref_oid ( const bson_iterator * i )

Get the DB OID of the BSON DBRef object currently pointed to by the iterator.

Parameters

i	the bson_iterator.

Returns: the DB OID of the current BSON DBRef object.

SDB_EXPORT int bson_iterator_decimal	(	const bson_iterator *	i,
		bson_decimal *	decimal
	)

Get the decimal value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_iterator_decimal_scale	(	const bson_iterator *	i,
		int *	sign,
		int *	scale
	)

Get the decimal's sign and scale of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_iterator_decimal_size	(	const bson_iterator *	i,
		int *	size
	)

Get the decimal's size of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_iterator_decimal_typemod	(	const bson_iterator *	i,
		int *	typemod
	)

Get the decimal's typemod of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT int bson_iterator_decimal_weight	(	const bson_iterator *	i,
		int *	weight
	)

Get the decimal's weight of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: BSON_OK or BSON_ERROR.

SDB_EXPORT double bson_iterator_double ( const bson_iterator * i )

Get the double value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

double bson_iterator_double_raw ( const bson_iterator * i )

Get the double value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT void bson_iterator_from_buffer	(	bson_iterator *	i,
		const char *	buffer
	)

Initialize a bson iterator from a const char* buffer.

Note that this is mostly used internally.

Parameters

i	the bson_iterator to initialize.
buffer	the buffer to point to.

SDB_EXPORT void bson_iterator_init	(	bson_iterator *	i,
		const bson *	b
	)

Initialize a bson_iterator.

Parameters

i	the bson_iterator to initialize.
bson	the BSON object to associate with the iterator.

SDB_EXPORT int bson_iterator_int ( const bson_iterator * i )

Get the int value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

int bson_iterator_int_raw ( const bson_iterator * i )

Get the int value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT const char* bson_iterator_key ( const bson_iterator * i )

Get the key of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the key of the current BSON object.

SDB_EXPORT int64_t bson_iterator_long ( const bson_iterator * i )

Get the long value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

int64_t bson_iterator_long_raw ( const bson_iterator * i )

Get the long value of the BSON object currently pointed to by the iterator.

Assumes the correct type is used.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT bson_bool_t bson_iterator_more ( const bson_iterator * i )

Check to see if the bson_iterator has more data.

Parameters

i	the iterator.

Returns: returns true if there is more data.

SDB_EXPORT bson_type bson_iterator_next ( bson_iterator * i )

Point the iterator at the next BSON object.

Parameters

i	the bson_iterator.

Returns: the type of the next BSON object.

SDB_EXPORT bson_oid_t* bson_iterator_oid ( const bson_iterator * i )

Get the bson_oid_t value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT const char* bson_iterator_regex ( const bson_iterator * i )

Get the value of the BSON regex object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON regex object.

SDB_EXPORT const char* bson_iterator_regex_opts ( const bson_iterator * i )

Get the options of the BSON regex object currently pointed to by the iterator.

Parameters

i	the bson_iterator.

Returns: the options of the current BSON regex object.

SDB_EXPORT const char* bson_iterator_string ( const bson_iterator * i )

Get the string value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

int bson_iterator_string_len ( const bson_iterator * i )

Get the string length of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the length of the current BSON object.

SDB_EXPORT void bson_iterator_subiterator	(	const bson_iterator *	i,
		bson_iterator *	sub
	)

Get a bson_iterator that on the BSON subobject.

Parameters

i	the bson_iterator.
sub	the iterator to point at the BSON subobject.

SDB_EXPORT void bson_iterator_subobject	(	const bson_iterator *	i,
		bson *	sub
	)

Get the BSON subobject currently pointed to by the iterator.

Parameters

i	the bson_iterator.
sub	the BSON subobject destination.

SDB_EXPORT time_t bson_iterator_time_t ( const bson_iterator * i )

Get the time value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the time value of the current BSON object.

SDB_EXPORT bson_timestamp_t bson_iterator_timestamp ( const bson_iterator * i )

Get the timestamp value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT bson_type bson_iterator_type ( const bson_iterator * i )

Get the type of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the type of the current BSON object.

SDB_EXPORT const char* bson_iterator_value ( const bson_iterator * i )

Get the value of the BSON object currently pointed to by the iterator.

Parameters

i	the bson_iterator

Returns: the value of the current BSON object.

SDB_EXPORT void* bson_malloc ( int size )

Allocates memory and checks return value, exiting fatally if malloc() fails.

Parameters

size	bytes to allocate.

Returns: a pointer to the allocated memory.

See Also: malloc(3)

SDB_EXPORT void bson_oid_from_string	(	bson_oid_t *	oid,
		const char *	str
	)

Create a bson_oid_t from a string.

Parameters

oid	the bson_oid_t destination.
str	a null terminated string comprised of at least 24 hex chars.

SDB_EXPORT void bson_oid_gen ( bson_oid_t * oid )

Create a bson_oid object.

Parameters

oid	the destination for the newly created bson_oid_t.

SDB_EXPORT time_t bson_oid_generated_time ( bson_oid_t * oid )

Get the time a bson_oid_t was created.

Parameters

oid	the bson_oid_t.

SDB_EXPORT void bson_oid_to_string	(	const bson_oid_t *	oid,
		char *	str
	)

Create a string representation of the bson_oid_t.

Parameters

oid	the bson_oid_t source.
str	the string representation destination.

SDB_EXPORT void bson_print ( const bson * b )

Print a string representation of a BSON object.

Parameters

b	the BSON object to print.

void* bson_realloc	(	void *	ptr,
		int	size
	)

Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails.

Parameters

ptr	pointer to the space to reallocate.
size	bytes to allocate.

Returns: a pointer to the allocated memory.

See Also: realloc()

SDB_EXPORT void bson_set_oid_fuzz ( int(*)(void) func )

Set a function to be used to generate the second four bytes of an object id.

Parameters

func	a pointer to a function that returns an int.

SDB_EXPORT void bson_set_oid_inc ( int(*)(void) func )

Set a function to be used to generate the incrementing part of an object id (last four bytes).

If you need thread-safety in generating object ids, you should set this function.

Parameters

func	a pointer to a function that returns an int.

SDB_EXPORT int bson_size ( const bson * b )

Size of a BSON object.

Parameters

b	the BSON object.

Returns: the size.

SDB_EXPORT int bson_sprint	(	char *	buffer,
		int	bufsize,
		const bson *	b
	)

Print a string representation of a BSON object to buffer.

Parameters

b	the BSON object to print.

SDB_EXPORT int bson_sprint_iterator	(	char **	pbuf,
		int *	left,
		bson_iterator *	i,
		char	delChar
	)

Print a string representation of BSON Iterator to buffer ( without key ).

Parameters

i	the BSON Iterator to print.
delChar	the string delimiter.

SDB_EXPORT int bson_sprint_length ( const bson * b )

Estimate the length of the string representation of the specified BSON object.

The actual space needed will be less than or equal to the estimated value.

Parameters

b	the BSON object to print.

Returns: estimated length of the string representation (> 0) if succeed, 0 if failed

SDB_EXPORT int bson_sprint_length_iterator ( bson_iterator * i )

Estimate the length of a bson iterator.

Parameters

b	the BSON Iterator, note this doesn't include key

Returns: estimated length of the string representation if succeed, 0 if failed

SDB_EXPORT int bson_sprint_length_raw	(	const char *	data,
		int	isobj
	)

Estimate the length of the string representation of the specified BSON object.

The actual space needed will be less than or equal to the estimated value.

Parameters

data	the raw data to print.
isobj	1 if the raw data is a object, 0 if array

Returns: estimated length of the string representation (> 0) if succeed, 0 if failed

SDB_EXPORT int bson_sprint_raw	(	char **	pbuf,
		int *	left,
		const char *	data,
		int	isobj
	)

Print a string representation of a BSON object.

Parameters

bson	the raw data to print.
depth	the depth to recurse the object.x Print a string representation of a BSON object to buffer.
bson	the raw data to print.
depth	the depth to recurse the object.x

Returns: 0 for failure; 1 for success

SDB_EXPORT bson_err_handler set_bson_err_handler ( bson_err_handler func )

Set a function for error handling.

Parameters

func	a bson_err_handler function.

Returns: the old error handling function, or NULL.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation