MongoDB C++ Driver 3.4.x release

/* * Copyright 2013 MongoDB, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef BSON_H #define BSON_H #define BSON_INSIDE #include "bson/bson-compat.h" #include <string.h> #include <time.h> #include "bson/bson-macros.h" #include "bson/bson-config.h" #include "bson/bson-atomic.h" #include "bson/bson-context.h" #include "bson/bson-clock.h" #include "bson/bson-decimal128.h" #include "bson/bson-error.h" #include "bson/bson-iter.h" #include "bson/bson-json.h" #include "bson/bson-keys.h" #include "bson/bson-md5.h" #include "bson/bson-memory.h" #include "bson/bson-oid.h" #include "bson/bson-reader.h" #include "bson/bson-string.h" #include "bson/bson-types.h" #include "bson/bson-utf8.h" #include "bson/bson-value.h" #include "bson/bson-version.h" #include "bson/bson-version-functions.h" #include "bson/bson-writer.h" #include "bson/bcon.h" #undef BSON_INSIDE BSON_BEGIN_DECLS /** * bson_empty: * @b: a bson_t. * * Checks to see if @b is an empty BSON document. An empty BSON document is * a 5 byte document which contains the length (4 bytes) and a single NUL * byte indicating end of fields. */ #define bson_empty(b) (((b)->len == 5) || !bson_get_data ((b))[4]) /** * bson_empty0: * * Like bson_empty() but treats NULL the same as an empty bson_t document. */ #define bson_empty0(b) (!(b) || bson_empty (b)) /** * bson_clear: * * Easily free a bson document and set it to NULL. Use like: * * bson_t *doc = bson_new(); * bson_clear (&doc); * BSON_ASSERT (doc == NULL); */ #define bson_clear(bptr) \ do { \ if (*(bptr)) { \ bson_destroy (*(bptr)); \ *(bptr) = NULL; \ } \ } while (0) /** * BSON_MAX_SIZE: * * The maximum size in bytes of a BSON document. */ #define BSON_MAX_SIZE ((size_t) ((1U << 31) - 1)) #define BSON_APPEND_ARRAY(b, key, val) \ bson_append_array (b, key, (int) strlen (key), val) #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \ bson_append_array_begin (b, key, (int) strlen (key), child) #define BSON_APPEND_BINARY(b, key, subtype, val, len) \ bson_append_binary (b, key, (int) strlen (key), subtype, val, len) #define BSON_APPEND_BOOL(b, key, val) \ bson_append_bool (b, key, (int) strlen (key), val) #define BSON_APPEND_CODE(b, key, val) \ bson_append_code (b, key, (int) strlen (key), val) #define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \ bson_append_code_with_scope (b, key, (int) strlen (key), val, scope) #define BSON_APPEND_DBPOINTER(b, key, coll, oid) \ bson_append_dbpointer (b, key, (int) strlen (key), coll, oid) #define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \ bson_append_document_begin (b, key, (int) strlen (key), child) #define BSON_APPEND_DOUBLE(b, key, val) \ bson_append_double (b, key, (int) strlen (key), val) #define BSON_APPEND_DOCUMENT(b, key, val) \ bson_append_document (b, key, (int) strlen (key), val) #define BSON_APPEND_INT32(b, key, val) \ bson_append_int32 (b, key, (int) strlen (key), val) #define BSON_APPEND_INT64(b, key, val) \ bson_append_int64 (b, key, (int) strlen (key), val) #define BSON_APPEND_MINKEY(b, key) \ bson_append_minkey (b, key, (int) strlen (key)) #define BSON_APPEND_DECIMAL128(b, key, val) \ bson_append_decimal128 (b, key, (int) strlen (key), val) #define BSON_APPEND_MAXKEY(b, key) \ bson_append_maxkey (b, key, (int) strlen (key)) #define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key)) #define BSON_APPEND_OID(b, key, val) \ bson_append_oid (b, key, (int) strlen (key), val) #define BSON_APPEND_REGEX(b, key, val, opt) \ bson_append_regex (b, key, (int) strlen (key), val, opt) #define BSON_APPEND_UTF8(b, key, val) \ bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val)) #define BSON_APPEND_SYMBOL(b, key, val) \ bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val)) #define BSON_APPEND_TIME_T(b, key, val) \ bson_append_time_t (b, key, (int) strlen (key), val) #define BSON_APPEND_TIMEVAL(b, key, val) \ bson_append_timeval (b, key, (int) strlen (key), val) #define BSON_APPEND_DATE_TIME(b, key, val) \ bson_append_date_time (b, key, (int) strlen (key), val) #define BSON_APPEND_TIMESTAMP(b, key, val, inc) \ bson_append_timestamp (b, key, (int) strlen (key), val, inc) #define BSON_APPEND_UNDEFINED(b, key) \ bson_append_undefined (b, key, (int) strlen (key)) #define BSON_APPEND_VALUE(b, key, val) \ bson_append_value (b, key, (int) strlen (key), (val)) /** * bson_new: * * Allocates a new bson_t structure. Call the various bson_append_*() * functions to add fields to the bson. You can iterate the bson_t at any * time using a bson_iter_t and bson_iter_init(). * * Returns: A newly allocated bson_t that should be freed with bson_destroy(). */ BSON_EXPORT (bson_t *) bson_new (void); BSON_EXPORT (bson_t *) bson_new_from_json (const uint8_t *data, ssize_t len, bson_error_t *error); BSON_EXPORT (bool) bson_init_from_json (bson_t *bson, const char *data, ssize_t len, bson_error_t *error); /** * bson_init_static: * @b: A pointer to a bson_t. * @data: The data buffer to use. * @length: The length of @data. * * Initializes a bson_t using @data and @length. This is ideal if you would * like to use a stack allocation for your bson and do not need to grow the * buffer. @data must be valid for the life of @b. * * Returns: true if initialized successfully; otherwise false. */ BSON_EXPORT (bool) bson_init_static (bson_t *b, const uint8_t *data, size_t length); /** * bson_init: * @b: A pointer to a bson_t. * * Initializes a bson_t for use. This function is useful to those that want a * stack allocated bson_t. The usefulness of a stack allocated bson_t is * marginal as the target buffer for content will still require heap * allocations. It can help reduce heap fragmentation on allocators that do * not employ SLAB/magazine semantics. * * You must call bson_destroy() with @b to release resources when you are done * using @b. */ BSON_EXPORT (void) bson_init (bson_t *b); /** * bson_reinit: * @b: (inout): A bson_t. * * This is equivalent to calling bson_destroy() and bson_init() on a #bson_t. * However, it will try to persist the existing malloc'd buffer if one exists. * This is useful in cases where you want to reduce malloc overhead while * building many documents. */ BSON_EXPORT (void) bson_reinit (bson_t *b); /** * bson_new_from_data: * @data: A buffer containing a serialized bson document. * @length: The length of the document in bytes. * * Creates a new bson_t structure using the data provided. @data should contain * at least @length bytes that can be copied into the new bson_t structure. * * Returns: A newly allocated bson_t that should be freed with bson_destroy(). * If the first four bytes (little-endian) of data do not match @length, * then NULL will be returned. */ BSON_EXPORT (bson_t *) bson_new_from_data (const uint8_t *data, size_t length); /** * bson_new_from_buffer: * @buf: A pointer to a buffer containing a serialized bson document. * @buf_len: The length of the buffer in bytes. * @realloc_fun: a realloc like function * @realloc_fun_ctx: a context for the realloc function * * Creates a new bson_t structure using the data provided. @buf should contain * a bson document, or null