bson.h File Reference

BSON Declarations. More...

#include <time.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.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	MONGO_INLINE   static
#define	MONGO_EXPORT   __declspec(dllimport)
#define	MONGO_EXTERN_C_START
#define	MONGO_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_big_endian64(out, in)   ( bson_swap_endian64(out, in) )
#define	bson_big_endian32(out, in)   ( bson_swap_endian32(out, in) )
#define	BSON_OK   0
#define	BSON_ERROR   -1

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 *,...)

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_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 }

Functions
MONGO_EXPORT bson *	bson_create (void)
MONGO_EXPORT void	bson_dispose (bson *b)
MONGO_EXPORT int	bson_size (const bson *b)
	Size of a BSON object.
MONGO_EXPORT int	bson_buffer_size (const bson *b)
MONGO_EXPORT void	bson_print (const bson *b)
	Print a string representation of a BSON object.
MONGO_EXPORT const char *	bson_data (const bson *b)
	Return a pointer to the raw buffer stored by this bson object.
MONGO_EXPORT void	bson_print_raw (const char *bson, int depth)
	Print a string representation of a BSON object.
MONGO_EXPORT bson_type	bson_find (bson_iterator *it, const bson *obj, const char *name)
	Advance a bson_iterator to the named field.
MONGO_EXPORT bson_iterator *	bson_iterator_create (void)
MONGO_EXPORT void	bson_iterator_dispose (bson_iterator *)
MONGO_EXPORT void	bson_iterator_init (bson_iterator *i, const bson *b)
	Initialize a bson_iterator.
MONGO_EXPORT void	bson_iterator_from_buffer (bson_iterator *i, const char *buffer)
	Initialize a bson iterator from a const char* buffer.
MONGO_EXPORT bson_bool_t	bson_iterator_more (const bson_iterator *i)
	Check to see if the bson_iterator has more data.
MONGO_EXPORT bson_type	bson_iterator_next (bson_iterator *i)
	Point the iterator at the next BSON object.
MONGO_EXPORT bson_type	bson_iterator_type (const bson_iterator *i)
	Get the type of the BSON object currently pointed to by the iterator.
MONGO_EXPORT const char *	bson_iterator_key (const bson_iterator *i)
	Get the key of the BSON object currently pointed to by the iterator.
MONGO_EXPORT const char *	bson_iterator_value (const bson_iterator *i)
	Get the value of the BSON object currently pointed to by the iterator.
MONGO_EXPORT double	bson_iterator_double (const bson_iterator *i)
	Get the double value of the BSON object currently pointed to by the iterator.
MONGO_EXPORT int	bson_iterator_int (const bson_iterator *i)
	Get the int value of the BSON object currently pointed to by the iterator.
MONGO_EXPORT int64_t	bson_iterator_long (const bson_iterator *i)
	Get the long value of the BSON object currently pointed to by the iterator.
MONGO_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.
MONGO_EXPORT int	bson_iterator_timestamp_time (const bson_iterator *i)
MONGO_EXPORT int	bson_iterator_timestamp_increment (const bson_iterator *i)
MONGO_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.
MONGO_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.
MONGO_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.
MONGO_EXPORT const char *	bson_iterator_code (const bson_iterator *i)
	Get the code value of the BSON object currently pointed to by the iterator.
MONGO_EXPORT void	bson_iterator_code_scope (const bson_iterator *i, bson *scope)
	Calls bson_empty on scope if not a bson_codewscope.
MONGO_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.
MONGO_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.
MONGO_EXPORT int	bson_iterator_bin_len (const bson_iterator *i)
	Get the length of the BSON binary object currently pointed to by the iterator.
MONGO_EXPORT char	bson_iterator_bin_type (const bson_iterator *i)
	Get the type of the BSON binary object currently pointed to by the iterator.
MONGO_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.
MONGO_EXPORT const char *	bson_iterator_regex (const bson_iterator *i)
	Get the value of the BSON regex object currently pointed to by the iterator.
MONGO_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.
MONGO_EXPORT void	bson_iterator_subobject (const bson_iterator *i, bson *sub)
	Get the BSON subobject currently pointed to by the iterator.
MONGO_EXPORT void	bson_iterator_subiterator (const bson_iterator *i, bson_iterator *sub)
	Get a bson_iterator that on the BSON subobject.
MONGO_EXPORT void	bson_oid_from_string (bson_oid_t *oid, const char *str)
	Create a bson_oid_t from a string.
MONGO_EXPORT void	bson_oid_to_string (const bson_oid_t *oid, char *str)
	Create a string representation of the bson_oid_t.
MONGO_EXPORT void	bson_oid_gen (bson_oid_t *oid)
	Create a bson_oid object.
MONGO_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.
MONGO_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).
MONGO_EXPORT time_t	bson_oid_generated_time (bson_oid_t *oid)
	Get the time a bson_oid_t was created.
MONGO_EXPORT void	bson_init (bson *b)
	Initialize a new bson object.
int	bson_init_data (bson *b, char *data)
	Initialize a BSON object, and point its data pointer to the provided char*.
int	bson_init_finished_data (bson *b, char *data)
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.
MONGO_EXPORT int	bson_finish (bson *b)
	Finalize a bson object.
MONGO_EXPORT void	bson_destroy (bson *b)
	Destroy a bson object.
MONGO_EXPORT bson *	bson_empty (bson *obj)
	Returns a pointer to a static empty BSON object.
MONGO_EXPORT int	bson_copy (bson *out, const bson *in)
	Make a complete copy of the a BSON object.
MONGO_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.
MONGO_EXPORT int	bson_append_new_oid (bson *b, const char *name)
	Append a bson_oid_t to a bson.
MONGO_EXPORT int	bson_append_int (bson *b, const char *name, const int i)
	Append an int to a bson.
MONGO_EXPORT int	bson_append_long (bson *b, const char *name, const int64_t i)
	Append an long to a bson.
MONGO_EXPORT int	bson_append_double (bson *b, const char *name, const double d)
	Append an double to a bson.
MONGO_EXPORT int	bson_append_string (bson *b, const char *name, const char *str)
	Append a string to a bson.
MONGO_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.
MONGO_EXPORT int	bson_append_symbol (bson *b, const char *name, const char *str)
	Append a symbol to a bson.
MONGO_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.
MONGO_EXPORT int	bson_append_code (bson *b, const char *name, const char *str)
	Append code to a bson.
MONGO_EXPORT int	bson_append_code_n (bson *b, const char *name, const char *str, int len)
	Append len bytes of code to a bson.
MONGO_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.
MONGO_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.
MONGO_EXPORT int	bson_append_binary (bson *b, const char *name, char type, const char *str, int len)
	Append binary data to a bson.
MONGO_EXPORT int	bson_append_bool (bson *b, const char *name, const bson_bool_t v)
	Append a bson_bool_t to a bson.
MONGO_EXPORT int	bson_append_null (bson *b, const char *name)
	Append a null value to a bson.
MONGO_EXPORT int	bson_append_undefined (bson *b, const char *name)
	Append an undefined value to a bson.
MONGO_EXPORT int	bson_append_regex (bson *b, const char *name, const char *pattern, const char *opts)
	Append a regex value to a bson.
MONGO_EXPORT int	bson_append_bson (bson *b, const char *name, const bson *bson)
	Append bson data to a bson.
MONGO_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.
MONGO_EXPORT int	bson_append_timestamp (bson *b, const char *name, bson_timestamp_t *ts)
	Append a bson_timestamp_t value to a bson.
MONGO_EXPORT int	bson_append_timestamp2 (bson *b, const char *name, int time, int increment)
MONGO_EXPORT int	bson_append_date (bson *b, const char *name, bson_date_t millis)
	Append a bson_date_t value to a bson.
MONGO_EXPORT int	bson_append_time_t (bson *b, const char *name, time_t secs)
	Append a time_t value to a bson.
MONGO_EXPORT int	bson_append_start_object (bson *b, const char *name)
	Start appending a new object to a bson.
MONGO_EXPORT int	bson_append_start_array (bson *b, const char *name)
	Start appending a new array to a bson.
MONGO_EXPORT int	bson_append_finish_object (bson *b)
	Finish appending a new object or array to a bson.
MONGO_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)
MONGO_EXPORT void	bson_free (void *ptr)
MONGO_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.
MONGO_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.
MONGO_EXPORT double	bson_int64_to_double (int64_t i64)
	Cast an int64_t to double.
MONGO_EXPORT void	bson_swap_endian32 (void *outp, const void *inp)
MONGO_EXPORT void	bson_swap_endian64 (void *outp, const void *inp)

Variables
void *(*	bson_malloc_func )(size_t)
void *(*	bson_realloc_func )(void *, size_t)
void(*	bson_free_func )(void *)
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_error_t

Enumerator:

BSON_SIZE_OVERFLOW

Trying to create a BSON object larger than INT_MAX.

enum bson_type

Enumerator:

BSON_DBREF

Deprecated.

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

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

void bson_builder_error

(

bson *

b

)

Invoke the error handler, but do not exit.

Parameters

b	the buffer object.

Invoke the error handler, but do not exit.

Calls the error handler if available.

Parameters

MONGO_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.

MONGO_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

MONGO_EXPORT void bson_destroy

(

bson *

b

)

Destroy a bson object.

Parameters

b	the bson object to destroy.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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( ).

int bson_init_data	(	bson *	b,
		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.

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.

MONGO_EXPORT double bson_int64_to_double

(

int64_t

i64

)

Cast an int64_t to double.

This is necessary for embedding in certain environments.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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)

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_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.

MONGO_EXPORT void bson_print

(

const bson *

b

)

Print a string representation of a BSON object.

Parameters

b	the BSON object to print.

MONGO_EXPORT void bson_print_raw	(	const char *	bson,
		int	depth
	)

Print a string representation of a BSON object.

Parameters

bson	the raw data to print.
depth	the depth to recurse the object.x

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()

MONGO_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.

MONGO_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.

MONGO_EXPORT int bson_size

(

const bson *

b

)

Size of a BSON object.

Parameters

b	the BSON object.

Returns

the size.

MONGO_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.