SYNOPSIS

#include <bson.h>

typedef struct _bson_writer_t bson_writer_t;

bson_writer_t *
bson_writer_new (uint8_t         **buf,
                 size_t           *buflen,
                 size_t            offset,
                 bson_realloc_func realloc_func);

void
bson_writer_destroy (bson_writer_t *writer);

size_t
bson_writer_get_length (bson_writer_t *writer);

bool
bson_writer_begin (bson_writer_t *writer,
                   bson_t       **bson);

void
bson_writer_end (bson_writer_t *writer);

void
bson_writer_rollback (bson_writer_t *writer);

DESCRIPTION

bson_writer_t

The bson_writer_t structure is a helper for writing a series of BSON documents to a single malloc() buffer. You can provide a realloc() style function to grow the buffer as you go.

This is useful if you want to build a series of BSON documents right into the target buffer for an outgoing packet. The offset parameter allows you to start at an offset of the target buffer.

bson_writer_new()

Creates a new instance of bson_writer_t using the buffer, length, offset, and realloc() function supplied.

The caller is expected to clean up the structure when finished using bson_writer_destroy().

bson_writer_destroy()

Cleanup after writer and release any allocated memory. Note that the buffer supplied to bson_writer_new() is NOT freed from this method. The caller is responsible for that.

bson_writer_begin()

Begins writing a new document. The caller may use the bson structure to write out a new BSON document. When completed, the caller must call either bson_writer_end() or bson_writer_rollback().

bson_writer_end()

Complete writing of a bson_writer_t to the buffer supplied.

bson_writer_rollback()

Abort the appending of the current bson_t to the memory region managed by writer. This is useful if you detected that you went past a particular memory limit. For example, MongoDB has 48MB message limits.

bson_writer_get_length()

Fetches the current length of the content written by the buffer (including the initial offset). This includes a partly written document currently being written.

This is useful if you want to check to see if you’ve passed a given memory boundry that cannot be sent in a packet. See bson_writer_rollback() to abort the current document being written.

RETURN VALUE

bson_writer_get_length() returns the length of the underlying buffer.

ERRORS

No errors are defined.

SEE ALSO

AUTHORS

This page was written by MongoDB, Inc.