MongoDBCDriver  0.8.1
Classes | Macros | Typedefs | Enumerations | Functions | Variables
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 << 0), BSON_ALREADY_FINISHED = (1 << 4), BSON_NOT_IN_SUBOBJECT = (1 << 5), BSON_DOES_NOT_OWN_DATA = (1 << 6) }
 
enum  bson_validity_t { BSON_VALID = 0, BSON_NOT_UTF8 = (1 << 1), BSON_FIELD_HAS_DOT = (1 << 2), BSON_FIELD_INIT_DOLLAR = (1 << 3) }
 
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, BSON_MAXKEY = 127,
  BSON_MINKEY = 255
}
 

Functions

MONGO_EXPORT void bson_init_zero (bson *b)
 Zero a bson struct. More...
 
MONGO_EXPORT bsonbson_alloc (void)
 Allocate memory for a new BSON object. More...
 
MONGO_EXPORT void bson_dealloc (bson *b)
 Deallocate a BSON object. More...
 
MONGO_EXPORT int bson_init_finished_data (bson *b, char *data, bson_bool_t ownsData)
 Initialize a BSON object for reading and set its data pointer to the provided char*. More...
 
MONGO_EXPORT int bson_init_finished_data_with_copy (bson *b, const char *data)
 Initialize a BSON object for reading and copy finalized BSON data from the provided char*. More...
 
MONGO_EXPORT int bson_size (const bson *b)
 Size of a BSON object. More...
 
MONGO_EXPORT size_t bson_buffer_size (const bson *b)
 Minimum finished size of an unfinished BSON object given current contents. More...
 
MONGO_EXPORT void bson_print (const bson *b)
 Print a string representation of a BSON object. More...
 
MONGO_EXPORT const char * bson_data (const bson *b)
 Return a pointer to the raw buffer stored by this bson object. More...
 
MONGO_EXPORT int bson_has_data (const bson *b)
 Returns true if bson_data(b) {b->data} is not null; else, false. More...
 
MONGO_EXPORT void bson_print_raw (const char *bson, int depth)
 Print a string representation of a BSON object. More...
 
MONGO_EXPORT bson_type bson_find (bson_iterator *it, const bson *obj, const char *name)
 Advance a bson_iterator to the named field. More...
 
MONGO_EXPORT bson_iteratorbson_iterator_alloc (void)
 
MONGO_EXPORT void bson_iterator_dealloc (bson_iterator *)
 
MONGO_EXPORT void bson_iterator_init (bson_iterator *i, const bson *b)
 Initialize a bson_iterator. More...
 
MONGO_EXPORT void bson_iterator_from_buffer (bson_iterator *i, const char *buffer)
 Initialize a bson iterator from a const char* buffer. More...
 
MONGO_EXPORT bson_bool_t bson_iterator_more (const bson_iterator *i)
 Check to see if the bson_iterator has more data. More...
 
MONGO_EXPORT bson_type bson_iterator_next (bson_iterator *i)
 Point the iterator at the next BSON object. More...
 
MONGO_EXPORT bson_type bson_iterator_type (const bson_iterator *i)
 Get the type of the BSON object currently pointed to by the iterator. More...
 
MONGO_EXPORT const char * bson_iterator_key (const bson_iterator *i)
 Get the key of the BSON object currently pointed to by the iterator. More...
 
MONGO_EXPORT const char * bson_iterator_value (const bson_iterator *i)
 Get the value of the BSON object currently pointed to by the iterator. More...
 
MONGO_EXPORT double bson_iterator_double (const bson_iterator *i)
 Get the double value of the BSON object currently pointed to by the iterator. More...
 
MONGO_EXPORT int bson_iterator_int (const bson_iterator *i)
 Get the int value of the BSON object currently pointed to by the iterator. More...
 
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. More...
 
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. More...
 
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. More...
 
double bson_iterator_double_raw (const bson_iterator *i)
 Get the double value of the BSON object currently pointed to by the iterator. More...
 
int bson_iterator_int_raw (const bson_iterator *i)
 Get the int value of the BSON object currently pointed to by the iterator. More...
 
int64_t bson_iterator_long_raw (const bson_iterator *i)
 Get the long value of the BSON object currently pointed to by the iterator. More...
 
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. More...
 
MONGO_EXPORT bson_oid_tbson_iterator_oid (const bson_iterator *i)
 Get the bson_oid_t value of the BSON object currently pointed to by the iterator. More...
 
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. More...
 
int bson_iterator_string_len (const bson_iterator *i)
 Get the string length of the BSON object currently pointed to by the iterator. More...
 
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. More...
 
MONGO_EXPORT void bson_iterator_code_scope_init (const bson_iterator *i, bson *scope, bson_bool_t copyData)
 Get the code scope value of the BSON object currently pointed to by the iterator. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
MONGO_EXPORT void bson_iterator_subobject_init (const bson_iterator *i, bson *sub, bson_bool_t copyData)
 Get the BSON subobject currently pointed to by the iterator. More...
 
MONGO_EXPORT void bson_iterator_subiterator (const bson_iterator *i, bson_iterator *sub)
 Get a bson_iterator that on the BSON subobject. More...
 
MONGO_EXPORT void bson_oid_from_string (bson_oid_t *oid, const char *str)
 Create a bson_oid_t from a string. More...
 
MONGO_EXPORT void bson_oid_to_string (const bson_oid_t *oid, char *str)
 Create a string representation of the bson_oid_t. More...
 
MONGO_EXPORT void bson_oid_gen (bson_oid_t *oid)
 Create a bson_oid object. More...
 
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. More...
 
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). More...
 
MONGO_EXPORT time_t bson_oid_generated_time (bson_oid_t *oid)
 Get the time a bson_oid_t was created. More...
 
MONGO_EXPORT int bson_init (bson *b)
 Initialize a BSON object for building and allocate a data buffer. More...
 
int bson_init_size (bson *b, int size)
 Initialize a BSON object for building and allocate a data buffer of a given size. More...
 
int bson_init_unfinished_data (bson *b, char *data, int dataSize, bson_bool_t ownsData)
 Initialize a BSON object for building, using the provided char* of the given size. More...
 
int bson_ensure_space (bson *b, const size_t bytesNeeded)
 Grow a bson object. More...
 
MONGO_EXPORT int bson_finish (bson *b)
 Finalize a bson object. More...
 
MONGO_EXPORT void bson_destroy (bson *b)
 Destroy a bson object and deallocate its data buffer. More...
 
MONGO_EXPORT bson_bool_t bson_init_empty (bson *obj)
 Initialize a BSON object to an emoty object with a shared, static data buffer. More...
 
MONGO_EXPORT const bsonbson_shared_empty (void)
 Return a pointer to an empty, shared, static BSON object. More...
 
MONGO_EXPORT int bson_copy (bson *out, const bson *in)
 Make a complete copy of the a BSON object. More...
 
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. More...
 
MONGO_EXPORT int bson_append_new_oid (bson *b, const char *name)
 Append a bson_oid_t to a bson. More...
 
MONGO_EXPORT int bson_append_int (bson *b, const char *name, const int i)
 Append an int to a bson. More...
 
MONGO_EXPORT int bson_append_long (bson *b, const char *name, const int64_t i)
 Append an long to a bson. More...
 
MONGO_EXPORT int bson_append_double (bson *b, const char *name, const double d)
 Append an double to a bson. More...
 
MONGO_EXPORT int bson_append_string (bson *b, const char *name, const char *str)
 Append a string to a bson. More...
 
MONGO_EXPORT int bson_append_string_n (bson *b, const char *name, const char *str, size_t len)
 Append len bytes of a string to a bson. More...
 
MONGO_EXPORT int bson_append_symbol (bson *b, const char *name, const char *str)
 Append a symbol to a bson. More...
 
MONGO_EXPORT int bson_append_symbol_n (bson *b, const char *name, const char *str, size_t len)
 Append len bytes of a symbol to a bson. More...
 
MONGO_EXPORT int bson_append_code (bson *b, const char *name, const char *str)
 Append code to a bson. More...
 
MONGO_EXPORT int bson_append_code_n (bson *b, const char *name, const char *str, size_t len)
 Append len bytes of code to a bson. More...
 
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. More...
 
MONGO_EXPORT int bson_append_code_w_scope_n (bson *b, const char *name, const char *code, size_t size, const bson *scope)
 Append len bytes of code to a bson with scope. More...
 
MONGO_EXPORT int bson_append_binary (bson *b, const char *name, char type, const char *str, size_t len)
 Append binary data to a bson. More...
 
MONGO_EXPORT int bson_append_bool (bson *b, const char *name, const bson_bool_t v)
 Append a bson_bool_t to a bson. More...
 
MONGO_EXPORT int bson_append_null (bson *b, const char *name)
 Append a null value to a bson. More...
 
MONGO_EXPORT int bson_append_undefined (bson *b, const char *name)
 Append an undefined value to a bson. More...
 
MONGO_EXPORT int bson_append_maxkey (bson *b, const char *name)
 Append a maxkey value to a bson. More...
 
MONGO_EXPORT int bson_append_minkey (bson *b, const char *name)
 Append a minkey value to a bson. More...
 
MONGO_EXPORT int bson_append_regex (bson *b, const char *name, const char *pattern, const char *opts)
 Append a regex value to a bson. More...
 
MONGO_EXPORT int bson_append_bson (bson *b, const char *name, const bson *bson)
 Append bson data to a bson. More...
 
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. More...
 
MONGO_EXPORT int bson_append_timestamp (bson *b, const char *name, bson_timestamp_t *ts)
 Append a bson_timestamp_t value to a bson. More...
 
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. More...
 
MONGO_EXPORT int bson_append_time_t (bson *b, const char *name, time_t secs)
 Append a time_t value to a bson. More...
 
MONGO_EXPORT int bson_append_start_object (bson *b, const char *name)
 Start appending a new object to a bson. More...
 
MONGO_EXPORT int bson_append_start_array (bson *b, const char *name)
 Start appending a new array to a bson. More...
 
MONGO_EXPORT int bson_append_finish_object (bson *b)
 Finish appending a new object or array to a bson. More...
 
MONGO_EXPORT int bson_append_finish_array (bson *b)
 Finish appending a new object or array to a bson. More...
 
void bson_numstr (char *str, int i)
 
void bson_incnumstr (char *str)
 
MONGO_EXPORT void bson_free (void *ptr)
 
MONGO_EXPORT void * bson_malloc (size_t size)
 Allocates memory and checks return value, exiting fatally if malloc() fails. More...
 
void * bson_realloc (void *ptr, size_t size)
 Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails. More...
 
MONGO_EXPORT bson_err_handler set_bson_err_handler (bson_err_handler func)
 Set a function for error handling. More...
 
void bson_fatal (int ok)
 Exit fatally. More...
 
void bson_fatal_msg (int ok, const char *msg)
 Exit fatally with an error message. More...
 
void bson_builder_error (bson *b)
 Invoke the error handler, but do not exit. More...
 
MONGO_EXPORT double bson_int64_to_double (int64_t i64)
 Cast an int64_t to double. More...
 
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

Enumerator
BSON_SIZE_OVERFLOW 

Trying to create a BSON object larger than INT_MAX.

BSON_ALREADY_FINISHED 

Trying to modify a finished BSON object.

BSON_NOT_IN_SUBOBJECT 

Trying bson_append_finish_object() and not in sub.

BSON_DOES_NOT_OWN_DATA 

Trying to expand a BSON object which does not own its data block.

enum bson_type
Enumerator
BSON_DBREF 

Deprecated.

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.

Function Documentation

MONGO_EXPORT bson* bson_alloc ( void  )

Allocate memory for a new BSON object.

Note
After using this function, you must initialize the object using bson_init_finished_data( ), bson_init_empty( ), bson_init( ), or one of the other init functions.
Returns
a new BSON object.
MONGO_EXPORT int bson_append_binary ( bson b,
const char *  name,
char  type,
const char *  str,
size_t  len 
)

Append binary data to a bson.

Parameters
bthe bson to append to.
namethe key for the data.
typethe binary data type.
strthe binary data.
lenthe 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
bthe bson to append to.
namethe key for the boolean value.
vthe 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
bthe bson to append to.
namethe key for the bson data.
bsonthe 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
bthe bson to append to.
namethe key for the code.
strthe code to append.
lenthe 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,
size_t  len 
)

Append len bytes of code to a bson.

Parameters
bthe bson to append to.
namethe key for the code.
strthe code to append.
lenthe 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
bthe bson to append to.
namethe key for the code.
strthe string to append.
scopea 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,
size_t  size,
const bson scope 
)

Append len bytes of code to a bson with scope.

Parameters
bthe bson to append to.
namethe key for the code.
strthe string to append.
lenthe number of bytes from str to append.
scopea 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
bthe bson to append to.
namethe key for the date value.
millisthe 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
bthe bson to append to.
namethe key for the double.
dthe 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
bthe bson to append to.
name_or_nullthe key for the BSON element, or NULL.
elemthe 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
bthe 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
bthe 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
bthe bson to append to.
namethe key for the int.
ithe 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
bthe bson to append to.
namethe key for the long.
ithe long to append.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT int bson_append_maxkey ( bson b,
const char *  name 
)

Append a maxkey value to a bson.

Parameters
bthe bson to append to.
namethe key for the maxkey value.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT int bson_append_minkey ( bson b,
const char *  name 
)

Append a minkey value to a bson.

Parameters
bthe bson to append to.
namethe key for the minkey value.
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
bthe bson to append to.
namethe 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
bthe bson to append to.
namethe 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
bthe bson to append to.
namethe key for the bson_oid_t.
oidthe 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
bthe bson to append to.
namethe key for the regex value.
patternthe regex pattern to append.
theregex 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
bthe bson to append to.
namethe 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
bthe bson to append to.
namethe 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
bthe bson to append to.
namethe key for the string.
strthe string to append.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT int bson_append_string_n ( bson b,
const char *  name,
const char *  str,
size_t  len 
)

Append len bytes of a string to a bson.

Parameters
bthe bson to append to.
namethe key for the string.
strthe string to append.
lenthe 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
bthe bson to append to.
namethe key for the symbol.
strthe symbol to append.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT int bson_append_symbol_n ( bson b,
const char *  name,
const char *  str,
size_t  len 
)

Append len bytes of a symbol to a bson.

Parameters
bthe bson to append to.
namethe key for the symbol.
strthe symbol to append.
lenthe 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
bthe bson to append to.
namethe key for the date value.
secsthe 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
bthe bson to append to.
namethe key for the timestampe value.
tsthe 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
bthe bson to append to.
namethe key for the undefined value.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT size_t bson_buffer_size ( const bson b)

Minimum finished size of an unfinished BSON object given current contents.

Parameters
bthe BSON object.
Returns
the BSON object's minimum finished size
void bson_builder_error ( bson b)

Invoke the error handler, but do not exit.

Parameters
bthe 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
outthe copy destination BSON object.
inthe 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
ba BSON object
MONGO_EXPORT void bson_dealloc ( bson b)

Deallocate a BSON object.

Note
You must call bson_destroy( ) before calling this function.
MONGO_EXPORT void bson_destroy ( bson b)

Destroy a bson object and deallocate its data buffer.

Parameters
bthe bson object to destroy.
int bson_ensure_space ( bson b,
const size_t  bytesNeeded 
)

Grow a bson object.

Parameters
bthe bson to grow.
bytesNeededthe 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
okexits if ok is equal to 0.
void bson_fatal_msg ( int  ok,
const char *  msg 
)

Exit fatally with an error message.

Parameters
okexits if ok is equal to 0.
msgprints 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
itthe bson_iterator to use.
objthe BSON object to use.
namethe 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
bthe bson object to finalize.
Returns
the standard error code. To deallocate memory, call bson_destroy on the bson object.
MONGO_EXPORT int bson_has_data ( const bson b)

Returns true if bson_data(b) {b->data} is not null; else, false.

Note
Convenience function for determining if bson data was returned by a function. Check required after calls to mongo_create_index(), mongo_create_simple_index(), mongo_cmd_get_last_error() and mongo_cmd_get_prev_error().
Parameters
bthe bson struct to inspect.
MONGO_EXPORT int bson_init ( bson b)

Initialize a BSON object for building and allocate a data buffer.

Note
You must initialize each new bson object using this, bson_init_finished_data( ), or one of the other init functions. When done using the BSON object, you must pass it to bson_destroy( ).
Parameters
bthe BSON object to initialize.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT bson_bool_t bson_init_empty ( bson obj)

Initialize a BSON object to an emoty object with a shared, static data buffer.

Note
You must NOT modify this object's data. It is safe though not required to call bson_destroy( ) on this object.
Parameters
objthe BSON object to initialize.
Returns
BSON_OK
MONGO_EXPORT int bson_init_finished_data ( bson b,
char *  data,
bson_bool_t  ownsData 
)

Initialize a BSON object for reading and set its data pointer to the provided char*.

Note
When done using the bson object, you must pass the object to bson_destroy( ).
Parameters
bthe BSON object to initialize.
datathe finalized raw BSON data.
ownsDatawhen true, bson_destroy() will free the data block.
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT int bson_init_finished_data_with_copy ( bson b,
const char *  data 
)

Initialize a BSON object for reading and copy finalized BSON data from the provided char*.

Note
When done using the bson object, you must pass the object to bson_destroy( ).
Parameters
bthe BSON object to initialize.
datathe finalized raw BSON data to copy.
Returns
BSON_OK or BSON_ERROR.
int bson_init_size ( bson b,
int  size 
)

Initialize a BSON object for building and allocate a data buffer of a given size.

Note
When done using the bson object, you must pass it to bson_destroy( ).
Parameters
bthe BSON object to initialize.
sizethe initial size of the buffer.
Returns
BSON_OK or BSON_ERROR.
int bson_init_unfinished_data ( bson b,
char *  data,
int  dataSize,
bson_bool_t  ownsData 
)

Initialize a BSON object for building, using the provided char* of the given size.

When ownsData is true, the BSON object may reallocate the data block as needed, and bson_destroy will free it.

See also bson_init_finished_data( )

Note
When done using the BSON object, you must pass it to bson_destroy( ).
Parameters
bthe BSON object to initialize.
datathe raw BSON data.
ownsDatawhen true, bson_ensure_space() may reallocate the block and bson_destroy() will free it
Returns
BSON_OK or BSON_ERROR.
MONGO_EXPORT void bson_init_zero ( bson b)

Zero a bson struct.

All fields are set to zero except the stack.

Note
Mainly used internally, but can be called for safety purposes so that a later call to bson_destroy() doesn't flip out. It is safe to call this function on a NULL pointer in which case there is no effect.
Parameters
bthe BSON object to zero.
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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe bson_iterator
Returns
the code value of the current BSON object.
MONGO_EXPORT void bson_iterator_code_scope_init ( const bson_iterator i,
bson scope,
bson_bool_t  copyData 
)

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

Calls bson_init_empty on scope if current object is not BSON_CODEWSCOPE.

Note
When copyData is false, the scope becomes invalid when the iterator's data buffer is deallocated. For either value of copyData, you must pass the scope object to bson_destroy when you are done using it.
Parameters
ithe bson_iterator.
scopean uninitialized BSON object to receive the scope.
copyDatawhen true, makes a copy of the scope data which will remain valid when the iterator's data buffer is deallocated.
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
ithe 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
ithe 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
ithe 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
ithe bson_iterator to initialize.
bufferthe buffer to point to.
MONGO_EXPORT void bson_iterator_init ( bson_iterator i,
const bson b 
)

Initialize a bson_iterator.

Parameters
ithe bson_iterator to initialize.
bsonthe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe 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
ithe bson_iterator.
subthe iterator to point at the BSON subobject.
MONGO_EXPORT void bson_iterator_subobject_init ( const bson_iterator i,
bson sub,
bson_bool_t  copyData 
)

Get the BSON subobject currently pointed to by the iterator.

Note
When copyData is 0, the subobject becomes invalid when its parent's data buffer is deallocated. For either value of copyData, you must pass the subobject to bson_destroy when you are done using it.
Parameters
ithe bson_iterator.
suban unitialized BSON object which will become the new subobject.
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
ithe 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
ithe 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
ithe 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
ithe bson_iterator
Returns
the value of the current BSON object.
MONGO_EXPORT void* bson_malloc ( size_t  size)

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

Parameters
sizebytes 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
oidthe bson_oid_t destination.
stra 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
oidthe 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
oidthe 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
oidthe bson_oid_t source.
strthe string representation destination.
MONGO_EXPORT void bson_print ( const bson b)

Print a string representation of a BSON object.

Parameters
bthe BSON object to print.
MONGO_EXPORT void bson_print_raw ( const char *  bson,
int  depth 
)

Print a string representation of a BSON object.

Parameters
bsonthe raw data to print.
depththe depth to recurse the object.x
void* bson_realloc ( void *  ptr,
size_t  size 
)

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

Parameters
ptrpointer to the space to reallocate.
sizebytes 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
funca 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
funca pointer to a function that returns an int.
MONGO_EXPORT const bson* bson_shared_empty ( void  )

Return a pointer to an empty, shared, static BSON object.

Note
This object is owned by the driver. You must NOT modify it and must NOT call bson_destroy( ) on it.
Returns
the shared initialized BSON object.
MONGO_EXPORT int bson_size ( const bson b)

Size of a BSON object.

Parameters
bthe 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
funca bson_err_handler function.
Returns
the old error handling function, or NULL.