Loading...
Searching...
No Matches
Object Access
BSON

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

Collaboration diagram for Object Access:

## Functions

bson * | bson_new (void)
| Create a new BSON object.
bson * | bson_new_sized (gint32 size)
| Create a new BSON object, preallocating a given amount of space.
bson * | bson_new_from_data (const guint8 *data, gint32 size)
| Create a BSON object from existing data.
bson * | bson_build_full (bson_type type, const gchar *name, gboolean free_after,...)
| Build a BSON object in one go, with full control.
bson * | bson_build (bson_type type, const gchar *name,...)
| Build a BSON object in one go.
gboolean | bson_finish (bson *b)
| Finish a BSON object.
gboolean | bson_reset (bson *b)
| Reset a BSON object.
void | bson_free (bson *b)
| Free the memory associated with a BSON object.
gint32 | bson_size (const bson *b)
| Return the size of a finished BSON object.
const guint8 * | bson_data (const bson *b)
| Return the raw bytestream form of the BSON object.
gboolean | bson_validate_key (const gchar *key, gboolean forbid_dots, gboolean no_dollar)
| Validate a BSON key.

## Detailed Description

Functions that operate on whole BSON objects.

## Function Documentation

## bson_build()

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

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.

## bson_data()

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.

## bson_finish()

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.

## bson_free()

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

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

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

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.

## bson_reset()

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.

## bson_size()

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.

## bson_validate_key()

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.