Functions that operate on whole BSON objects. More...

Collaboration diagram for Object Access:

Functions
bson *	bson_new (void)
	Create a new BSON object. More...

bson *	bson_new_sized (gint32 size)
	Create a new BSON object, preallocating a given amount of space. More...

bson *	bson_new_from_data (const guint8 *data, gint32 size)
	Create a BSON object from existing data. More...

bson *	bson_build_full (bson_type type, const gchar *name, gboolean free_after,...)
	Build a BSON object in one go, with full control. More...

bson *	bson_build (bson_type type, const gchar *name,...)
	Build a BSON object in one go. More...

gboolean	bson_finish (bson *b)
	Finish a BSON object. More...

gboolean	bson_reset (bson *b)
	Reset a BSON object. More...

void	bson_free (bson *b)
	Free the memory associated with a BSON object. More...

gint32	bson_size (const bson *b)
	Return the size of a finished BSON object. More...

const guint8 *	bson_data (const bson *b)
	Return the raw bytestream form of the BSON object. More...

gboolean	bson_validate_key (const gchar *key, gboolean forbid_dots, gboolean no_dollar)
	Validate a BSON key. More...

Detailed Description

Functions that operate on whole BSON objects.

Function Documentation

bson* bson_build	(	bson_type	type,
		const gchar *	name,
			...
	)

Build a BSON object in one go.

Very similar to bson_build_full(), so much so, that it's exactly the same, except that the free_after parameter is always FALSE, and must not be specified in this case.

Parameters

type	is the element type we'll be adding.
name	is the key name.

Returns: A newly allocated, unfinished BSON object, which must be finalized and freed, once not needed anymore, by the caller. Or NULL on error.

bson* bson_build_full	(	bson_type	type,
		const gchar *	name,
		gboolean	free_after,
			...
	)

Build a BSON object in one go, with full control.

This function can be used to build a BSON object in one simple step, chaining all the elements together (including sub-documents, created by this same function - more about that later).

One has to specify the type, the key name, and whether he wants to see the added object free'd after addition. Each element type is freed appropriately, and documents and arrays are finished before addition, if they're to be freed afterwards.

This way of operation allows one to build a full BSON object, even with embedded documents, without leaking memory.

After the three required parameters, one will need to list the data itself, in the same order as one would if he'd add with the bson_append family of functions.

The list must be closed with a BSON_TYPE_NONE element, and the name and free_after parameters are not needed for the closing entry.

Parameters

type	is the element type we'll be adding.
name	is the key name.
free_after	determines whether the original variable will be freed after adding it to the BSON object.

Returns: A newly allocated, unfinished BSON object, which must be finalized and freed, once not needed anymore, by the caller. Or NULL on error.

const guint8* bson_data ( const bson * b)

Return the raw bytestream form of the BSON object.

Parameters

b	is the BSON object to retrieve data from.

Returns: The raw datastream or NULL on error. The stream s all not be freed.

Note: Trying to retrieve the data of an unfinished BSON object is considered an error.

gboolean bson_finish ( bson * b)

Finish a BSON object.

Terminate a BSON object. This includes appending the trailing zero byte and finalising the length of the object.

The object cannot be appended to after it is finalised.

Parameters

b	is the BSON object to close & finish.

Returns: TRUE on success, FALSE otherwise.

void bson_free ( bson * b)

Free the memory associated with a BSON object.

Frees up all memory associated with a BSON object. The variable shall not be used afterwards.

Parameters

b	is the BSON object to free.

bson* bson_new ( void )

Create a new BSON object.

Note: The created object will have no memory pre-allocated for data, resulting in possibly more reallocations than neccessary when appending elements.; If at all possible, use bson_new_sized() instead.

Returns: A newly allocated object, or NULL on error.

bson* bson_new_from_data	(	const guint8 *	data,
		gint32	size
	)

Create a BSON object from existing data.

In order to be able to parse existing BSON, one must load it up into a bson object - and this function does just that.

Note: Objects created by this function are not final objects, in order to be able to extend them. As such, when importing existing BSON data, which are terminated by a zero byte, specify the size as one smaller than the original data stream.; This is because bson_finish() will append a zero byte, thus one would end up with an invalid document if it had an extra one.

Parameters

data	is the BSON byte stream to import.
size	is the size of the byte stream.

Returns: A newly allocated object, with a copy of data as its contents.

bson* bson_new_sized ( gint32 size)

Create a new BSON object, preallocating a given amount of space.

Creates a new BSON object, pre-allocating size bytes of space for the data.

Parameters

size	is the space to pre-allocate for data.

Note: It is not an error to pre-allocate either less, or more space than what will really end up being added. Pre-allocation does not set the size of the final object, it is merely a hint, a way to help the system avoid memory reallocations.

Returns: A newly allocated object, or NULL on error.

gboolean bson_reset ( bson * b)

Reset a BSON object.

Resetting a BSON object clears the finished status, and sets its size to zero. Resetting is most useful when wants to keep the already allocated memory around for reuse.

Parameters

b	is the BSON object to reset.

Returns: TRUE on success, FALSE otherwise.

gint32 bson_size ( const bson * b)

Return the size of a finished BSON object.

Parameters

b	is the finished BSON object.

Returns: The size of the document, or -1 on error.

Note: Trying to get the size of a BSON object that has not been closed by bson_finish() is considered an error.

gboolean bson_validate_key	(	const gchar *	key,
		gboolean	forbid_dots,
		gboolean	no_dollar
	)

Validate a BSON key.

Verifies that a given key is a valid BSON field name. Depending on context (togglable by the boolean flags) this means that the string must either be free of dots, or must not start with a dollar sign.

Parameters

key	is the field name to validate.
forbid_dots	toggles whether to disallow dots in the name altogether.
no_dollar	toggles whether to forbid key names starting with a dollar sign.

Returns: TRUE if the field name is found to be valid, FALSE otherwise.

Note: This function does NOT do UTF-8 validation. That is left up to the application.