diff --git a/snooty.toml b/snooty.toml index ed6a2a4b..256093af 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,8 +11,54 @@ toc_landing_pages = [ "/libbson/tutorials", "/libbson/guides", "/libbson/cross-platform-notes", + "/libbson/api", + "/libbson/api/bson_context_t", + "/libbson/api/bson_decimal128_t", + "/libbson/api/bson_error_t", + "/libbson/api/bson_iter_t", + "/libbson/api/bson_json_reader_t", + "/libbson/api/bson_memory", + "/libbson/api/bson_oid_t", + "/libbson/api/bson_reader_t", + "/libbson/api/bson_string_t", + "/libbson/api/bson_t", + "/libbson/api/bson_value_t", + "/libbson/api/bson_writer_t", + "/libbson/api/character_string_routines", + "/libbson/api/version", "/libbson/tutorial", "/libmongoc", + "/libmongoc/api", + "/libmongoc/api/errors", + "/libmongoc/api/init-cleanup", + "/libmongoc/api/mongoc_auto_encryption_opts_t", + "/libmongoc/api/mongoc_bulk_operation_t", + "/libmongoc/api/mongoc_change_stream_t", + "/libmongoc/api/mongoc_client_encryption_t", + "/libmongoc/api/mongoc_client_pool_t", + "/libmongoc/api/mongoc_client_session_t", + "/libmongoc/api/mongoc_client_t", + "/libmongoc/api/mongoc_collection_t", + "/libmongoc/api/mongoc_cursor_t", + "/libmongoc/api/mongoc_database_t", + "/libmongoc/api/mongoc_find_and_modify_opts_t", + "/libmongoc/api/mongoc_gridfs_t", + "/libmongoc/api/mongoc_index_opt_t", + "/libmongoc/api/mongoc_optional_t", + "/libmongoc/api/mongoc_rand", + "/libmongoc/api/mongoc_read_concern_t", + "/libmongoc/api/mongoc_read_prefs_t", + "/libmongoc/api/mongoc_server_api_t", + "/libmongoc/api/mongoc_server_description_t", + "/libmongoc/api/mongoc_session_opt_t", + "/libmongoc/api/mongoc_socket_t", + "/libmongoc/api/mongoc_stream_t", + "/libmongoc/api/mongoc_topology_description_t", + "/libmongoc/api/mongoc_transaction_opt_t", + "/libmongoc/api/mongoc_uri_t", + "/libmongoc/api/mongoc_version", + "/libmongoc/api/mongoc_write_concern_t", + "/libmongoc/application-performance-monitoring", "/libmongoc/guides", "/libmongoc/howto", "/libmongoc/ref", @@ -28,6 +74,4 @@ full-version = "{+version+}.2" is-experimental = "is part of the experimental Queryable Encryption API and may be subject to breaking changes in future releases." range-is-experimental = "Range algorithm is experimental only and not intended for public use. It is subject to breaking changes." api-is-experimental = "This API {+is-experimental+}" -opt-is-experimental = "This option {+is-experimental+}" -api-libbson = "https://mongoc.org/libbson/current" -api-libmongoc = "https://mongoc.org/libmongoc/current" \ No newline at end of file +opt-is-experimental = "This option {+is-experimental+}" \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index d573def4..264f3f41 100644 --- a/source/index.txt +++ b/source/index.txt @@ -43,7 +43,7 @@ following our tutorial. - `MongoDB Developer Center `__ -- `API Reference `_ +- :ref:`API Reference ` - `Changelog `__ diff --git a/source/libbson.txt b/source/libbson.txt index 6d1a3dab..591eb034 100644 --- a/source/libbson.txt +++ b/source/libbson.txt @@ -22,7 +22,7 @@ libbson /libbson/tutorials /libbson/guides /libbson/cross-platform-notes - API Documentation + /libbson/api Introduction ------------ diff --git a/source/libbson/api.txt b/source/libbson/api.txt new file mode 100644 index 00000000..55983aeb --- /dev/null +++ b/source/libbson/api.txt @@ -0,0 +1,51 @@ +.. _libbson-api: + +============= +API Reference +============= + +.. toctree:: + :titlesonly: + :maxdepth: 2 + + /libbson/api/bson_t + /libbson/api/bson_array_builder_t + /libbson/api/bson_context_t + /libbson/api/bson_decimal128_t + /libbson/api/bson_error_t + /libbson/api/bson_iter_t + /libbson/api/bson_json_reader_t + /libbson/api/bson_oid_t + /libbson/api/bson_reader_t + /libbson/api/character_and_string_routines + /libbson/api/bson_string_t + /libbson/api/bson_subtype_t + /libbson/api/bson_type_t + /libbson/api/bson_unichar_t + /libbson/api/bson_value_t + /libbson/api/bson_visitor_t + /libbson/api/bson_writer_t + /libbson/api/bson_get_monotonic_time + /libbson/api/bson_memory + /libbson/api/version + +- :ref:`bson_t` +- :ref:`bson_array_builder_t` +- :ref:`bson_context_t` +- :ref:`bson_decimal128_t` +- :ref:`bson_error_t` +- :ref:`bson_iter_t` +- :ref:`bson_json_reader_t` +- :ref:`bson_oid_t` +- :ref:`bson_reader_t` +- :ref:`bson_character_and_string_routines` +- :ref:`bson_string_t` +- :ref:`bson_subtype_t` +- :ref:`bson_type_t` +- :ref:`bson_unichar_t` +- :ref:`bson_value_t` +- :ref:`bson_visitor_t` +- :ref:`bson_writer_t` +- :ref:`bson_get_monotonic_time` +- :ref:`bson_memory` +- :ref:`bson_version` \ No newline at end of file diff --git a/source/libbson/api/bson_array_builder_t.txt b/source/libbson/api/bson_array_builder_t.txt new file mode 100644 index 00000000..dd8e2a69 --- /dev/null +++ b/source/libbson/api/bson_array_builder_t.txt @@ -0,0 +1,219 @@ +.. _bson_array_builder_t: + +==================== +bson_array_builder_t +==================== + +.. code-block:: c + + typedef struct _bson_array_builder_t bson_array_builder_t; + +``bson_array_builder_t`` may be used to build BSON arrays. ``bson_array_builder_t`` +internally tracks and uses the array index as a key ("0", "1", "2", ...) when appending +elements. + +Appending an Array Value +------------------------ + +.. code-block:: c + + typedef struct _bson_array_builder_t bson_array_builder_t; + + bool + bson_append_array_builder_begin (bson_t *bson, + const char *key, + int key_length, + bson_array_builder_t **child); + + bool + bson_append_array_builder_end (bson_t *bson, bson_array_builder_t *child); + + #define BSON_APPEND_ARRAY_BUILDER_BEGIN(b, key, child) \ + bson_append_array_builder_begin (b, key, (int) strlen (key), child) + +``bson_append_array_builder_begin`` may be used to append an array as a value. Example: + +.. literalinclude:: ../includes/examples/creating.c + :language: c + :start-after: // bson_array_builder_t example ... begin + :end-before: // bson_array_builder_t example ... end + :dedent: 6 + +Creating a Top-Level Array +-------------------------- + +.. code-block:: c + + bson_array_builder_t * bson_array_builder_new (void); + + bool + bson_array_builder_build (bson_array_builder_t *bab, bson_t *out); + + BSON_EXPORT (void) + bson_array_builder_destroy (bson_array_builder_t *bab); + +``bson_array_builder_new`` and ``bson_array_builder_build`` may be used to build a top-level BSON array. +``bson_array_builder_build`` initializes and moves BSON data to ``out``. The ``bson_array_builder_t`` may +be reused and will start appending a new array at index "0": + +Example: + +.. literalinclude:: ../includes/examples/creating.c + :language: c + :start-after: // bson_array_builder_t top-level example ... begin + :end-before: // bson_array_builder_t top-level example ... end + :dedent: 6 + +Appending Values to an Array +---------------------------- + +``bson_array_builder_append_*`` functions are provided to append values to a BSON array. The +``bson_array_builder_append_*`` functions internally use ``bson_append_*`` and provide the array +index as a key: + +.. code-block:: c + + bool + bson_array_builder_append_value (bson_array_builder_t *bab, + const bson_value_t *value); + + + bool + bson_array_builder_append_array (bson_array_builder_t *bab, + const bson_t *array); + + + bool + bson_array_builder_append_binary (bson_array_builder_t *bab, + bson_subtype_t subtype, + const uint8_t *binary, + uint32_t length); + + bool + bson_array_builder_append_bool (bson_array_builder_t *bab, bool value); + + + bool + bson_array_builder_append_code (bson_array_builder_t *bab, + const char *javascript); + + + bool + bson_array_builder_append_code_with_scope (bson_array_builder_t *bab, + const char *javascript, + const bson_t *scope); + + + bool + bson_array_builder_append_dbpointer (bson_array_builder_t *bab, + const char *collection, + const bson_oid_t *oid); + + + bool + bson_array_builder_append_double (bson_array_builder_t *bab, double value); + + + bool + bson_array_builder_append_document (bson_array_builder_t *bab, + const bson_t *value); + + + bool + bson_array_builder_append_document_begin (bson_array_builder_t *bab, + bson_t *child); + + + bool + bson_array_builder_append_document_end (bson_array_builder_t *bab, + bson_t *child); + + bool + bson_array_builder_append_int32 (bson_array_builder_t *bab, int32_t value); + + + bool + bson_array_builder_append_int64 (bson_array_builder_t *bab, int64_t value); + + + bool + bson_array_builder_append_decimal128 (bson_array_builder_t *bab, + const bson_decimal128_t *value); + + + bool + bson_array_builder_append_iter (bson_array_builder_t *bab, + const bson_iter_t *iter); + + + bool + bson_array_builder_append_minkey (bson_array_builder_t *bab); + + + bool + bson_array_builder_append_maxkey (bson_array_builder_t *bab); + + + bool + bson_array_builder_append_null (bson_array_builder_t *bab); + + + bool + bson_array_builder_append_oid (bson_array_builder_t *bab, + const bson_oid_t *oid); + + + bool + bson_array_builder_append_regex (bson_array_builder_t *bab, + const char *regex, + const char *options); + + + bool + bson_array_builder_append_regex_w_len (bson_array_builder_t *bab, + const char *regex, + int regex_length, + const char *options); + + bool + bson_array_builder_append_utf8 (bson_array_builder_t *bab, + const char *value, + int length); + + bool + bson_array_builder_append_symbol (bson_array_builder_t *bab, + const char *value, + int length); + + bool + bson_array_builder_append_time_t (bson_array_builder_t *bab, time_t value); + + + bool + bson_array_builder_append_timeval (bson_array_builder_t *bab, + struct timeval *value); + + + bool + bson_array_builder_append_date_time (bson_array_builder_t *bab, int64_t value); + + + bool + bson_array_builder_append_now_utc (bson_array_builder_t *bab); + + + bool + bson_array_builder_append_timestamp (bson_array_builder_t *bab, + uint32_t timestamp, + uint32_t increment); + + bool + bson_array_builder_append_undefined (bson_array_builder_t *bab); + + bool + bson_array_builder_append_array_builder_begin (bson_array_builder_t *bab, + bson_array_builder_t **child); + + bool + bson_array_builder_append_array_builder_end (bson_array_builder_t *bab, + bson_array_builder_t *child); diff --git a/source/libbson/api/bson_context_t.txt b/source/libbson/api/bson_context_t.txt new file mode 100644 index 00000000..08ec9349 --- /dev/null +++ b/source/libbson/api/bson_context_t.txt @@ -0,0 +1,77 @@ +.. _bson_context_t: + +============== +bson_context_t +============== + +BSON OID Generation Context + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef enum { + BSON_CONTEXT_NONE = 0, + BSON_CONTEXT_DISABLE_PID_CACHE = (1 << 2), + } bson_context_flags_t; + + typedef struct _bson_context_t bson_context_t; + + bson_context_t * + bson_context_get_default (void) BSON_GNUC_CONST; + bson_context_t * + bson_context_new (bson_context_flags_t flags); + void + bson_context_destroy (bson_context_t *context); + +Description +----------- + +The :ref:`bson_context_t` structure is context for generation of BSON Object +IDs. This context allows overriding behavior of generating ObjectIDs. The flags +``BSON_CONTEXT_NONE``, ``BSON_CONTEXT_THREAD_SAFE``, and ``BSON_CONTEXT_DISABLE_PID_CACHE`` +are the only ones used. The others have no effect. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_context_t/bson_context_destroy + /libbson/api/bson_context_t/bson_context_get_default + /libbson/api/bson_context_t/bson_context_new + +- :ref:`bson_context_destroy` +- :ref:`bson_context_get_default` +- :ref:`bson_context_new` + +Example +------- + +.. code-block:: c + + #include + + int + main (int argc, char *argv[]) + { + bson_context_t *ctx = NULL; + bson_oid_t oid; + + /* use default context, via bson_context_get_default() */ + bson_oid_init (&oid, NULL); + + /* specify a local context for additional control */ + ctx = bson_context_new (BSON_CONTEXT_NONE); + bson_oid_init (&oid, ctx); + + bson_context_destroy (ctx); + + return 0; + } + diff --git a/source/libbson/api/bson_context_t/bson_context_destroy.txt b/source/libbson/api/bson_context_t/bson_context_destroy.txt new file mode 100644 index 00000000..7938dde0 --- /dev/null +++ b/source/libbson/api/bson_context_t/bson_context_destroy.txt @@ -0,0 +1,28 @@ +.. _bson_context_destroy: + +====================== +bson_context_destroy() +====================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_context_destroy (bson_context_t *context); + +Parameters +---------- + +- ``context``: A :ref:`bson_context_t`. + +Description +----------- + +The ``bson_context_destroy()`` function shall release all resources associated with +``context``. Does nothing if ``context`` is NULL. + +This should be called when you are no longer using a :ref:`bson_context_t` that you +have allocated with :ref:`bson_context_new`. + diff --git a/source/libbson/api/bson_context_t/bson_context_get_default.txt b/source/libbson/api/bson_context_t/bson_context_get_default.txt new file mode 100644 index 00000000..83b9ac85 --- /dev/null +++ b/source/libbson/api/bson_context_t/bson_context_get_default.txt @@ -0,0 +1,20 @@ +.. _bson_context_get_default: + +========================== +bson_context_get_default() +========================== + +Synopsis +-------- + +.. code-block:: c + + bson_context_t * + bson_context_get_default (void); + +Returns +------- + +The ``bson_context_get_default()`` function shall return the default :ref:`bson_context_t` +for the process. This context is created with the flags ``BSON_CONTEXT_THREAD_SAFE`` and +``BSON_CONTEXT_DISABLE_PID_CACHE``. \ No newline at end of file diff --git a/source/libbson/api/bson_context_t/bson_context_new.txt b/source/libbson/api/bson_context_t/bson_context_new.txt new file mode 100644 index 00000000..45f469d5 --- /dev/null +++ b/source/libbson/api/bson_context_t/bson_context_new.txt @@ -0,0 +1,42 @@ +.. _bson_context_new: + +================== +bson_context_new() +================== + +Synopsis +-------- + +.. code-block:: c + + bson_context_t * + bson_context_new (bson_context_flags_t flags); + +Parameters +---------- + +- ``flags``: A :ref:`bson_context_t`. + +The following ``flags`` may be used: + +- ``BSON_CONTEXT_NONE`` meaning creating ObjectIDs with this context is not a thread-safe operation. +- ``BSON_CONTEXT_DISABLE_PID_CACHE`` meaning creating ObjectIDs will also check if the process has + changed by calling ``getpid()`` on every ObjectID generation. + +The following flags are deprecated and have no effect: + +- ``BSON_CONTEXT_DISABLE_HOST_CACHE`` +- ``BSON_CONTEXT_THREAD_SAFE`` +- ``BSON_CONTEXT_USE_TASK_ID`` + +Description +----------- + +Creates a new :ref:`bson_context_t`. This is rarely needed as :ref:`bson_context_get_default` +serves most use-cases. + +Returns +------- + +A newly allocated :ref:`bson_context_t` that should be freed with :ref:`bson_context_destroy`. + diff --git a/source/libbson/api/bson_decimal128_t.txt b/source/libbson/api/bson_decimal128_t.txt new file mode 100644 index 00000000..4d5a6409 --- /dev/null +++ b/source/libbson/api/bson_decimal128_t.txt @@ -0,0 +1,76 @@ +.. _bson_decimal128_t: + +================= +bson_decimal128_t +================= + +BSON Decimal128 Abstraction + +Synopsis +-------- + +.. code-block:: c + + #include + + #define BSON_DECIMAL128_STRING 43 + #define BSON_DECIMAL128_INF "Infinity" + #define BSON_DECIMAL128_NAN "NaN" + + typedef struct { + #if BSON_BYTE_ORDER == BSON_LITTLE_ENDIAN + uint64_t low; + uint64_t high; + #elif BSON_BYTE_ORDER == BSON_BIG_ENDIAN + uint64_t high; + uint64_t low; + #endif + } bson_decimal128_t; + +Description +----------- + +The :ref:`bson_decimal128_t` structure represents the IEEE-754 Decimal128 +data type. The type ``bson_decimal128_t`` is an aggregate that contains two +``uint64_t``\ s, named ``high`` and ``low``. The declaration and layout order +between them depends on the endian order of the target platform: ``low`` will +always correspond to the low-order bits of the Decimal128 object, while ``high`` +corresponds to the high-order bits. The ``bson_decimal128_t`` always has a size +of sixteen (``16``), and can be bit-cast to/from a ``_Decimal128``. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_decimal128_t/bson_decimal128_from_string + /libbson/api/bson_decimal128_t/bson_decimal128_from_string_w_len + /libbson/api/bson_decimal128_t/bson_decimal128_to_string + +- :ref:`bson_decimal128_from_string` +- :ref:`bson_decimal128_from_string_w_len` +- :ref:`bson_decimal128_to_string` + +Example +------- + +.. code-block:: c + + #include + #include + + int + main (int argc, char *argv[]) + { + char string[BSON_DECIMAL128_STRING]; + bson_decimal128_t decimal128; + + bson_decimal128_from_string ("100.00", &decimal128); + bson_decimal128_to_string (&decimal128, string); + printf ("Decimal128 value: %s\n", string); + + return 0; + } + diff --git a/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string.txt b/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string.txt new file mode 100644 index 00000000..1dff4824 --- /dev/null +++ b/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string.txt @@ -0,0 +1,42 @@ +.. _bson_decimal128_from_string: + +============================= +bson_decimal128_from_string() +============================= + +Synopsis +-------- + +.. code-block:: c + + bool + bson_decimal128_from_string (const char *string, bson_decimal128_t *dec); + +Parameters +---------- + +- ``string``: A string containing ASCII encoded Decimal128. +- ``dec``: A :ref:`bson_decimal128_t`. + +Description +----------- + +Parses the string containing ascii encoded Decimal128 and initialize the bytes +in ``dec``. See the `Decimal128 specification +`_ +for the exact string format. + +Returns +------- + +Returns ``true`` if valid Decimal128 string was provided, otherwise ``false`` +and ``dec`` will be set to ``NaN``. + +Example +------- + +.. code-block:: c + + bson_decimal128_t dec; + bson_decimal128_from_string ("1.00", &dec); + diff --git a/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string_w_len.txt b/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string_w_len.txt new file mode 100644 index 00000000..0d141cd1 --- /dev/null +++ b/source/libbson/api/bson_decimal128_t/bson_decimal128_from_string_w_len.txt @@ -0,0 +1,45 @@ +.. _bson_decimal128_from_string_w_len: + +=================================== +bson_decimal128_from_string_w_len() +=================================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_decimal128_from_string_w_len (const char *string, + int len, + bson_decimal128_t *dec); + +Parameters +---------- + +- ``string``: A string containing ASCII encoded Decimal128. +- ``len``: The length of ``string`` in bytes, or -1 meaning the string is null-terminated. +- ``dec``: A :ref:`bson_decimal128_t`. + +Description +----------- + +Parses the string containing ascii encoded Decimal128 and initialize the bytes +in ``dec``. See the `Decimal128 specification +`_ +for the exact string format. + +Returns +------- + +Returns ``true`` if valid Decimal128 string was provided, otherwise ``false`` +and ``dec`` will be set to ``NaN``. + +Example +------- + +.. code-block:: c + + bson_decimal128_t dec; + bson_decimal128_from_string_w_len ("1.00", 4, &dec); + bson_decimal128_from_string_w_len ("1.00", -1, &dec); diff --git a/source/libbson/api/bson_decimal128_t/bson_decimal128_to_string.txt b/source/libbson/api/bson_decimal128_t/bson_decimal128_to_string.txt new file mode 100644 index 00000000..9b56dc20 --- /dev/null +++ b/source/libbson/api/bson_decimal128_t/bson_decimal128_to_string.txt @@ -0,0 +1,33 @@ +.. _bson_decimal128_to_string: + +=========================== +bson_decimal128_to_string() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_decimal128_to_string (const bson_decimal128_t *dec, char *str); + +Parameters +---------- + +- ``dec``: A :refson_decimal128_t`. +- ``str``: A location of length BSON_DECIMAL128_STRING for the resulting string. + +Description +----------- + +Converts ``dec`` into a printable string. + +Example +------- + +.. code-block:: c + + char decimal128_string[BSON_DECIMAL128_STRING]; + bson_decimal128_to_string (&decimal128t, decimal128_string); + diff --git a/source/libbson/api/bson_error_t.txt b/source/libbson/api/bson_error_t.txt new file mode 100644 index 00000000..04213203 --- /dev/null +++ b/source/libbson/api/bson_error_t.txt @@ -0,0 +1,55 @@ +.. _bson_error_t: + +============ +bson_error_t +============ + +BSON Error Encapsulation + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct { + uint32_t domain; + uint32_t code; + char message[504]; + } bson_error_t; + +Description +----------- + +The :ref:`bson_error_t` structure is used as an out-parameter to pass error information to the caller. It should be stack-allocated and does not requiring freeing. + +See :ref:`Handling Errors `. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_error_t/bson_set_error + /libbson/api/bson_error_t/bson_strerror_r + +- :ref:`bson_set_error` +- :ref:`bson_strerror_r` + +Example +------- + +.. code-block:: c + + bson_reader_t *reader; + bson_error_t error; + + reader = bson_reader_new_from_file ("dump.bson", &error); + if (!reader) { + fprintf ( + stderr, "ERROR: %d.%d: %s\n", error.domain, error.code, error.message); + } + diff --git a/source/libbson/api/bson_error_t/bson_set_error.txt b/source/libbson/api/bson_error_t/bson_set_error.txt new file mode 100644 index 00000000..d4345789 --- /dev/null +++ b/source/libbson/api/bson_error_t/bson_set_error.txt @@ -0,0 +1,30 @@ +.. _bson_set_error: + +================ +bson_set_error() +================ + +Synopsis +-------- + +.. code-block:: c + + void + bson_set_error ( + bson_error_t *error, uint32_t domain, uint32_t code, const char *format, ...) + BSON_GNUC_PRINTF (4, 5); + +Parameters +---------- + +- ``error``: A :ref:`bson_error_t`. +- ``domain``: A ``uint32_t``. +- ``code``: A ``uint32_t``. +- ``format``: A ``printf()`` style format string. + +Description +----------- + +This is a helper function to set the parameters of a :ref:`bson_error_t`. It +handles the case where ``error`` is NULL by doing nothing. + diff --git a/source/libbson/api/bson_error_t/bson_strerror_r.txt b/source/libbson/api/bson_error_t/bson_strerror_r.txt new file mode 100644 index 00000000..93d89d6d --- /dev/null +++ b/source/libbson/api/bson_error_t/bson_strerror_r.txt @@ -0,0 +1,31 @@ +.. _bson_strerror_r: + +================= +bson_strerror_r() +================= + +Synopsis +-------- + +.. code-block:: c + + char * + bson_strerror_r (int err_code, char *buf, size_t buflen); + +Parameters +---------- + +- ``err_code``: An errno. +- ``buf``: A location to store the string. +- ``buflen``: The size of ``buf``. + +Description +----------- + +This is a portability wrapper around ``strerror()``. + +Returns +------- + +The passed in ``buf`` parameter or an internal string. + diff --git a/source/libbson/api/bson_get_monotonic_time.txt b/source/libbson/api/bson_get_monotonic_time.txt new file mode 100644 index 00000000..4c5078b6 --- /dev/null +++ b/source/libbson/api/bson_get_monotonic_time.txt @@ -0,0 +1,24 @@ +.. _bson_get_monotonic_time: + +============ +System Clock +============ + +BSON Clock Abstraction + +Synopsis +-------- + +.. code-block:: c + + int64_t + bson_get_monotonic_time (void); + int + bson_gettimeofday (struct timeval *tv); + +Description +----------- + +The clock abstraction in Libbson provides a cross-platform way to handle timeouts within +the BSON library. It abstracts the differences in implementations of ``gettimeofday()`` +as well as providing a monotonic (incrementing only) clock in microseconds. diff --git a/source/libbson/api/bson_iter_t.txt b/source/libbson/api/bson_iter_t.txt new file mode 100644 index 00000000..e8690f2a --- /dev/null +++ b/source/libbson/api/bson_iter_t.txt @@ -0,0 +1,236 @@ +.. _bson_iter_t: + +=========== +bson_iter_t +=========== + +BSON Document Iterator + +Synopsis +-------- + +.. code-block:: c + + #include + + #define BSON_ITER_HOLDS_DOUBLE(iter) /* ... */ + + #define BSON_ITER_HOLDS_UTF8(iter) /* ... */ + + #define BSON_ITER_HOLDS_DOCUMENT(iter) /* ... */ + + #define BSON_ITER_HOLDS_ARRAY(iter) /* ... */ + + #define BSON_ITER_HOLDS_BINARY(iter) /* ... */ + + #define BSON_ITER_HOLDS_UNDEFINED(iter) /* ... */ + + #define BSON_ITER_HOLDS_OID(iter) /* ... */ + + #define BSON_ITER_HOLDS_BOOL(iter) /* ... */ + + #define BSON_ITER_HOLDS_DATE_TIME(iter) /* ... */ + + #define BSON_ITER_HOLDS_NULL(iter) /* ... */ + + #define BSON_ITER_HOLDS_REGEX(iter) /* ... */ + + #define BSON_ITER_HOLDS_DBPOINTER(iter) /* ... */ + + #define BSON_ITER_HOLDS_CODE(iter) /* ... */ + + #define BSON_ITER_HOLDS_SYMBOL(iter) /* ... */ + + #define BSON_ITER_HOLDS_CODEWSCOPE(iter) /* ... */ + + #define BSON_ITER_HOLDS_INT32(iter) /* ... */ + + #define BSON_ITER_HOLDS_TIMESTAMP(iter) /* ... */ + + #define BSON_ITER_HOLDS_INT64(iter) /* ... */ + + #define BSON_ITER_HOLDS_DECIMAL128(iter) /* ... */ + + #define BSON_ITER_HOLDS_MAXKEY(iter) /* ... */ + + #define BSON_ITER_HOLDS_MINKEY(iter) /* ... */ + + #define BSON_ITER_HOLDS_INT(iter) \ + (BSON_ITER_HOLDS_INT32 (iter) || BSON_ITER_HOLDS_INT64 (iter)) + + #define BSON_ITER_HOLDS_NUMBER(iter) \ + (BSON_ITER_HOLDS_INT (iter) || BSON_ITER_HOLDS_DOUBLE (iter)) + + #define BSON_ITER_IS_KEY(iter, key) \ + (0 == strcmp ((key), bson_iter_key ((iter)))) + + typedef struct { + /*< private >*/ + } bson_iter_t; + +Description +----------- + +:ref:`bson_iter_t` is a structure used to iterate through the elements of a :ref:`bson_t`. +It is meant to be used on the stack and can be discarded at any time as it contains no external +allocation. The contents of the structure should be considered private and may change between +releases, however the structure size will not change. + +The :ref:`bson_t` *MUST* be valid for the lifetime of the iter and it is an error to modify the +:ref:`bson_t` while using the iter. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_iter_t/bson_iter_array + /libbson/api/bson_iter_t/bson_iter_as_bool + /libbson/api/bson_iter_t/bson_iter_as_double + /libbson/api/bson_iter_t/bson_iter_as_int64 + /libbson/api/bson_iter_t/bson_iter_binary + /libbson/api/bson_iter_t/bson_iter_bool + /libbson/api/bson_iter_t/bson_iter_code + /libbson/api/bson_iter_t/bson_iter_codewscope + /libbson/api/bson_iter_t/bson_iter_date_time + /libbson/api/bson_iter_t/bson_iter_dbpointer + /libbson/api/bson_iter_t/bson_iter_decimal128 + /libbson/api/bson_iter_t/bson_iter_document + /libbson/api/bson_iter_t/bson_iter_double + /libbson/api/bson_iter_t/bson_iter_dup_utf8 + /libbson/api/bson_iter_t/bson_iter_find + /libbson/api/bson_iter_t/bson_iter_find_case + /libbson/api/bson_iter_t/bson_iter_find_descendant + /libbson/api/bson_iter_t/bson_iter_find_w_len + /libbson/api/bson_iter_t/bson_iter_init + /libbson/api/bson_iter_t/bson_iter_init_find + /libbson/api/bson_iter_t/bson_iter_init_find_case + /libbson/api/bson_iter_t/bson_iter_init_find_w_len + /libbson/api/bson_iter_t/bson_iter_init_from_data + /libbson/api/bson_iter_t/bson_iter_init_from_data_at_offset + /libbson/api/bson_iter_t/bson_iter_int32 + /libbson/api/bson_iter_t/bson_iter_int64 + /libbson/api/bson_iter_t/bson_iter_key + /libbson/api/bson_iter_t/bson_iter_key_len + /libbson/api/bson_iter_t/bson_iter_next + /libbson/api/bson_iter_t/bson_iter_offset + /libbson/api/bson_iter_t/bson_iter_oid + /libbson/api/bson_iter_t/bson_iter_overwrite_bool + /libbson/api/bson_iter_t/bson_iter_overwrite_date_time + /libbson/api/bson_iter_t/bson_iter_overwrite_decimal128 + /libbson/api/bson_iter_t/bson_iter_overwrite_double + /libbson/api/bson_iter_t/bson_iter_overwrite_int32 + /libbson/api/bson_iter_t/bson_iter_overwrite_int64 + /libbson/api/bson_iter_t/bson_iter_overwrite_oid + /libbson/api/bson_iter_t/bson_iter_overwrite_timestamp + /libbson/api/bson_iter_t/bson_iter_recurse + /libbson/api/bson_iter_t/bson_iter_regex + /libbson/api/bson_iter_t/bson_iter_symbol + /libbson/api/bson_iter_t/bson_iter_time_t + /libbson/api/bson_iter_t/bson_iter_timestamp + /libbson/api/bson_iter_t/bson_iter_timeval + /libbson/api/bson_iter_t/bson_iter_type + /libbson/api/bson_iter_t/bson_iter_utf8 + /libbson/api/bson_iter_t/bson_iter_value + /libbson/api/bson_iter_t/bson_iter_visit_all + +- :ref:`bson_iter_array` +- :ref:`bson_iter_as_bool` +- :ref:`bson_iter_as_double` +- :ref:`bson_iter_as_int64` +- :ref:`bson_iter_binary` +- :ref:`bson_iter_bool` +- :ref:`bson_iter_code` +- :ref:`bson_iter_codewscope` +- :ref:`bson_iter_date_time` +- :ref:`bson_iter_dbpointer` +- :ref:`bson_iter_decimal128` +- :ref:`bson_iter_document` +- :ref:`bson_iter_double` +- :ref:`bson_iter_dup_utf8` +- :ref:`bson_iter_find` +- :ref:`bson_iter_find_case` +- :ref:`bson_iter_find_descendant` +- :ref:`bson_iter_find_w_len` +- :ref:`bson_iter_init` +- :ref:`bson_iter_init_find` +- :ref:`bson_iter_init_find_case` +- :ref:`bson_iter_find_descendant` +- :ref:`bson_iter_find_w_len` +- :ref:`bson_iter_init` +- :ref:`bson_iter_init_find` +- :ref:`bson_iter_init_find_case` +- :ref:`bson_iter_init_find_w_len` +- :ref:`bson_iter_init_from_data` +- :ref:`bson_iter_init_from_data_at_offset` +- :ref:`bson_iter_int32` +- :ref:`bson_iter_int64` +- :ref:`bson_iter_key` +- :ref:`bson_iter_key_len` +- :ref:`bson_iter_next` +- :ref:`bson_iter_offset` +- :ref:`bson_iter_oid` +- :ref:`bson_iter_overwrite_bool` +- :ref:`bson_iter_overwrite_date_time` +- :ref:`bson_iter_overwrite_decimal128` +- :ref:`bson_iter_overwrite_double` +- :ref:`bson_iter_overwrite_int32` +- :ref:`bson_iter_overwrite_int64` +- :ref:`bson_iter_overwrite_oid` +- :ref:`bson_iter_overwrite_timestamp` +- :ref:`bson_iter_recurse` +- :ref:`bson_iter_regex` +- :ref:`bson_iter_symbol` +- :ref:`bson_iter_time_t` +- :ref:`bson_iter_timestamp` +- :ref:`bson_iter_timeval` +- :ref:`bson_iter_type` +- :ref:`bson_iter_utf8` +- :ref:`bson_iter_value` +- :ref:`bson_iter_visit_all` + +Examples +-------- + +.. code-block:: c + + bson_iter_t iter; + + if (bson_iter_init (&iter, my_bson_doc)) { + while (bson_iter_next (&iter)) { + printf ("Found a field named: %s\n", bson_iter_key (&iter)); + } + } + +.. code-block:: c + + bson_iter_t iter; + + if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) { + printf ("Found the field named: %s\n", bson_iter_key (&iter)); + } + +.. code-block:: c + + bson_iter_t iter; + bson_iter_t sub_iter; + + if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") && + (BSON_ITER_HOLDS_DOCUMENT (&iter) || BSON_ITER_HOLDS_ARRAY (&iter)) && + bson_iter_recurse (&iter, &sub_iter)) { + while (bson_iter_next (&sub_iter)) { + printf ("Found key \"%s\" in sub document.\n", bson_iter_key (&sub_iter)); + } + } + +.. code-block:: c + + bson_iter_t iter; + + if (bson_iter_init (&iter, my_doc) && + bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) { + printf ("The type of a.b.c.d is: %d\n", (int) bson_iter_type (&sub_iter)); + } + diff --git a/source/libbson/api/bson_iter_t/bson_iter_array.txt b/source/libbson/api/bson_iter_t/bson_iter_array.txt new file mode 100644 index 00000000..fedc7e8f --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_array.txt @@ -0,0 +1,33 @@ +.. _bson_iter_array: + +================= +bson_iter_array() +================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_ARRAY(iter) (bson_iter_type ((iter)) == BSON_TYPE_ARRAY) + + void + bson_iter_array (const bson_iter_t *iter, + uint32_t *array_len, + const uint8_t **array); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``array_len``: A location for the buffer length. +- ``array``: A location for the immutable buffer. + +Description +----------- + +The ``bson_iter_array()`` function shall retrieve the raw buffer of a sub-array +from ``iter``. ``iter`` *MUST* be on an element that is of type BSON_TYPE_ARRAY. +This can be verified with :ref:`bson_iter_type` or the ``BSON_ITER_HOLDS_ARRAY()`` +macro. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_as_bool.txt b/source/libbson/api/bson_iter_t/bson_iter_as_bool.txt new file mode 100644 index 00000000..f4aab4c4 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_as_bool.txt @@ -0,0 +1,41 @@ +.. _bson_iter_as_bool: + +=================== +bson_iter_as_bool() +=================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_as_bool (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the current field as if it were a boolean. + +``bson_iter_as_bool()`` currently knows how to determine a boolean value from the following types: + +- BSON_TYPE_BOOL +- BSON_TYPE_DOUBLE +- BSON_TYPE_INT32 +- BSON_TYPE_INT64 +- BSON_TYPE_NULL +- BSON_TYPE_UNDEFINED +- BSON_TYPE_UTF8 + +BSON_TYPE_UTF8 will always equate to ``true``. + +Returns +------- + +True if the field equates to non-zero. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_as_double.txt b/source/libbson/api/bson_iter_t/bson_iter_as_double.txt new file mode 100644 index 00000000..4011bded --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_as_double.txt @@ -0,0 +1,38 @@ +.. _bson_iter_as_double: + +===================== +bson_iter_as_double() +===================== + +Synopsis +-------- + +.. code-block:: c + + double + bson_iter_as_double (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` + +Description +----------- + +Fetches the current field as if it were a double. + +``bson_iter_as_double()`` will cast the following types to double + +- BSON_TYPE_BOOL +- BSON_TYPE_DOUBLE +- BSON_TYPE_INT32 +- BSON_TYPE_INT64 + +Any other value will return 0. + +Returns +------- + +The value type casted to double. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_as_int64.txt b/source/libbson/api/bson_iter_t/bson_iter_as_int64.txt new file mode 100644 index 00000000..de64085f --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_as_int64.txt @@ -0,0 +1,35 @@ +.. _bson_iter_as_int64: + +==================== +bson_iter_as_int64() +==================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + bson_iter_as_int64 (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +The ``bson_iter_as_int64()`` function shall return the contents of the current element +as if it were a BSON_TYPE_INT64 element. The currently supported casts include: + +- BSON_TYPE_BOOL +- BSON_TYPE_DOUBLE +- BSON_TYPE_INT32 +- BSON_TYPE_INT64 + +Returns +------- + +A 64-bit signed integer. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_binary.txt b/source/libbson/api/bson_iter_t/bson_iter_binary.txt new file mode 100644 index 00000000..45c2a8e3 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_binary.txt @@ -0,0 +1,38 @@ +.. _bson_iter_binary: + +================== +bson_iter_binary() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_BINARY(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_BINARY) + + void + bson_iter_binary (const bson_iter_t *iter, + bson_subtype_t *subtype, + uint32_t *binary_len, + const uint8_t **binary); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``subtype``: A location for a :ref:`bson_subtype_t` or NULL. +- ``binary_len``: A location for the length of ``binary``. +- ``binary``: A location for a pointer to the immutable buffer. + +Description +----------- + +This function shall return the binary data of a BSON_TYPE_BINARY element. It is a +programming error to call this function on a field that is not of type BSON_TYPE_BINARY. +You can check this with the BSON_ITER_HOLDS_BINARY() macro or :ref:`bson_iter_type`. + +The buffer that ``binary`` points to is only valid until the iterator's :ref:`bson_t` is +modified or freed. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_bool.txt b/source/libbson/api/bson_iter_t/bson_iter_bool.txt new file mode 100644 index 00000000..33718458 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_bool.txt @@ -0,0 +1,33 @@ +.. _bson_iter_bool: + +================ +bson_iter_bool() +================ + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_BOOL(iter) (bson_iter_type ((iter)) == BSON_TYPE_BOOL) + + bool + bson_iter_bool (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +The ``bson_iter_bool()`` function shall return the boolean value of a BSON_TYPE_BOOL element. It +is a programming error to call this function on an element other than BSON_TYPE_BOOL. You can +check this with :ref:`bson_iter_type` or ``BSON_ITER_HOLDS_BOOL()``. + +Returns +------- + +Either ``true`` or ``false``. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_code.txt b/source/libbson/api/bson_iter_t/bson_iter_code.txt new file mode 100644 index 00000000..a474fbaf --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_code.txt @@ -0,0 +1,34 @@ +.. _bson_iter_code: + +================ +bson_iter_code() +================ + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_CODE(iter) (bson_iter_type ((iter)) == BSON_TYPE_CODE) + + const char * + bson_iter_code (const bson_iter_t *iter, uint32_t *length); + +Parameters +---------- + +- ``iter``: A :refson_iter_t`. +- ``length``: A location for the length of the UTF-8 encoded string or NULL. + +Description +----------- + +This function returns the contents of a BSON_TYPE_CODE field. The length of the string is stored in ``length`` if non-NULL. + +It is invalid to call this function on a field that is not of type BSON_TYPE_CODE. + +Returns +------- + +A UTF-8 encoded string which should not be modified or freed. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_codewscope.txt b/source/libbson/api/bson_iter_t/bson_iter_codewscope.txt new file mode 100644 index 00000000..ddf7eaee --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_codewscope.txt @@ -0,0 +1,40 @@ +.. _bson_iter_codewscope: + +====================== +bson_iter_codewscope() +====================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_CODEWSCOPE(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_CODEWSCOPE) + + const char * + bson_iter_codewscope (const bson_iter_t *iter, + uint32_t *length, + uint32_t *scope_len, + const uint8_t **scope); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``length``: An optional location for the length of the resulting UTF-8 encoded string. +- ``scope_len``: A optional location for the length of ``scope``. +- ``scope``: An optional location to store the immutable raw scope BSON document. + +Description +----------- + +The ``bson_iter_codewscope()`` function acts similar to :ref:`bson_iter_code` except for +BSON_TYPE_CODEWSCOPE elements. It also will provide a pointer to the buffer for scope, which +can be loaded into a :ref:`bson_t` using :ref:`bson_init_static` + +Returns +------- + +An UTF-8 encoded string containing the JavaScript code which should not be modified or freed. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_date_time.txt b/source/libbson/api/bson_iter_t/bson_iter_date_time.txt new file mode 100644 index 00000000..ef5de92f --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_date_time.txt @@ -0,0 +1,33 @@ +.. _bson_iter_date_time: + +===================== +bson_iter_date_time() +===================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_DATE_TIME(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_DATE_TIME) + + int64_t + bson_iter_date_time (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` + +Description +----------- + +The bson_iter_date_time() function shall return the number of milliseconds since the UNIX epoch, +as contained in the BSON_TYPE_DATE_TIME element. + +Returns +------- + +A 64-bit integer containing the number of milliseconds since the UNIX epoch. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_dbpointer.txt b/source/libbson/api/bson_iter_t/bson_iter_dbpointer.txt new file mode 100644 index 00000000..7b48ecfc --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_dbpointer.txt @@ -0,0 +1,34 @@ +.. _bson_iter_dbpointer: + +===================== +bson_iter_dbpointer() +===================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_dbpointer (const bson_iter_t *iter, + uint32_t *collection_len, + const char **collection, + const bson_oid_t **oid); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``collection_len``: A location for the length of the collection name. +- ``collection``: A location for the collection name.. +- ``oid``: A location for a :ref:`bson_oid_t` + +Description +----------- + +Fetches the contents of a BSON_TYPE_DBPOINTER element. + +.. warning:: + + The BSON_TYPE_DBPOINTER field type is deprecated by the BSON spec and should not be used in new code. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_decimal128.txt b/source/libbson/api/bson_iter_t/bson_iter_decimal128.txt new file mode 100644 index 00000000..ee177ab3 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_decimal128.txt @@ -0,0 +1,34 @@ +.. _bson_iter_decimal128: + +====================== +bson_iter_decimal128() +====================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_DECIMAL128(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_DECIMAL128) + + bool + bson_iter_decimal128 (const bson_iter_t *iter, /* IN */ + bson_decimal128_t *dec); /* OUT */ + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``dec``: A location for a :ref:`bson_decimal128_t`. + +Description +----------- + +Fetches the value from a BSON_TYPE_DECIMAL128 field. You should verify that this is a BSON_TYPE_DECIMAL128 field before calling this function. + +Returns +------- + +true if type was BSON_TYPE_DECIMAL128, otherwise false. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_document.txt b/source/libbson/api/bson_iter_t/bson_iter_document.txt new file mode 100644 index 00000000..064f0fec --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_document.txt @@ -0,0 +1,33 @@ +.. _bson_iter_document: + +==================== +bson_iter_document() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_DOCUMENT(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_DOCUMENT) + + void + bson_iter_document (const bson_iter_t *iter, + uint32_t *document_len, + const uint8_t **document); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``document_len``: A location for the length of the document in bytes. +- ``document``: A location for the document buffer. + +Description +----------- + +The ``bson_iter_document()`` function shall retrieve the raw buffer of a sub-document from ``iter``. +``iter`` *MUST* be on an element that is of type BSON_TYPE_DOCUMENT. This can be verified with +:ref:`bson_iter_type` or the ``BSON_ITER_HOLDS_DOCUMENT()`` macro. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_double.txt b/source/libbson/api/bson_iter_t/bson_iter_double.txt new file mode 100644 index 00000000..81b8c5a1 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_double.txt @@ -0,0 +1,32 @@ +.. _bson_iter_double: + +================== +bson_iter_double() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_DOUBLE(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_DOUBLE) + + double + bson_iter_double (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` + +Description +----------- + +Fetches the contents of a BSON_TYPE_DOUBLE field. + +Returns +------- + +A double. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_dup_utf8.txt b/source/libbson/api/bson_iter_t/bson_iter_dup_utf8.txt new file mode 100644 index 00000000..f956c9dc --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_dup_utf8.txt @@ -0,0 +1,30 @@ +.. _bson_iter_dup_utf8: + +==================== +bson_iter_dup_utf8() +==================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_iter_dup_utf8 (const bson_iter_t *iter, uint32_t *length); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``length``: An optional location for the length of the UTF-8 encoded string. + +Description +----------- + +This function is similar to :ref:`bson_iter_utf8` except that it calls :ref:`bson_strndup` on the result. + +Returns +------- + +A newly allocated string that should be freed with :ref:`bson_free` + diff --git a/source/libbson/api/bson_iter_t/bson_iter_find.txt b/source/libbson/api/bson_iter_t/bson_iter_find.txt new file mode 100644 index 00000000..c64612ea --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_find.txt @@ -0,0 +1,34 @@ +.. _bson_iter_find: + +================ +bson_iter_find() +================ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_find (bson_iter_t *iter, const char *key); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``key``: A string containing the requested key. + +Description +----------- + +The ``bson_iter_find()`` function shall advance ``iter`` to the first element named ``key`` or exhaust +all elements of ``iter``. If ``iter`` is exhausted, false is returned and ``iter`` should be considered +invalid. + +``key`` is case-sensitive. For a case-folded version, see :ref:`bson_iter_find_case`. + +Returns +------- + +true is returned if the requested key was found. If not, ``iter`` was exhausted and should now be considered invalid. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_find_case.txt b/source/libbson/api/bson_iter_t/bson_iter_find_case.txt new file mode 100644 index 00000000..3e315768 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_find_case.txt @@ -0,0 +1,32 @@ +.. _bson_iter_find_case: + +===================== +bson_iter_find_case() +===================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_find_case (bson_iter_t *iter, const char *key); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``key``: An ASCII string containing the field to locate. + +Description +----------- + +Advances ``iter`` to the first element matching the name of ``key`` or exhausting all elements. + +``key`` is not case-sensitive. The keys will be case-folded to determine a match using the current locale. + +Returns +------- + +true if ``key`` was found. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_find_descendant.txt b/source/libbson/api/bson_iter_t/bson_iter_find_descendant.txt new file mode 100644 index 00000000..39d6e8ae --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_find_descendant.txt @@ -0,0 +1,36 @@ +.. _bson_iter_find_descendant: + +=========================== +bson_iter_find_descendant() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_find_descendant (bson_iter_t *iter, + const char *dotkey, + bson_iter_t *descendant); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``dotkey``: A dot-notation key like ``"a.b.c.d"``. +- ``descendant``: A :ref:`bson_iter_t` + +Description +----------- + +The :ref:`bson_iter_find_descendant` function shall follow standard MongoDB dot notation to +recurse into subdocuments. ``descendant`` will be initialized and advanced to the descendant. +If false is returned, both ``iter`` and ``descendant`` should be considered invalid. + +Returns +------- + +true is returned if the requested key was found. If not, false is returned and ``iter`` was exhausted +and should now be considered invalid. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_find_w_len.txt b/source/libbson/api/bson_iter_t/bson_iter_find_w_len.txt new file mode 100644 index 00000000..436e8be9 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_find_w_len.txt @@ -0,0 +1,35 @@ +.. _bson_iter_find_w_len: + +====================== +bson_iter_find_w_len() +====================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_find_w_len (bson_iter_t *iter, const char *key, int keylen); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``key``: A string containing the requested key. +- ``keylen``: An integer indicating the length of the key string. + +Description +----------- + +The ``bson_iter_find_w_len()`` function shall advance ``iter`` to the first element named ``key`` or +exhaust all elements of ``iter``. If ``iter`` is exhausted, false is returned and ``iter`` should be +considered invalid. + +``key`` is case-sensitive. For a case-folded version, see :ref:`bson_iter_find_case` + +Returns +------- + +true is returned if the requested key was found. If not, ``iter`` was exhausted and should now be considered invalid. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_init.txt b/source/libbson/api/bson_iter_t/bson_iter_init.txt new file mode 100644 index 00000000..388d4481 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init.txt @@ -0,0 +1,73 @@ +.. _bson_iter_init: + +================ +bson_iter_init() +================ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init (bson_iter_t *iter, const bson_t *bson); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``bson``: A :ref:`bson_t` + +Description +----------- + +The ``bson_iter_init()`` function shall initialize ``iter`` to iterate upon the BSON document +``bson``. Upon initialization, ``iter`` is placed before the first element. Callers must call +:ref:`bson_iter_next`, :ref:`bson_iter_find`, or :ref:`bson_iter_find_case` to advance to an element. + +Returns +------- + +Returns true if the iter was successfully initialized. + +Example +------- + +.. code-block:: c + + static void + print_doc_id (const bson_t *doc) + { + bson_iter_t iter; + bson_oid_t oid; + char oidstr[25]; + + if (bson_iter_init (&iter, doc) && bson_iter_find (&iter, "_id") && + BSON_ITER_HOLDS_OID (&iter)) { + bson_iter_oid (&iter, &oid); + bson_oid_to_string (&oid, oidstr); + printf ("%s\n", oidstr); + } else { + printf ("Document is missing _id.\n"); + } + } + + /* alternatively */ + + static void + print_doc_id (const bson_t *doc) + { + bson_iter_t iter; + bson_oid_t oid; + char oidstr[25]; + + if (bson_iter_init_find (&iter, doc, "_id") && BSON_ITER_HOLDS_OID (&iter)) { + bson_iter_oid (&iter, &oid); + bson_oid_to_string (&oid, oidstr); + printf ("%s\n", oidstr); + } else { + printf ("Document is missing _id.\n"); + } + } + +.. include:: /libbson/includes/seealso/iter-init.rst diff --git a/source/libbson/api/bson_iter_t/bson_iter_init_find.txt b/source/libbson/api/bson_iter_t/bson_iter_init_find.txt new file mode 100644 index 00000000..39b7b1b1 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init_find.txt @@ -0,0 +1,27 @@ +.. _bson_iter_init_find: + +===================== +bson_iter_init_find() +===================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init_find (bson_iter_t *iter, const bson_t *bson, const char *key); + +Parameters +---------- + +- ``iter``: A :refson_iter_t`. +- ``bson``: A :ref:`bson_t`. +- ``key``: A key to locate after initializing the iter. + +Description +----------- + +This function is identical to ``(bson_iter_init() && bson_iter_find())``. + +.. include:: /libbson/includes/seealso/iter-init.rst diff --git a/source/libbson/api/bson_iter_t/bson_iter_init_find_case.txt b/source/libbson/api/bson_iter_t/bson_iter_init_find_case.txt new file mode 100644 index 00000000..f1096d7b --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init_find_case.txt @@ -0,0 +1,29 @@ +.. _bson_iter_init_find_case: + +========================== +bson_iter_init_find_case() +========================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init_find_case (bson_iter_t *iter, + const bson_t *bson, + const char *key); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``bson``: A :ref:`bson_t`. +- ``key``: A key to locate after initializing the iter. + +Description +----------- + +This function is identical to ``bson_iter_init() && bson_iter_find_case()``. + +.. include:: /libbson/includes/seealso/iter-init.rst \ No newline at end of file diff --git a/source/libbson/api/bson_iter_t/bson_iter_init_find_w_len.txt b/source/libbson/api/bson_iter_t/bson_iter_init_find_w_len.txt new file mode 100644 index 00000000..fa01c4bf --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init_find_w_len.txt @@ -0,0 +1,31 @@ +.. _bson_iter_init_find_w_len: + +=========================== +bson_iter_init_find_w_len() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init_find_w_len (bson_iter_t *iter, + const bson_t *bson, + const char *key, + int keylen); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``bson``: A :ref:`bson_t` +- ``key``: A key to locate after initializing the iter. +- ``keylen``: An integer indicating the length of the key string. + +Description +----------- + +This function is identical to ``(bson_iter_init() && bson_iter_find_w_len())``. + +.. include:: /libbson/includes/seealso/iter-init.rst diff --git a/source/libbson/api/bson_iter_t/bson_iter_init_from_data.txt b/source/libbson/api/bson_iter_t/bson_iter_init_from_data.txt new file mode 100644 index 00000000..f04125f4 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init_from_data.txt @@ -0,0 +1,57 @@ +.. _bson_iter_init_from_data: + +========================== +bson_iter_init_from_data() +========================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init_from_data (bson_iter_t *iter, const uint8_t *data, size_t length); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``data``: A buffer to initialize with. +- ``length``: The length of ``data`` in bytes. + +Description +----------- + +The ``bson_iter_init_from_data()`` function shall initialize ``iter`` to iterate upon the buffer ``data``, +which must contain a BSON document. Upon initialization, ``iter`` is placed before the first element. +Callers must call :ref:`bson_iter_next`, :ref:`bson_iter_find`, or :ref:`bson_iter_find_case` to +advance to an element. + +Returns +------- + +Returns true if the iter was successfully initialized. + +Example +------- + +.. code-block:: c + + static void + print_doc_id (const uint8_t *data, size_t length) + { + bson_iter_t iter; + bson_oid_t oid; + char oidstr[25]; + + if (bson_iter_init_from_data (&iter, data, length) && bson_iter_find (&iter, "_id") && + BSON_ITER_HOLDS_OID (&iter)) { + bson_iter_oid (&iter, &oid); + bson_oid_to_string (&oid, oidstr); + printf ("%s\n", oidstr); + } else { + printf ("Document is missing _id.\n"); + } + } + +.. include:: /libbson/includes/seealso/iter-init.rst diff --git a/source/libbson/api/bson_iter_t/bson_iter_init_from_data_at_offset.txt b/source/libbson/api/bson_iter_t/bson_iter_init_from_data_at_offset.txt new file mode 100644 index 00000000..c4465a14 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_init_from_data_at_offset.txt @@ -0,0 +1,62 @@ +.. _bson_iter_init_from_data_at_offset: + +==================================== +bson_iter_init_from_data_at_offset() +==================================== + + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_init_from_data_at_offset (bson_iter_t *iter, + const uint8_t *data, + size_t length, + uint32_t offset, + uint32_t keylen); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``data``: A buffer to initialize with. This is not validated. +- ``length``: The length of ``data`` in bytes. This is not validated. +- ``offset``: The offset of the field to start iterating. This is not validated. This + should be an offset previously obtained from :ref:`bson_iter_offset`. +- ``keylen``: The string length of the key of the field to start iterating. This is not validated. + This should be a length previously obtained from :ref:`bson_iter_key_len`. + +Description +----------- + +Creates a :ref:`bson_iter_t` and starts iteration on a field at the offset. + +:ref:`bson_iter_init_from_data_at_offset` is useful for situations where the +progress of a :ref:`bson_iter_t` must be saved and restored without relying +on the :ref:`bson_iter_t` data layout. Saving the progress could be +accomplished by: + +- Saving the current field's key length with :ref:`bson_iter_key_len` +- Saving the current offset with :ref:`bson_iter_offset` +- Saving the data pointer of the iterated :ref:`bson_t` with :ref:`bson_get_data` +- Saving the data length of the iterated :ref:`bson_t` with the ``len`` struct field + +Then later, these saved values can be passed to +:ref:`bson_iter_init_from_data_at_offset` to reconstruct the +:ref:`bson_iter_t` in constant time. + +Returns +------- + +Returns true if the iter was successfully initialized. + +.. seealso:: + + | :ref:`bson_iter_key_len` + + | :ref:`bson_iter_offset` + + | :ref:`bson_get_data` + diff --git a/source/libbson/api/bson_iter_t/bson_iter_int32.txt b/source/libbson/api/bson_iter_t/bson_iter_int32.txt new file mode 100644 index 00000000..f1a5d08a --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_int32.txt @@ -0,0 +1,32 @@ +.. _bson_iter_int32: + +================= +bson_iter_int32() +================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_INT32(iter) (bson_iter_type ((iter)) == BSON_TYPE_INT32) + + int32_t + bson_iter_int32 (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the value from a BSON_TYPE_INT32 element. You should verify that the field is a BSON_TYPE_INT32 +field before calling this function. + +Returns +------- + +A 32-bit integer. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_int64.txt b/source/libbson/api/bson_iter_t/bson_iter_int64.txt new file mode 100644 index 00000000..f8e3bf17 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_int64.txt @@ -0,0 +1,32 @@ +.. _bson_iter_int64: + +================= +bson_iter_int64() +================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_INT64(iter) (bson_iter_type ((iter)) == BSON_TYPE_INT64) + + int64_t + bson_iter_int64 (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the value from a BSON_TYPE_INT64 field. You should verify that this is a BSON_TYPE_INT64 +field before calling this function. + +Returns +------- + +A 64-bit integer. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_key.txt b/source/libbson/api/bson_iter_t/bson_iter_key.txt new file mode 100644 index 00000000..5d6fd478 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_key.txt @@ -0,0 +1,33 @@ +.. _bson_iter_key: + +=============== +bson_iter_key() +=============== + +Synopsis +-------- + +.. code-block:: c + + const char * + bson_iter_key (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the key for the current element observed by ``iter``. + +Returns +------- + +A string which should not be modified or freed. + +.. seealso:: + + | :ref:`bson_iter_key_len` to retrieve the length of the key in constant time. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_key_len.txt b/source/libbson/api/bson_iter_t/bson_iter_key_len.txt new file mode 100644 index 00000000..2bb749eb --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_key_len.txt @@ -0,0 +1,35 @@ +.. _bson_iter_key_len: + +=================== +bson_iter_key_len() +=================== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + bson_iter_key_len (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the length of the key for the current element observed by ``iter``. This is a +constant time computation, and therefore faster than calling ``strlen()`` on a key returned +by :ref:`bson_iter_key`. + +Returns +------- + +An integer representing the key length. + +.. seealso:: + + | :ref:`bson_iter_key` to retrieve current key. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_next.txt b/source/libbson/api/bson_iter_t/bson_iter_next.txt new file mode 100644 index 00000000..59693f1a --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_next.txt @@ -0,0 +1,32 @@ +.. _bson_iter_next: + +================ +bson_iter_next() +================ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_next (bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Advances ``iter`` to the next element in the document. + +Returns +------- + +true if ``iter`` was advanced. Returns false if ``iter`` has passed the last element in the +document or encountered invalid BSON. + +It is a programming error to use ``iter`` after this function has returned false. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_offset.txt b/source/libbson/api/bson_iter_t/bson_iter_offset.txt new file mode 100644 index 00000000..f5e39ffa --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_offset.txt @@ -0,0 +1,33 @@ +.. _bson_iter_offset: + +================== +bson_iter_offset() +================== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + bson_iter_offset (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` + +Description +----------- + +Fetches the offset for the current element observed by ``iter``. + +Returns +------- + +An unsigned integer representing the offset in the BSON data of the current element. + +.. seealso:: + + | :ref:`bson_iter_init_from_data_at_offset` to use this offset to reconstruct a :ref:`bson_iter_t` in constant time. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_oid.txt b/source/libbson/api/bson_iter_t/bson_iter_oid.txt new file mode 100644 index 00000000..795709ef --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_oid.txt @@ -0,0 +1,32 @@ +.. _bson_iter_oid: + +=============== +bson_iter_oid() +=============== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_OID(iter) (bson_iter_type ((iter)) == BSON_TYPE_OID) + + const bson_oid_t * + bson_iter_oid (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the :ref:`bson_oid_t` for a BSON_TYPE_OID element. You should verify it is an element of type +BSON_TYPE_OID before calling this function. + +Returns +------- + +A :ref:`bson_oid_t` that should not be modified or freed. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_bool.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_bool.txt new file mode 100644 index 00000000..3d4d93c6 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_bool.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_bool: + +========================== +bson_iter_overwrite_bool() +========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_bool (bson_iter_t *iter, bool value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``value``: A bool containing the new value. + +Description +----------- + +The ``bson_iter_overwrite_bool()`` function shall overwrite the contents of a BSON_TYPE_BOOL element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_BOOL. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_date_time.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_date_time.txt new file mode 100644 index 00000000..58c0b4b0 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_date_time.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_date_time: + +=============================== +bson_iter_overwrite_date_time() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_date_time (bson_iter_t *iter, int64_t value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``value``: The date and time as specified in milliseconds since the UNIX epoch. + +Description +----------- + +The ``bson_iter_overwrite_date_time()`` function shall overwrite the contents of a BSON_TYPE_DATE_TIME element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_DATE_TIME. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_decimal128.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_decimal128.txt new file mode 100644 index 00000000..2b8f3948 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_decimal128.txt @@ -0,0 +1,30 @@ +.. _bson_iter_overwrite_decimal128: + +================================ +bson_iter_overwrite_decimal128() +================================ + +Synopsis +-------- + +.. code-block:: c + + ool + bson_iter_overwrite_decimal128 (bson_iter_t *iter, const bson_decimal128_t *value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``value``: The new Decimal128 value. + +Description +----------- + +The :ref:`bson_iter_overwrite_decimal128` function shall overwrite the contents of a BSON_TYPE_DECIMAL128 +element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_DECIMAL128. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_double.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_double.txt new file mode 100644 index 00000000..3e2667ce --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_double.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_double: + +============================ +bson_iter_overwrite_double() +============================ + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_double (bson_iter_t *iter, double value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``value``: The new double value. + +Description +----------- + +The :ref:`bson_iter_overwrite_double` function shall overwrite the contents of a BSON_TYPE_DOUBLE element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_DOUBLE. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_int32.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_int32.txt new file mode 100644 index 00000000..e564e51c --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_int32.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_int32: + +=========================== +bson_iter_overwrite_int32() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_int32 (bson_iter_t *iter, int32_t value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``value``: A int32_t. + +Description +----------- + +The :ref:`bson_iter_overwrite_int32` function shall overwrite the contents of a BSON_TYPE_INT32 element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_BOOL. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_int64.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_int64.txt new file mode 100644 index 00000000..22ce58f3 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_int64.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_int64: + +=========================== +bson_iter_overwrite_int64() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_int64 (bson_iter_t *iter, int64_t value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t` +- ``value``: A int64_t. + +Description +----------- + +The :ref:`bson_iter_overwrite_int64` function shall overwrite the contents of a BSON_TYPE_INT64 element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_INT64. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_oid.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_oid.txt new file mode 100644 index 00000000..7c4c8b97 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_oid.txt @@ -0,0 +1,29 @@ +.. _bson_iter_overwrite_oid: + +========================= +bson_iter_overwrite_oid() +========================= + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_oid (bson_iter_t *iter, const bson_oid_t *value); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``oid``: A :ref:`bson_oid_t`. + +Description +----------- + +The ``bson_iter_overwrite_oid()`` function shall overwrite the contents of a BSON_TYPE_OID element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_OID. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_overwrite_timestamp.txt b/source/libbson/api/bson_iter_t/bson_iter_overwrite_timestamp.txt new file mode 100644 index 00000000..47c71677 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_overwrite_timestamp.txt @@ -0,0 +1,32 @@ +.. _bson_iter_overwrite_timestamp: + +=============================== +bson_iter_overwrite_timestamp() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_overwrite_timestamp (bson_iter_t *iter, + uint32_t timestamp, + uint32_t increment); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``timestamp``: A uint32_t. +- ``increment``: A uint32_t. + +Description +----------- + +The ``bson_iter_overwrite_timestamp()`` function shall overwrite the contents of a BSON_TYPE_TIMESTAMP element in place. + +This may only be done when the underlying bson document allows mutation. + +It is a programming error to call this function when ``iter`` is not observing an element of type BSON_TYPE_TIMESTAMP. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_recurse.txt b/source/libbson/api/bson_iter_t/bson_iter_recurse.txt new file mode 100644 index 00000000..6c9ea9e0 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_recurse.txt @@ -0,0 +1,36 @@ +.. _bson_iter_recurse: + +=================== +bson_iter_recurse() +=================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_recurse (const bson_iter_t *iter, bson_iter_t *child); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``child``: A :ref:`bson_iter_t`. + +Description +----------- + +The :ref:`bson_iter_recurse` function shall initialize ``child`` using the embedded document +or array currently observed by ``iter``. + +If there was a failure to initialize the ``iter``, false is returned and both ``iter`` and ``child`` +should be considered invalid. + +This should only be called when observing an element of type BSON_TYPE_ARRAY or BSON_TYPE_DOCUMENT. + +Returns +------- + +If ``iter`` observes an element of type BSON_TYPE_ARRAY or BSON_TYPE_DOCUMENT, then ``child`` is initialized +and the function returns ``true``. Otherwise, the function returns ``false`` and ``child`` is invalid. diff --git a/source/libbson/api/bson_iter_t/bson_iter_regex.txt b/source/libbson/api/bson_iter_t/bson_iter_regex.txt new file mode 100644 index 00000000..0dd75475 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_regex.txt @@ -0,0 +1,34 @@ +.. _bson_iter_regex: + +================= +bson_iter_regex() +================= + +Synopsis +-------- + +.. code-block:: c + + const char * + bson_iter_regex (const bson_iter_t *iter, const char **options); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``options``: A (null). + +Description +----------- + +The :ref:`bson_iter_regex` function shall retrieve the contents of a BSON_TYPE_REGEX +element currently observed by ``iter``. + +It is invalid to call this function when not observing an element of type BSON_TYPE_REGEX. + +Returns +------- + +A string containing the regex which should not be modified or freed. ``options`` is set to the +options provided for the regex. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_symbol.txt b/source/libbson/api/bson_iter_t/bson_iter_symbol.txt new file mode 100644 index 00000000..f698f28f --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_symbol.txt @@ -0,0 +1,35 @@ +.. _bson_iter_symbol: + +================== +bson_iter_symbol() +================== + +Synopsis +-------- + +.. code-block:: c + + const char * + bson_iter_symbol (const bson_iter_t *iter, uint32_t *length); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``length``: A uint32_t. + +Description +----------- + +The symbol element type is *DEPRECATED* in the bson specification at http://bsonspec.org. + +The :ref:`bson_iter_symbol` function shall return the contents of a BSON_TYPE_SYMBOL +element. + +If non-NULL, ``length`` will be set to the length of the resulting string. + +Returns +------- + +The symbol and ``length`` is set. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_time_t.txt b/source/libbson/api/bson_iter_t/bson_iter_time_t.txt new file mode 100644 index 00000000..2afba52d --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_time_t.txt @@ -0,0 +1,30 @@ +.. _bson_iter_time_t: + +================== +bson_iter_time_t() +================== + +Synopsis +-------- + +.. code-block:: c + + time_t + bson_iter_time_t (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +The :ref:`bson_iter_time_t` function shall return the number of seconds since the +UNIX epoch, as contained in the BSON_TYPE_DATE_TIME element. + +Returns +------- + +A ``time_t`` containing the number of seconds since the UNIX epoch. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_timestamp.txt b/source/libbson/api/bson_iter_t/bson_iter_timestamp.txt new file mode 100644 index 00000000..d189a22d --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_timestamp.txt @@ -0,0 +1,38 @@ +.. _bson_iter_timestamp: + +===================== +bson_iter_timestamp() +===================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_TIMESTAMP(iter) \ + (bson_iter_type ((iter)) == BSON_TYPE_TIMESTAMP) + + void + bson_iter_timestamp (const bson_iter_t *iter, + uint32_t *timestamp, + uint32_t *increment); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``timestamp``: A uint32_t. +- ``increment``: A uint32_t. + +Description +----------- + +The BSON_TYPE_TIMESTAMP type is not a date/time and is typically used for intra-server +communication. + +You probably want :ref:`bson_iter_date_time`. + +The :ref:`bson_iter_timestamp` function shall return the contents of a BSON_TYPE_TIMESTAMP +element. It is invalid to call this function while observing an element that is not of type +BSON_TYPE_TIMESTAMP. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_timeval.txt b/source/libbson/api/bson_iter_t/bson_iter_timeval.txt new file mode 100644 index 00000000..292c23e3 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_timeval.txt @@ -0,0 +1,26 @@ +.. _bson_iter_timeval: + +=================== +bson_iter_timeval() +=================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_iter_timeval (const bson_iter_t *iter, struct timeval *tv); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``tv``: A struct timeval. + +Description +----------- + +The :ref:`bson_iter_timeval` function shall return the number of seconds and microseconds +since the UNIX epoch, as contained in the BSON_TYPE_DATE_TIME element into ``tv``. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_type.txt b/source/libbson/api/bson_iter_t/bson_iter_type.txt new file mode 100644 index 00000000..29b28ef9 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_type.txt @@ -0,0 +1,54 @@ +.. _bson_iter_type: + +================ +bson_iter_type() +================ + +Synopsis +-------- + +.. code-block:: c + + typedef enum { + BSON_TYPE_EOD = 0x00, + BSON_TYPE_DOUBLE = 0x01, + BSON_TYPE_UTF8 = 0x02, + BSON_TYPE_DOCUMENT = 0x03, + BSON_TYPE_ARRAY = 0x04, + BSON_TYPE_BINARY = 0x05, + BSON_TYPE_UNDEFINED = 0x06, + BSON_TYPE_OID = 0x07, + BSON_TYPE_BOOL = 0x08, + BSON_TYPE_DATE_TIME = 0x09, + BSON_TYPE_NULL = 0x0A, + BSON_TYPE_REGEX = 0x0B, + BSON_TYPE_DBPOINTER = 0x0C, + BSON_TYPE_CODE = 0x0D, + BSON_TYPE_SYMBOL = 0x0E, + BSON_TYPE_CODEWSCOPE = 0x0F, + BSON_TYPE_INT32 = 0x10, + BSON_TYPE_TIMESTAMP = 0x11, + BSON_TYPE_INT64 = 0x12, + BSON_TYPE_MAXKEY = 0x7F, + BSON_TYPE_MINKEY = 0xFF, + } bson_type_t; + + bson_type_t + bson_iter_type (const bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +The ``bson_iter_type()`` function shall return the type of the observed element in a BSON +document. + +Returns +------- + +A :ref:`bson_type_t`. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_utf8.txt b/source/libbson/api/bson_iter_t/bson_iter_utf8.txt new file mode 100644 index 00000000..7c9e84fe --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_utf8.txt @@ -0,0 +1,43 @@ +.. _bson_iter_utf8: + +================ +bson_iter_utf8() +================ + +Synopsis +-------- + +.. code-block:: c + + #define BSON_ITER_HOLDS_UTF8(iter) (bson_iter_type ((iter)) == BSON_TYPE_UTF8) + + const char * + bson_iter_utf8 (const bson_iter_t *iter, uint32_t *length); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``length``: An optional location for the length of the resulting UTF-8 encoded string. + +Description +----------- + +The :ref:`bson_iter_utf8` function shall retrieve the contents of a BSON_TYPE_UTF8 element +currently observed by ``iter``. + +It is invalid to call this function while observing an element other than BSON_TYPE_UTF8. + +Returns +------- + +A UTF-8 encoded string that has not been modified or freed. + +It is suggested that the caller validate the content is valid UTF-8 before using this in other +places. That can be done by calling :ref:`bson_utf8_validate` or validating the underlying +:ref:`bson_t` before iterating it. + +Note that not all drivers use multi-byte representation for ``\0`` in UTF-8 encodings (commonly +referred to as modified-UTF8). You probably want to take a look at the length field when marshaling +to other runtimes. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_value.txt b/source/libbson/api/bson_iter_t/bson_iter_value.txt new file mode 100644 index 00000000..eb7ec49a --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_value.txt @@ -0,0 +1,32 @@ +.. _bson_iter_value: + +================= +bson_iter_value() +================= + +Synopsis +-------- + +.. code-block:: c + + const bson_value_t * + bson_iter_value (bson_iter_t *iter); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. + +Description +----------- + +Fetches the value for the currently observed type as a boxed type. This allows passing around +the value without knowing the type at runtime. + +If the :ref:`bson_iter_t` is further modified, the :ref:`bson_value_t` is invalidated. + +Returns +------- + +A :ref:`bson_value_t` that should not be modified or freed. + diff --git a/source/libbson/api/bson_iter_t/bson_iter_visit_all.txt b/source/libbson/api/bson_iter_t/bson_iter_visit_all.txt new file mode 100644 index 00000000..921dc2e1 --- /dev/null +++ b/source/libbson/api/bson_iter_t/bson_iter_visit_all.txt @@ -0,0 +1,37 @@ +.. _bson_iter_visit_all: + +bson_iter_visit_all() +===================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_iter_visit_all (bson_iter_t *iter, + const bson_visitor_t *visitor, + void *data); + +Parameters +---------- + +- ``iter``: A :ref:`bson_iter_t`. +- ``visitor``: A :ref:`bson_visitor_t`. +- ``data``: Optional data for ``visitor``. + +Description +----------- + +A convenience function to iterate all remaining fields of ``iter`` using the callback +vtable provided by ``visitor``. + +Returns +------- + +Returns true if visitation was prematurely stopped by a callback function. Returns false either +because all elements were visited *or* due to corrupt BSON. + +See :ref:`bson_visitor_t` for examples of how to set your own callbacks to provide information +about the location of corrupt or unsupported BSON document entries. + diff --git a/source/libbson/api/bson_json_reader_t.txt b/source/libbson/api/bson_json_reader_t.txt new file mode 100644 index 00000000..7fd388e6 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t.txt @@ -0,0 +1,153 @@ +.. _bson_json_reader_t: + +================== +bson_json_reader_t +================== + +Bulk JSON to BSON conversion + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct _bson_json_reader_t bson_json_reader_t; + + typedef enum { + BSON_JSON_ERROR_READ_CORRUPT_JS = 1, + BSON_JSON_ERROR_READ_INVALID_PARAM, + BSON_JSON_ERROR_READ_CB_FAILURE, + } bson_json_error_code_t; + +Description +----------- + +The :ref:`bson_json_reader_t` structure is used for reading a sequence of JSON documents and +transforming them to :ref:`bson_t` documents. + +This can often be useful if you want to perform bulk operations that are defined in a file +containing JSON documents. + +.. tip:: + + :ref:`bson_json_reader_t` works upon JSON documents formatted in `MongoDB extended JSON + `_ format. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_json_reader_t/bson_json_data_reader_ingest + /libbson/api/bson_json_reader_t/bson_json_data_reader_new + /libbson/api/bson_json_reader_t/bson_json_reader_destroy + /libbson/api/bson_json_reader_t/bson_json_reader_new + /libbson/api/bson_json_reader_t/bson_json_reader_new_from_fd + /libbson/api/bson_json_reader_t/bson_json_reader_new_from_file + /libbson/api/bson_json_reader_t/bson_json_reader_read + +- :ref:`bson_json_data_reader_ingest` +- :ref:`bson_json_data_reader_new` +- :ref:`bson_json_reader_destroy` +- :ref:`bson_json_reader_new` +- :ref:`bson_json_reader_new_from_fd` +- :ref:`bson_json_reader_new_from_file` +- :ref:`bson_json_reader_read` + +Example +------- + +.. code-block:: c + + /* + * 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. + */ + + + /* + * This program will print each JSON document contained in the provided files + * as a BSON string to STDOUT. + */ + + + #include + #include + #include + + + int + main (int argc, char *argv[]) + { + bson_json_reader_t *reader; + bson_error_t error; + const char *filename; + bson_t doc = BSON_INITIALIZER; + int i; + int b; + + /* + * Print program usage if no arguments are provided. + */ + if (argc == 1) { + fprintf (stderr, "usage: %s FILE...\n", argv[0]); + return 1; + } + + /* + * Process command line arguments expecting each to be a filename. + */ + for (i = 1; i < argc; i++) { + filename = argv[i]; + + /* + * Open the filename provided in command line arguments. + */ + if (0 == strcmp (filename, "-")) { + reader = bson_json_reader_new_from_fd (STDIN_FILENO, false); + } else { + if (!(reader = bson_json_reader_new_from_file (filename, &error))) { + fprintf ( + stderr, "Failed to open \"%s\": %s\n", filename, error.message); + continue; + } + } + + /* + * Convert each incoming document to BSON and print to stdout. + */ + while ((b = bson_json_reader_read (reader, &doc, &error))) { + if (b < 0) { + fprintf (stderr, "Error in json parsing:\n%s\n", error.message); + abort (); + } + + if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) { + fprintf (stderr, "Failed to write to stdout, exiting.\n"); + exit (1); + } + bson_reinit (&doc); + } + + bson_json_reader_destroy (reader); + bson_destroy (&doc); + } + + return 0; + } + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_data_reader_ingest.txt b/source/libbson/api/bson_json_reader_t/bson_json_data_reader_ingest.txt new file mode 100644 index 00000000..65488ae6 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_data_reader_ingest.txt @@ -0,0 +1,28 @@ +.. _bson_json_data_reader_ingest: + +============================== +bson_json_data_reader_ingest() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_json_data_reader_ingest (bson_json_reader_t *reader, + const uint8_t *data, + size_t len); + +Parameters +---------- + +- ``reader``: A :ref:`bson_json_reader_t` +- ``data``: A uint8_t containing data to feed. +- ``len``: A size_t containing the length of ``data``. + +Description +----------- + +Feed data to a memory based json reader. + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_data_reader_new.txt b/source/libbson/api/bson_json_reader_t/bson_json_data_reader_new.txt new file mode 100644 index 00000000..f5293636 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_data_reader_new.txt @@ -0,0 +1,32 @@ +.. _bson_json_data_reader_new: + +=========================== +bson_json_data_reader_new() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bson_json_reader_t * + bson_json_data_reader_new (bool allow_multiple, size_t size); + +Parameters +---------- + +- ``allow_multiple``: Unused. +- ``size``: A requested buffer size. + +Description +----------- + +Creates a new streaming JSON reader that will convert JSON documents to BSON. + +The ``allow_multiple`` parameter is unused. + +Returns +------- + +A newly allocated bson_json_reader_t that should be freed with bson_json_reader_destroy(). + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_reader_destroy.txt b/source/libbson/api/bson_json_reader_t/bson_json_reader_destroy.txt new file mode 100644 index 00000000..8a85bcdc --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_reader_destroy.txt @@ -0,0 +1,23 @@ +.. _bson_json_reader_destroy: + +========================== +bson_json_reader_destroy() +========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_json_reader_destroy (bson_json_reader_t *reader); + +Parameters +---------- + +- ``reader``: A :ref:`bson_json_reader_t`. + +Description +----------- + +Frees a bson_json_reader_t. Does nothing if ``reader`` is NULL. diff --git a/source/libbson/api/bson_json_reader_t/bson_json_reader_new.txt b/source/libbson/api/bson_json_reader_t/bson_json_reader_new.txt new file mode 100644 index 00000000..5b4c70aa --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_reader_new.txt @@ -0,0 +1,39 @@ +.. _bson_json_reader_new: + +====================== +bson_json_reader_new() +====================== + +Synopsis +-------- + +.. code-block:: c + + bson_json_reader_t * + bson_json_reader_new (void *data, + bson_json_reader_cb cb, + bson_json_destroy_cb dcb, + bool allow_multiple, + size_t buf_size); + +Parameters +---------- + +- ``data``: A user-defined pointer. +- ``cb``: A bson_json_reader_cb. +- ``dcb``: A bson_json_destroy_cb. +- ``allow_multiple``: Unused. +- ``buf_size``: A size_t containing the requested internal buffer size. + +Description +----------- + +Creates a new bson_json_reader_t that can read from an arbitrary data source in a streaming fashion. + +The ``allow_multiple`` parameter is unused. + +Returns +------- + +A newly allocated bson_json_reader_t that should be freed with bson_json_reader_destroy(). + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_fd.txt b/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_fd.txt new file mode 100644 index 00000000..6043e5a1 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_fd.txt @@ -0,0 +1,30 @@ +.. _bson_json_reader_new_from_fd: + +============================== +bson_json_reader_new_from_fd() +============================== + +Synopsis +-------- + +.. code-block:: c + + bson_json_reader_t * + bson_json_reader_new_from_fd (int fd, bool close_on_destroy); + +Parameters +---------- + +- ``fd``: An open file-descriptor. +- ``close_on_destroy``: Whether ``close()`` should be called on ``fd`` when the reader is destroyed. + +Description +----------- + +Creates a new JSON to BSON converter that will be reading from the file-descriptor ``fd``. + +Returns +------- + +A newly allocated bson_json_reader_t that should be freed with bson_json_reader_destroy(). + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_file.txt b/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_file.txt new file mode 100644 index 00000000..c6b0cd19 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_file.txt @@ -0,0 +1,35 @@ +.. _bson_json_reader_new_from_file: + +================================ +bson_json_reader_new_from_file() +================================ + +Synopsis +-------- + +.. code-block:: c + + bson_json_reader_t * + bson_json_reader_new_from_file (const char *filename, bson_error_t *error); + +Parameters +---------- + +- ``filename``: A file-name in the system file-name encoding. +- ``error``: A :ref:`bson_error_t`. + +Description +----------- + +Creates a new bson_json_reader_t using the underlying file found at ``filename``. + +Errors +------ + +Errors are propagated via ``error``. + +Returns +------- + +A newly allocated bson_json_reader_t if successful, otherwise NULL and error is set. + diff --git a/source/libbson/api/bson_json_reader_t/bson_json_reader_read.txt b/source/libbson/api/bson_json_reader_t/bson_json_reader_read.txt new file mode 100644 index 00000000..eefb6568 --- /dev/null +++ b/source/libbson/api/bson_json_reader_t/bson_json_reader_read.txt @@ -0,0 +1,39 @@ +.. _bson_json_reader_read: + +======================= +bson_json_reader_read() +======================= + +Synopsis +-------- + +.. code-block:: c + + int + bson_json_reader_read (bson_json_reader_t *reader, + bson_t *bson, + bson_error_t *error); + +Parameters +---------- + +- ``reader``: A :ref:`bson_json_reader_t` +- ``bson``: A :ref:`bson_t` +- ``error``: A :ref:`bson_error_t` + +Description +----------- + +Reads the next BSON document from the underlying JSON source. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +1 if successful and data was read. 0 if successful and no data was read. -1 if there was an error. + +.. include:: /libbson/includes/seealso/json.rst diff --git a/source/libbson/api/bson_memory.txt b/source/libbson/api/bson_memory.txt new file mode 100644 index 00000000..098a242b --- /dev/null +++ b/source/libbson/api/bson_memory.txt @@ -0,0 +1,50 @@ +.. _bson_memory: + +================= +Memory Management +================= + +BSON Memory Abstraction. + +Description +----------- + +Libbson contains a lightweight memory abstraction to make portability to new platforms easier. +Additionally, it helps us integrate with interesting higher-level languages. One caveat, however, +is that Libbson is not designed to deal with Out of Memory (OOM) situations. Doing so requires +extreme diligence throughout the application stack that has rarely been implemented correctly. +This may change in the future. As it stands now, Libbson will ``abort()`` under OOM situations. + +To aid in language binding integration, Libbson allows for setting a custom memory allocator via +:ref:`bson_mem_set_vtable`. This allocation may be reversed via ::ref:`bson_mem_restore_vtable`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_memory/bson_free + /libbson/api/bson_memory/bson_malloc + /libbson/api/bson_memory/bson_malloc0 + /libbson/api/bson_memory/bson_aligned_alloc + /libbson/api/bson_memory/bson_aligned_alloc0 + /libbson/api/bson_memory/bson_mem_restore_vtable + /libbson/api/bson_memory/bson_mem_set_vtable + /libbson/api/bson_memory/bson_realloc + /libbson/api/bson_memory/bson_realloc_ctx + /libbson/api/bson_memory/bson_realloc_func + /libbson/api/bson_memory/bson_zero_free + +- :ref:`bson_free` +- :ref:`bson_malloc` +- :ref:`bson_malloc0` +- :ref:`bson_aligned_alloc` +- :ref:`bson_aligned_alloc0` +- :ref:`bson_mem_restore_vtable` +- :ref:`bson_mem_set_vtable` +- :ref:`bson_realloc` +- :ref:`bson_realloc_ctx` +- :ref:`bson_realloc_func` +- :ref:`bson_zero_free` \ No newline at end of file diff --git a/source/libbson/api/bson_memory/bson_aligned_alloc.txt b/source/libbson/api/bson_memory/bson_aligned_alloc.txt new file mode 100644 index 00000000..4e5a9def --- /dev/null +++ b/source/libbson/api/bson_memory/bson_aligned_alloc.txt @@ -0,0 +1,39 @@ +.. _bson_aligned_alloc: + +==================== +bson_aligned_alloc() +==================== + +Synopsis +-------- + +.. code-block:: c + + void * + bson_aligned_alloc (size_t alignment, size_t num_bytes); + +Parameters +---------- + +- ``alignment``: The alignment of the allocated bytes of memory. Must be a power of 2 and a multiple + of ``sizeof (void *)``. +- ``num_bytes``: The number of bytes to allocate. Must be a multiple of ``alignment``. + +Description +----------- + +This is a portable ``aligned_alloc()`` wrapper. + +In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger with an +alignment of at least ``alignment``. + +If there was a failure to allocate ``num_bytes`` bytes aligned to ``alignment``, the process will be aborted. + +.. warning:: + + This function will abort on failure to allocate memory. + +Returns +------- + +A pointer to a memory region which *HAS NOT* been zeroed. diff --git a/source/libbson/api/bson_memory/bson_aligned_alloc0.txt b/source/libbson/api/bson_memory/bson_aligned_alloc0.txt new file mode 100644 index 00000000..d6d2d150 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_aligned_alloc0.txt @@ -0,0 +1,40 @@ +.. _bson_aligned_alloc0: + +===================== +bson_aligned_alloc0() +===================== + +Synopsis +-------- + +.. code-block:: c + + void * + bson_aligned_alloc0 (size_t alignment, size_t num_bytes); + +Parameters +---------- + +- ``alignment``: The alignment of the allocated bytes of memory. Must be a power of 2 and + a multiple of ``sizeof (void *)``. +- ``num_bytes``: The number of bytes to allocate. Must be a multiple of ``alignment``. + +Description +----------- + +This is a portable ``aligned_alloc()`` wrapper that also sets the memory to zero. + +In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger with +an alignment of at least ``alignment``. + +If there was a failure to allocate ``num_bytes`` bytes aligned to ``alignment``, the process will +be aborted. + +.. warning:: + + This function will abort on failure to allocate memory. + +Returns +------- + +A pointer to a memory region which *HAS* been zeroed. diff --git a/source/libbson/api/bson_memory/bson_free.txt b/source/libbson/api/bson_memory/bson_free.txt new file mode 100644 index 00000000..dba018ed --- /dev/null +++ b/source/libbson/api/bson_memory/bson_free.txt @@ -0,0 +1,24 @@ +.. _bson_free: + +=========== +bson_free() +=========== + +Synopsis +-------- + +.. code-block:: c + + void + bson_free (void *mem); + +Parameters +---------- + +- ``mem``: A memory region. + +Description +----------- + +This function shall free the memory supplied by ``mem``. This should be used by functions that require you free the result with ``bson_free()``. + diff --git a/source/libbson/api/bson_memory/bson_malloc.txt b/source/libbson/api/bson_memory/bson_malloc.txt new file mode 100644 index 00000000..47a97211 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_malloc.txt @@ -0,0 +1,37 @@ +.. _bson_malloc: + +============= +bson_malloc() +============= + +Synopsis +-------- + +.. code-block:: c + + void * + bson_malloc (size_t num_bytes); + +Parameters +---------- + +- ``num_bytes``: A size_t containing the number of bytes to allocate. + +Description +----------- + +This is a portable ``malloc()`` wrapper. + +In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger. + +If there was a failure to allocate ``num_bytes`` bytes, the process will be aborted. + +.. warning:: + + This function will abort on failure to allocate memory. + +Returns +------- + +A pointer to a memory region which *HAS NOT* been zeroed. + diff --git a/source/libbson/api/bson_memory/bson_malloc0.txt b/source/libbson/api/bson_memory/bson_malloc0.txt new file mode 100644 index 00000000..cf00c8d0 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_malloc0.txt @@ -0,0 +1,37 @@ +.. _bson_malloc0: + +============== +bson_malloc0() +============== + +Synopsis +-------- + +.. code-block:: c + + void * + bson_malloc0 (size_t num_bytes); + +Parameters +---------- + +- ``num_bytes``: A size_t. + +Description +----------- + +This is a portable ``malloc()`` wrapper that also sets the memory to zero. Similar to ``calloc()``. + +In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger. + +If there was a failure to allocate ``num_bytes`` bytes, the process will be aborted. + +.. warning:: + + This function will abort on failure to allocate memory. + +Returns +------- + +A pointer to a memory region which *HAS* been zeroed. + diff --git a/source/libbson/api/bson_memory/bson_mem_restore_vtable.txt b/source/libbson/api/bson_memory/bson_mem_restore_vtable.txt new file mode 100644 index 00000000..b1ea5876 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_mem_restore_vtable.txt @@ -0,0 +1,24 @@ +.. _bson_mem_restore_vtable: + +========================= +bson_mem_restore_vtable() +========================= + +Synopsis +-------- + +.. code-block:: c + + void + bson_mem_restore_vtable (void); + +Description +----------- + +This function shall restore the default memory allocator to be used by Libbson. + +.. warning:: + + This function *MUST* be called at the end of the process. Failure to do so will result in + memory being freed by the wrong allocator. + diff --git a/source/libbson/api/bson_memory/bson_mem_set_vtable.txt b/source/libbson/api/bson_memory/bson_mem_set_vtable.txt new file mode 100644 index 00000000..04fdd385 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_mem_set_vtable.txt @@ -0,0 +1,40 @@ +.. _bson_mem_set_vtable: + +===================== +bson_mem_set_vtable() +===================== + +Synopsis +-------- + +.. code-block:: c + + typedef struct _bson_mem_vtable_t { + void *(*malloc) (size_t num_bytes); + void *(*calloc) (size_t n_members, size_t num_bytes); + void *(*realloc) (void *mem, size_t num_bytes); + void (*free) (void *mem); + void *(*aligned_alloc) (size_t alignment, size_t num_bytes); + void *padding[3]; + } bson_mem_vtable_t; + + void + bson_mem_set_vtable (const bson_mem_vtable_t *vtable); + +Parameters +---------- + +- ``vtable``: A bson_mem_vtable_t with every non-padding field set. + +Description +----------- + +This function shall install a new memory allocator to be used by Libbson. + +For backwards compatibility, if ``vtable->aligned_alloc`` is not set, calls to +``vtable->aligned_alloc`` will use ``vtable->malloc`` instead. + +.. warning:: + + This function *MUST* be called at the beginning of the process. Failure to do so will + result in memory being freed by the wrong allocator. diff --git a/source/libbson/api/bson_memory/bson_realloc.txt b/source/libbson/api/bson_memory/bson_realloc.txt new file mode 100644 index 00000000..e357a56e --- /dev/null +++ b/source/libbson/api/bson_memory/bson_realloc.txt @@ -0,0 +1,39 @@ +.. _bson_realloc: + +============== +bson_realloc() +============== + +Synopsis +-------- + +.. code-block:: c + + void * + bson_realloc (void *mem, size_t num_bytes); + +Parameters +---------- + +- ``mem``: A memory region. +- ``num_bytes``: A size_t containing the new requested size. + +Description +----------- + +This is a portable ``realloc()`` wrapper. + +In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger. +If ``num_bytes`` is 0, then the allocation will be freed. + +If there was a failure to allocate ``num_bytes`` bytes, the process will be aborted. + +.. warning:: + + This function will abort on failure to allocate memory. + +Returns +------- + +A pointer to a memory region which *HAS NOT* been zeroed. + diff --git a/source/libbson/api/bson_memory/bson_realloc_ctx.txt b/source/libbson/api/bson_memory/bson_realloc_ctx.txt new file mode 100644 index 00000000..a37c5e9b --- /dev/null +++ b/source/libbson/api/bson_memory/bson_realloc_ctx.txt @@ -0,0 +1,27 @@ +.. _bson_realloc_ctx: + +================== +bson_realloc_ctx() +================== + +Synopsis +-------- + +.. code-block:: c + + void * + bson_realloc_ctx (void *mem, size_t num_bytes, void *ctx); + +Parameters +---------- + +- ``mem``: A memory region. +- ``num_bytes``: A size_t containing the requested size. +- ``ctx``: A consumer-specific pointer or ``NULL``. + +Description +----------- + +This function is identical to :ref:`bson_realloc` except it takes a context parameter. +This is useful when working with pooled or specific memory allocators. + diff --git a/source/libbson/api/bson_memory/bson_realloc_func.txt b/source/libbson/api/bson_memory/bson_realloc_func.txt new file mode 100644 index 00000000..1c567e92 --- /dev/null +++ b/source/libbson/api/bson_memory/bson_realloc_func.txt @@ -0,0 +1,27 @@ +.. _bson_realloc_func: + +================= +bson_realloc_func +================= + +Synopsis +-------- + +.. code-block:: c + + typedef void *(*bson_realloc_func) (void *mem, size_t num_bytes, void *ctx); + +Parameters +---------- + +- ``mem``: A memory region. +- ``num_bytes``: A size_t containing the requested size. +- ``ctx``: A consumer-specific pointer or ``NULL``. + +Description +----------- + +This is a prototype for pluggable realloc functions used through the Libbson library. +If you wish to use a custom allocator this is one way to do it. Additionally, +:ref:`bson_realloc_ctx` is a default implementation of this prototype. + diff --git a/source/libbson/api/bson_memory/bson_zero_free.txt b/source/libbson/api/bson_memory/bson_zero_free.txt new file mode 100644 index 00000000..5029b87d --- /dev/null +++ b/source/libbson/api/bson_memory/bson_zero_free.txt @@ -0,0 +1,28 @@ +.. _bson_zero_free: + +================ +bson_zero_free() +================ + +Synopsis +-------- + +.. code-block:: c + + void + bson_zero_free (void *mem, size_t size); + +Parameters +---------- + +- ``mem``: A memory region. +- ``size``: The size of ``mem``. + +Description +----------- + +This function behaves like :ref:`bson_free` except that it zeroes the memory first. +This can be useful if you are storing passwords or other similarly important data. Note +that if it truly is important, you probably want a page protected with ``mlock()`` as well +to prevent it swapping to disk. + diff --git a/source/libbson/api/bson_oid_t.txt b/source/libbson/api/bson_oid_t.txt new file mode 100644 index 00000000..fb4deb3c --- /dev/null +++ b/source/libbson/api/bson_oid_t.txt @@ -0,0 +1,125 @@ +.. _bson_oid_t: + +========== +bson_oid_t +========== + +BSON ObjectID Abstraction + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct { + uint8_t bytes[12]; + } bson_oid_t; + +Description +----------- + +The :ref:`bson_oid_t` structure contains the 12-byte ObjectId notation defined by the +`BSON ObjectID specification `_. + +ObjectId is a 12-byte BSON type, constructed using: + +- a 4-byte value representing the seconds since the Unix epoch (in Big Endian). +- a 5-byte random value. +- a 3-byte counter (Big Endian), starting with a random value. + +String Conversion +----------------- + +You can convert an Object ID to a string using :ref:`bson_oid_to_string` and back with +:ref:`bson_oid_init_from_string`. + +Hashing +------- + +A :ref:`bson_oid_t` can be used in hashtables using the function :ref:`bson_oid_hash` +and :ref:`bson_oid_equal`. + +Comparing +--------- + +A :ref:`bson_oid_t` can be compared to another using :ref:`bson_oid_compare` for +``qsort()`` style comparing and :ref:`bson_oid_equal` for direct equality. + +Validating +---------- + +You can validate that a string containing a hex-encoded ObjectID is valid using the function +:ref:`bson_oid_is_valid`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_oid_t/bson_oid_compare + /libbson/api/bson_oid_t/bson_oid_compare_unsafe + /libbson/api/bson_oid_t/bson_oid_copy + /libbson/api/bson_oid_t/bson_oid_copy_unsafe + /libbson/api/bson_oid_t/bson_oid_equal + /libbson/api/bson_oid_t/bson_oid_equal_unsafe + /libbson/api/bson_oid_t/bson_oid_get_time_t + /libbson/api/bson_oid_t/bson_oid_get_time_t_unsafe + /libbson/api/bson_oid_t/bson_oid_hash + /libbson/api/bson_oid_t/bson_oid_hash_unsafe + /libbson/api/bson_oid_t/bson_oid_init + /libbson/api/bson_oid_t/bson_oid_init_from_data + /libbson/api/bson_oid_t/bson_oid_init_from_string + /libbson/api/bson_oid_t/bson_oid_init_from_string_unsafe + /libbson/api/bson_oid_t/bson_oid_init_sequence + /libbson/api/bson_oid_t/bson_oid_is_valid + /libbson/api/bson_oid_t/bson_oid_to_string + +- :ref:`bson_oid_compare` +- :ref:`bson_oid_compare_unsafe` +- :ref:`bson_oid_copy` +- :ref:`bson_oid_copy_unsafe` +- :ref:`bson_oid_equal` +- :ref:`bson_oid_equal_unsafe` +- :ref:`bson_oid_get_time_t` +- :ref:`bson_oid_get_time_t_unsafe` +- :ref:`bson_oid_hash` +- :ref:`bson_oid_hash_unsafe` +- :ref:`bson_oid_init` +- :ref:`bson_oid_init_from_data` +- :ref:`bson_oid_init_from_string` +- :ref:`bson_oid_init_from_string_unsafe` +- :ref:`bson_oid_init_sequence` +- :ref:`bson_oid_is_valid` +- :ref:`bson_oid_to_string` + +Example +------- + +.. code-block:: c + + #include + #include + + int + main (int argc, char *argv[]) + { + bson_oid_t oid; + char str[25]; + + bson_oid_init (&oid, NULL); + bson_oid_to_string (&oid, str); + printf ("%s\n", str); + + if (bson_oid_is_valid (str, sizeof str)) { + bson_oid_init_from_string (&oid, str); + } + + printf ("The UNIX time was: %u\n", (unsigned) bson_oid_get_time_t (&oid)); + + return 0; + } + diff --git a/source/libbson/api/bson_oid_t/bson_oid_compare.txt b/source/libbson/api/bson_oid_t/bson_oid_compare.txt new file mode 100644 index 00000000..b412b175 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_compare.txt @@ -0,0 +1,31 @@ +.. _bson_oid_compare: + +================== +bson_oid_compare() +================== + +Synopsis +-------- + +.. code-block:: c + + int + bson_oid_compare (const bson_oid_t *oid1, const bson_oid_t *oid2); + +Parameters +---------- + +- ``oid1``: A :ref:`bson_oid_t` +- ``oid2``: A :ref:`bson_oid_t` + +Description +----------- + +The :ref:`bson_oid_compare` function shall return a qsort() style value of a lexicographical +sort of ``oid1`` and ``oid2``. + +Returns +------- + +less than 0, 0, or greater than 0 based on the comparison. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_compare_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_compare_unsafe.txt new file mode 100644 index 00000000..995279b1 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_compare_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_compare_unsafe: + +========================= +bson_oid_compare_unsafe() +========================= + +Synopsis +-------- + +.. code-block:: c + + static inline int + bson_oid_compare_unsafe (const bson_oid_t *oid1, const bson_oid_t *oid2); + +Description +----------- + +Identical to :ref:`bson_oid_compare`, but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_copy.txt b/source/libbson/api/bson_oid_t/bson_oid_copy.txt new file mode 100644 index 00000000..6305141e --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_copy.txt @@ -0,0 +1,25 @@ +.. _bson_oid_copy: + +=============== +bson_oid_copy() +=============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_copy (const bson_oid_t *src, bson_oid_t *dst); + +Parameters +---------- + +- ``src``: A :ref:`bson_oid_t`. +- ``dst``: A :ref:`bson_oid_t`. + +Description +----------- + +Copies the contents of src into dst. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_copy_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_copy_unsafe.txt new file mode 100644 index 00000000..2f67319b --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_copy_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_copy_unsafe: + +====================== +bson_oid_copy_unsafe() +====================== + +Synopsis +-------- + +.. code-block:: c + + static inline void + bson_oid_copy_unsafe (const bson_oid_t *src, bson_oid_t *dst); + +Description +----------- + +Identical to :ref:`bson_oid_copy`, but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_equal.txt b/source/libbson/api/bson_oid_t/bson_oid_equal.txt new file mode 100644 index 00000000..edb29504 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_equal.txt @@ -0,0 +1,30 @@ +.. _bson_oid_equal: + +================ +bson_oid_equal() +================ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_oid_equal (const bson_oid_t *oid1, const bson_oid_t *oid2); + +Parameters +---------- + +- ``oid1``: A :ref:`bson_oid_t`. +- ``oid2``: A :ref:`bson_oid_t`. + +Description +----------- + +Checks if two bson_oid_t contain the same bytes. + +Returns +------- + +true if they are equal, otherwise false. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_equal_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_equal_unsafe.txt new file mode 100644 index 00000000..95fb1a5c --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_equal_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_equal_unsafe: + +======================= +bson_oid_equal_unsafe() +======================= + +Synopsis +-------- + +.. code-block:: c + + static inline bool + bson_oid_equal_unsafe (const bson_oid_t *oid1, const bson_oid_t *oid2); + +Description +----------- + +Identical to :ref:`bson_oid_equal` but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_get_time_t.txt b/source/libbson/api/bson_oid_t/bson_oid_get_time_t.txt new file mode 100644 index 00000000..56dcaad3 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_get_time_t.txt @@ -0,0 +1,29 @@ +.. _bson_oid_get_time_t: + +===================== +bson_oid_get_time_t() +===================== + +Synopsis +-------- + +.. code-block:: c + + time_t + bson_oid_get_time_t (const bson_oid_t *oid); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t`. + +Description +----------- + +Fetches the generation time in seconds since the UNIX Epoch of ``oid``. + +Returns +------- + +A time_t containing the seconds since the UNIX epoch of ``oid``. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_get_time_t_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_get_time_t_unsafe.txt new file mode 100644 index 00000000..6e60e5b5 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_get_time_t_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_get_time_t_unsafe: + +============================ +bson_oid_get_time_t_unsafe() +============================ + +Synopsis +-------- + +.. code-block:: c + + static inline time_t + bson_oid_get_time_t_unsafe (const bson_oid_t *oid); + +Description +----------- + +Identical to :ref:`bson_oid_get_time_t`, but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_hash.txt b/source/libbson/api/bson_oid_t/bson_oid_hash.txt new file mode 100644 index 00000000..6997fa5f --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_hash.txt @@ -0,0 +1,29 @@ +.. _bson_oid_hash: + +=============== +bson_oid_hash() +=============== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + bson_oid_hash (const bson_oid_t *oid); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t`. + +Description +----------- + +Generates a hash code for ``oid`` suitable for a hashtable. + +Returns +------- + +A 32-bit hash code. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_hash_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_hash_unsafe.txt new file mode 100644 index 00000000..9a041d46 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_hash_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_hash_unsafe: + +====================== +bson_oid_hash_unsafe() +====================== + +Synopsis +-------- + +.. code-block:: c + + static inline uint32_t + bson_oid_hash_unsafe (const bson_oid_t *oid); + +Description +----------- + +Identical to :ref:`bson_oid_hash`, but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_init.txt b/source/libbson/api/bson_oid_t/bson_oid_init.txt new file mode 100644 index 00000000..4ffe54c3 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_init.txt @@ -0,0 +1,25 @@ +.. _bson_oid_init: + +=============== +bson_oid_init() +=============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_init (bson_oid_t *oid, bson_context_t *context); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t` +- ``context``: An *optional* :ref:`bson_context_t` or NULL. + +Description +----------- + +Generates a new :ref:`bson_oid_t` using either ``context`` or the default :ref:`bson_context_t`. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_init_from_data.txt b/source/libbson/api/bson_oid_t/bson_oid_init_from_data.txt new file mode 100644 index 00000000..f850efbe --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_init_from_data.txt @@ -0,0 +1,25 @@ +.. _bson_oid_init_from_data: + +========================= +bson_oid_init_from_data() +========================= + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_init_from_data (bson_oid_t *oid, const uint8_t *data); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t`. +- ``data``: A buffer containing 12 bytes for the oid. + +Description +----------- + +Initializes a :ref:`bson_oid_t` using the raw buffer provided. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_init_from_string.txt b/source/libbson/api/bson_oid_t/bson_oid_init_from_string.txt new file mode 100644 index 00000000..1e0705df --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_init_from_string.txt @@ -0,0 +1,32 @@ +.. _bson_oid_init_from_string: + +=========================== +bson_oid_init_from_string() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_init_from_string (bson_oid_t *oid, const char *str); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t`. +- ``str``: A string containing a hex encoded version of the oid. + +Description +----------- + +Parses the string containing hex encoded oid and initialize the bytes in ``oid``. + +Example +------- + +.. code-block:: c + + bson_oid_init_from_string (&oid, "012345678901234567890123"); + diff --git a/source/libbson/api/bson_oid_t/bson_oid_init_from_string_unsafe.txt b/source/libbson/api/bson_oid_t/bson_oid_init_from_string_unsafe.txt new file mode 100644 index 00000000..db337785 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_init_from_string_unsafe.txt @@ -0,0 +1,18 @@ +.. _bson_oid_init_from_string_unsafe: + +================================== +bson_oid_init_from_string_unsafe() +================================== + +Synopsis +-------- + +.. code-block:: c + + static inline void + bson_oid_init_from_string_unsafe (bson_oid_t *oid, const char *str); + +Description +----------- + +Identical to :ref:`bson_oid_init_from_string`, but performs no integrity checking. diff --git a/source/libbson/api/bson_oid_t/bson_oid_init_sequence.txt b/source/libbson/api/bson_oid_t/bson_oid_init_sequence.txt new file mode 100644 index 00000000..7d73a87c --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_init_sequence.txt @@ -0,0 +1,37 @@ +.. _bson_oid_init_sequence: + +======================== +bson_oid_init_sequence() +======================== + +.. warning:: + .. deprecated:: 1.14.0 + + This function is deprecated and should not be used in new code. + + Please use :ref:`bson_oid_init` in new code. + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_init_sequence (bson_oid_t *oid, bson_context_t *context) + BSON_GNUC_DEPRECATED_FOR (bson_oid_init); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t`. +- ``context``: An optional :ref:`bson_context_t`. + +Description +----------- + +Generates a new ObjectID with the next 64-bit sequence number in ``context``. The first 4 +bytes contain the current time and the following 8 contain the sequence number in big-endian +format. + +The :ref:`bson_oid_t` generated by this function is not guaranteed to be globally unique. +Only unique within this context. It is however, guaranteed to be sequential. diff --git a/source/libbson/api/bson_oid_t/bson_oid_is_valid.txt b/source/libbson/api/bson_oid_t/bson_oid_is_valid.txt new file mode 100644 index 00000000..5d425cd1 --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_is_valid.txt @@ -0,0 +1,30 @@ +.. _bson_oid_is_valid: + +=================== +bson_oid_is_valid() +=================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_oid_is_valid (const char *str, size_t length); + +Parameters +---------- + +- ``str``: A string. +- ``length``: The length of ``str``. + +Description +----------- + +Checks if a string containing a hex encoded string is a valid BSON ObjectID. + +Returns +------- + +true if ``str`` could be parsed. + diff --git a/source/libbson/api/bson_oid_t/bson_oid_to_string.txt b/source/libbson/api/bson_oid_t/bson_oid_to_string.txt new file mode 100644 index 00000000..38c08bcd --- /dev/null +++ b/source/libbson/api/bson_oid_t/bson_oid_to_string.txt @@ -0,0 +1,25 @@ +.. _bson_oid_to_string: + +==================== +bson_oid_to_string() +==================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_oid_to_string (const bson_oid_t *oid, char str[25]); + +Parameters +---------- + +- ``oid``: A :ref:`bson_oid_t` +- ``str``: A location for the resulting string. + +Description +----------- + +Converts ``oid`` into a hex encoded string. + diff --git a/source/libbson/api/bson_reader_t.txt b/source/libbson/api/bson_reader_t.txt new file mode 100644 index 00000000..7bd28aca --- /dev/null +++ b/source/libbson/api/bson_reader_t.txt @@ -0,0 +1,154 @@ +.. _bson_reader_t: + +============= +bson_reader_t +============= + +Streaming BSON Document Reader + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct _bson_reader_t bson_reader_t; + + bson_reader_t * + bson_reader_new_from_handle (void *handle, + bson_reader_read_func_t rf, + bson_reader_destroy_func_t df); + bson_reader_t * + bson_reader_new_from_fd (int fd, bool close_on_destroy); + bson_reader_t * + bson_reader_new_from_file (const char *path, bson_error_t *error); + bson_reader_t * + bson_reader_new_from_data (const uint8_t *data, size_t length); + + void + bson_reader_destroy (bson_reader_t *reader); + +Description +----------- + +:ref:`bson_reader_t` is a structure used for reading a sequence of BSON documents. +The sequence can come from a file-descriptor, memory region, or custom callbacks. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_reader_t/bson_reader_destroy + /libbson/api/bson_reader_t/bson_reader_destroy_func_t + /libbson/api/bson_reader_t/bson_reader_new_from_data + /libbson/api/bson_reader_t/bson_reader_new_from_fd + /libbson/api/bson_reader_t/bson_reader_new_from_file + /libbson/api/bson_reader_t/bson_reader_new_from_handle + /libbson/api/bson_reader_t/bson_reader_read + /libbson/api/bson_reader_t/bson_reader_read_func_t + /libbson/api/bson_reader_t/bson_reader_reset + /libbson/api/bson_reader_t/bson_reader_set_destroy_func + /libbson/api/bson_reader_t/bson_reader_set_read_func + /libbson/api/bson_reader_t/bson_reader_tell + +- :ref:`bson_reader_destroy` +- :ref:`bson_reader_destroy_func_t` +- :ref:`bson_reader_new_from_data` +- :ref:`bson_reader_new_from_fd` +- :ref:`bson_reader_new_from_file` +- :ref:`bson_reader_new_from_handle` +- :ref:`bson_reader_read` +- :ref:`bson_reader_read_func_t` +- :ref:`bson_reader_reset` +- :ref:`bson_reader_set_destroy_func` +- :ref:`bson_reader_set_read_func` +- :ref:`bson_reader_tell` + +Example +------- + +.. code-block:: c + + /* + * 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. + */ + + + /* + * This program will print each BSON document contained in the provided files + * as a JSON string to STDOUT. + */ + + + #include + #include + + + int + main (int argc, char *argv[]) + { + bson_reader_t *reader; + const bson_t *b; + bson_error_t error; + const char *filename; + char *str; + int i; + + /* + * Print program usage if no arguments are provided. + */ + if (argc == 1) { + fprintf (stderr, "usage: %s [FILE | -]...\nUse - for STDIN.\n", argv[0]); + return 1; + } + + /* + * Process command line arguments expecting each to be a filename. + */ + for (i = 1; i < argc; i++) { + filename = argv[i]; + + if (strcmp (filename, "-") == 0) { + reader = bson_reader_new_from_fd (STDIN_FILENO, false); + } else { + if (!(reader = bson_reader_new_from_file (filename, &error))) { + fprintf ( + stderr, "Failed to open \"%s\": %s\n", filename, error.message); + continue; + } + } + + /* + * Convert each incoming document to JSON and print to stdout. + */ + while ((b = bson_reader_read (reader, NULL))) { + str = bson_as_canonical_extended_json (b, NULL); + fprintf (stdout, "%s\n", str); + bson_free (str); + } + + /* + * Cleanup after our reader, which closes the file descriptor. + */ + bson_reader_destroy (reader); + } + + return 0; + } + diff --git a/source/libbson/api/bson_reader_t/bson_reader_destroy.txt b/source/libbson/api/bson_reader_t/bson_reader_destroy.txt new file mode 100644 index 00000000..f117b028 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_destroy.txt @@ -0,0 +1,23 @@ +.. _bson_reader_destroy: + +===================== +bson_reader_destroy() +===================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_reader_destroy (bson_reader_t *reader); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t` + +Description +----------- + +Destroys and releases all resources associated with ``reader``. Does nothing if ``reader`` is NULL. diff --git a/source/libbson/api/bson_reader_t/bson_reader_destroy_func_t.txt b/source/libbson/api/bson_reader_t/bson_reader_destroy_func_t.txt new file mode 100644 index 00000000..35f8e506 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_destroy_func_t.txt @@ -0,0 +1,26 @@ +.. _bson_reader_destroy_func_t: + +========================== +bson_reader_destroy_func_t +========================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*bson_reader_destroy_func_t) (void *handle); + +Parameters +---------- + +- ``handle``: The opaque handle provided to :ref:`bson_reader_new_from_handle`. + +Description +----------- + +An optional callback function that will be called when a :ref:`bson_reader_t` created with +:ref:`bson_reader_new_from_handle` is destroyed with :ref:`bson_reader_destroy`. + +The handle used when creating the reader is passed to this callback. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_new_from_data.txt b/source/libbson/api/bson_reader_t/bson_reader_new_from_data.txt new file mode 100644 index 00000000..e9a9e989 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_new_from_data.txt @@ -0,0 +1,32 @@ +.. _bson_reader_new_from_data: + +=========================== +bson_reader_new_from_data() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bson_reader_t * + bson_reader_new_from_data (const uint8_t *data, size_t length); + +Parameters +---------- + +- ``data``: A uint8_t. +- ``length``: A size_t. + +Description +----------- + +The :ref:`bson_reader_new_from_data` function shall create a new :ref:`bson_reader_t` +using the buffer supplied. ``data`` is not copied and *MUST* be valid for the lifetime of the +resulting :ref:`bson_reader_t`. + +Returns +------- + +A newly allocated :ref:`bson_reader_t`. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_new_from_fd.txt b/source/libbson/api/bson_reader_t/bson_reader_new_from_fd.txt new file mode 100644 index 00000000..b37c513a --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_new_from_fd.txt @@ -0,0 +1,36 @@ +.. _bson_reader_new_from_fd: + +========================= +bson_reader_new_from_fd() +========================= + +Synopsis +-------- + +.. code-block:: c + + bson_reader_t * + bson_reader_new_from_fd (int fd, bool close_on_destroy); + +Parameters +---------- + +- ``fd``: A valid file-descriptor. +- ``close_on_destroy``: Whether ``close()`` should be called on ``fd`` when the reader is destroyed. + +Description +----------- + +The :ref:`bson_reader_new_from_fd` function shall create a new :ref:`bson_reader_t` +that will read from the provided file-descriptor. + +fd *MUST* be in blocking mode. + +If ``close_fd`` is true, then ``fd`` will be closed when the :ref:`bson_reader_t` is destroyed +with :ref:`bson_reader_destroy`. + +Returns +------- + +A newly allocated :ref:`bson_reader_t` that should be freed with :ref:`bson_reader_destroy`. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_new_from_file.txt b/source/libbson/api/bson_reader_t/bson_reader_new_from_file.txt new file mode 100644 index 00000000..1d0bfdea --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_new_from_file.txt @@ -0,0 +1,35 @@ +.. _bson_reader_new_from_file: + +=========================== +bson_reader_new_from_file() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bson_reader_t * + bson_reader_new_from_file (const char *path, bson_error_t *error); + +Parameters +---------- + +- ``path``: A filename in the host filename encoding. +- ``error``: A :ref:`bson_error_t`. + +Description +----------- + +Creates a new :ref:`bson_reader_t` using the file denoted by ``filename``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +A newly allocated :ref:`bson_reader_t` on success, otherwise NULL and error is set. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_new_from_handle.txt b/source/libbson/api/bson_reader_t/bson_reader_new_from_handle.txt new file mode 100644 index 00000000..64d9013e --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_new_from_handle.txt @@ -0,0 +1,34 @@ +.. _bson_reader_new_from_handle: + +============================= +bson_reader_new_from_handle() +============================= + +Synopsis +-------- + +.. code-block:: c + + bson_reader_t * + bson_reader_new_from_handle (void *handle, + bson_reader_read_func_t rf, + bson_reader_destroy_func_t df); + +Parameters +---------- + +- ``handle``: A user-provided pointer or NULL. +- ``rf``: A :ref:`bson_reader_read_func_t`. +- ``df``: A :ref:`bson_reader_destroy_func_t`. + +Description +----------- + +This function allows for a pluggable data stream for the reader. This can be used +to read from sockets, files, memory, or other arbitrary sources. + +Returns +------- + +A newly allocated bson_reader_t if successful; otherwise NULL. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_read.txt b/source/libbson/api/bson_reader_t/bson_reader_read.txt new file mode 100644 index 00000000..ca10af36 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_read.txt @@ -0,0 +1,53 @@ +.. _bson_reader_read: + +================== +bson_reader_read() +================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + bson_reader_read (bson_reader_t *reader, bool *reached_eof); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t`. +- ``reached_eof``: A UNKNOWN. + +Description +----------- + +The :ref:`bson_reader_read` function shall read the next document from the underlying +file-descriptor or buffer. + +If there are no further documents or a failure was detected, then NULL is returned. + +If we reached the end of the sequence, ``reached_eof`` is set to true. + +To detect an error, check for NULL and ``reached_of`` is false. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +Example +------- + +.. code-block:: c + + const bson_t *doc; + bool reached_eof = false; + + while ((doc = bson_reader_read (reader, &reached_eof))) { + /* do something */ + } + + if (!reached_eof) { + fprintf (stderr, "Failed to read all documents.\n"); + } + diff --git a/source/libbson/api/bson_reader_t/bson_reader_read_func_t.txt b/source/libbson/api/bson_reader_t/bson_reader_read_func_t.txt new file mode 100644 index 00000000..d5a5ab69 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_read_func_t.txt @@ -0,0 +1,40 @@ +.. _bson_reader_read_func_t: + +======================= +bson_reader_read_func_t +======================= + +Synopsis +-------- + +.. code-block:: c + + typedef ssize_t (*bson_reader_read_func_t) (void *handle, + void *buf, + size_t count); + +Parameters +---------- + +- ``handle``: The handle to read from. +- ``buf``: The buffer to read into. +- ``count``: The number of bytes to read. + +Description +----------- + +A callback function that will be called by :ref:`bson_reader_t` to read the next +chunk of data from the underlying opaque file descriptor. + +This function is meant to operate similar to the ``read(2)`` function as part of libc +on UNIX-like systems. + +Returns +------- + +0 for end of stream. + +-1 for a failure on read. + +A value greater than zero for the number of bytes read into ``buf``. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_reset.txt b/source/libbson/api/bson_reader_t/bson_reader_reset.txt new file mode 100644 index 00000000..8114012e --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_reset.txt @@ -0,0 +1,26 @@ +.. _bson_reader_reset: + +=================== +bson_reader_reset() +=================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_reader_reset (bson_reader_t *reader); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t` + +Description +----------- + +Seeks to the beginning of the underlying buffer. Valid only for a reader created from +a buffer with :ref:`bson_reader_new_from_data`, not one created from a file, file +descriptor, or handle. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_set_destroy_func.txt b/source/libbson/api/bson_reader_t/bson_reader_set_destroy_func.txt new file mode 100644 index 00000000..f044f6fc --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_set_destroy_func.txt @@ -0,0 +1,27 @@ +.. _bson_reader_set_destroy_func: + +============================== +bson_reader_set_destroy_func() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_reader_set_destroy_func (bson_reader_t *reader, + bson_reader_destroy_func_t func); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t`. +- ``func``: A :ref:`bson_reader_destroy_func_t`. + +Description +----------- + +Allows for setting a callback to be executed when a reader is destroyed. This should only +be used by implementations implementing their own read callbacks. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_set_read_func.txt b/source/libbson/api/bson_reader_t/bson_reader_set_read_func.txt new file mode 100644 index 00000000..8f3d177d --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_set_read_func.txt @@ -0,0 +1,25 @@ +.. _bson_reader_set_read_func: + +=========================== +bson_reader_set_read_func() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_reader_set_read_func (bson_reader_t *reader, bson_reader_read_func_t func); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t`. +- ``func``: A :ref:`bson_reader_read_func_t`. + +Description +----------- + +Sets the function to read more data from the underlying stream in a custom bson_reader_t. + diff --git a/source/libbson/api/bson_reader_t/bson_reader_tell.txt b/source/libbson/api/bson_reader_t/bson_reader_tell.txt new file mode 100644 index 00000000..5e05daf5 --- /dev/null +++ b/source/libbson/api/bson_reader_t/bson_reader_tell.txt @@ -0,0 +1,29 @@ +.. _bson_reader_tell: + +================== +bson_reader_tell() +================== + +Synopsis +-------- + +.. code-block:: c + + off_t + bson_reader_tell (bson_reader_t *reader); + +Parameters +---------- + +- ``reader``: A :ref:`bson_reader_t`. + +Description +----------- + +Tells the current position within the underlying stream. + +Returns +------- + +-1 on failure, otherwise the offset within the underlying stream. + diff --git a/source/libbson/api/bson_string_t.txt b/source/libbson/api/bson_string_t.txt new file mode 100644 index 00000000..bf995ef8 --- /dev/null +++ b/source/libbson/api/bson_string_t.txt @@ -0,0 +1,69 @@ +.. _bson_string_t: + +============= +bson_string_t +============= + +String Building Abstraction + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct { + char *str; + uint32_t len; + uint32_t alloc; + } bson_string_t; + +Description +----------- + +:ref:`bson_string_t` is an abstraction for building strings. As chunks are added to +the string, allocations are performed in powers of two. + +This API is useful if you need to build UTF-8 encoded strings. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_string_t/bson_string_append + /libbson/api/bson_string_t/bson_string_append_c + /libbson/api/bson_string_t/bson_string_append_printf + /libbson/api/bson_string_t/bson_string_append_unichar + /libbson/api/bson_string_t/bson_string_free + /libbson/api/bson_string_t/bson_string_new + /libbson/api/bson_string_t/bson_string_truncate + +- :ref:`bson_string_append` +- :ref:`bson_string_append_c` +- :ref:`bson_string_append_printf` +- :ref:`bson_string_append_unichar` +- :ref:`bson_string_free` +- :ref:`bson_string_new` +- :ref:`bson_string_truncate` + +Example +------- + +.. code-block:: c + + bson_string_t *str; + + str = bson_string_new (NULL); + bson_string_append_printf (str, "%d %s %f\n", 0, "some string", 0.123); + printf ("%s\n", str->str); + + bson_string_free (str, true); + +.. tip:: + + You can call :ref:`bson_string_free` with ``false`` if you would like to take ownership of ``str->str``. Some APIs that do this might call ``return bson_string_free (str, false);`` after building the string. + diff --git a/source/libbson/api/bson_string_t/bson_string_append.txt b/source/libbson/api/bson_string_t/bson_string_append.txt new file mode 100644 index 00000000..4a48a52a --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_append.txt @@ -0,0 +1,26 @@ +.. _bson_string_append: + +==================== +bson_string_append() +==================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_string_append (bson_string_t *string, const char *str); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``str``: A string. + +Description +----------- + +Appends the ASCII or UTF-8 encoded string ``str`` to ``string``. This is not suitable for +embedding NULLs in strings. + diff --git a/source/libbson/api/bson_string_t/bson_string_append_c.txt b/source/libbson/api/bson_string_t/bson_string_append_c.txt new file mode 100644 index 00000000..fb916c4c --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_append_c.txt @@ -0,0 +1,25 @@ +.. _bson_string_append_c: + +====================== +bson_string_append_c() +====================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_string_append_c (bson_string_t *string, char str); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``str``: An ASCII char. + +Description +----------- + +Appends ``c`` to the string builder ``string``. + diff --git a/source/libbson/api/bson_string_t/bson_string_append_printf.txt b/source/libbson/api/bson_string_t/bson_string_append_printf.txt new file mode 100644 index 00000000..4c80dcce --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_append_printf.txt @@ -0,0 +1,26 @@ +.. _bson_string_append_printf: + +=========================== +bson_string_append_printf() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_string_append_printf (bson_string_t *string, const char *format, ...) + BSON_GNUC_PRINTF (2, 3); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``format``: A printf style format string. + +Description +----------- + +Like bson_string_append() but formats a printf style string and then appends that to ``string``. + diff --git a/source/libbson/api/bson_string_t/bson_string_append_unichar.txt b/source/libbson/api/bson_string_t/bson_string_append_unichar.txt new file mode 100644 index 00000000..7c538968 --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_append_unichar.txt @@ -0,0 +1,26 @@ +.. _bson_string_append_unichar: + +============================ +bson_string_append_unichar() +============================ + +Synopsis +-------- + +.. code-block:: c + + void + bson_string_append_unichar (bson_string_t *string, bson_unichar_t unichar); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``unichar``: A :ref:`bson_unichar_t`. + +Description +----------- + +Appends a unicode character to string. The character will be encoded into its multi-byte +UTF-8 representation. + diff --git a/source/libbson/api/bson_string_t/bson_string_free.txt b/source/libbson/api/bson_string_t/bson_string_free.txt new file mode 100644 index 00000000..49f4e9ff --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_free.txt @@ -0,0 +1,30 @@ +.. _bson_string_free: + +================== +bson_string_free() +================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_string_free (bson_string_t *string, bool free_segment); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``free_segment``: A bool indicating whether ``string->str`` should be freed. + +Description +----------- + +Frees the ``bson_string_t`` structure and optionally ``string->str``. + +Returns +------- + +``string->str`` if ``free_segment`` is false, otherwise ``NULL``. + diff --git a/source/libbson/api/bson_string_t/bson_string_new.txt b/source/libbson/api/bson_string_t/bson_string_new.txt new file mode 100644 index 00000000..e1fbafe1 --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_new.txt @@ -0,0 +1,30 @@ +.. _bson_string_new: + +================= +bson_string_new() +================= + +Synopsis +-------- + +.. code-block:: c + + bson_string_t * + bson_string_new (const char *str); + +Parameters +---------- + +- ``str``: A string to be copied or NULL. + +Description +----------- + +Creates a new string builder, which uses power-of-two growth of buffers. Use the various +bson_string_append*() functions to append to the string. + +Returns +------- + +A newly allocated bson_string_t that should be freed with bson_string_free() when no longer in use. + diff --git a/source/libbson/api/bson_string_t/bson_string_truncate.txt b/source/libbson/api/bson_string_t/bson_string_truncate.txt new file mode 100644 index 00000000..2eaf76f3 --- /dev/null +++ b/source/libbson/api/bson_string_t/bson_string_truncate.txt @@ -0,0 +1,28 @@ +.. _bson_string_truncate: + +====================== +bson_string_truncate() +====================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_string_truncate (bson_string_t *string, uint32_t len); + +Parameters +---------- + +- ``string``: A :ref:`bson_string_t`. +- ``len``: The new length of the string, excluding the trailing ``\0``. + +Description +----------- + +Truncates the string so that it is ``len`` bytes in length. This must be smaller or equal +to the current length of the string. + +A ``\0`` byte will be placed where the end of the string occurs. + diff --git a/source/libbson/api/bson_subtype_t.txt b/source/libbson/api/bson_subtype_t.txt new file mode 100644 index 00000000..3be8b8b8 --- /dev/null +++ b/source/libbson/api/bson_subtype_t.txt @@ -0,0 +1,43 @@ +.. _bson_subtype_t: + +============== +bson_subtype_t +============== + +Binary Field Subtype + +Synopsis +-------- + +.. code-block:: c + + #include + + + typedef enum { + BSON_SUBTYPE_BINARY = 0x00, + BSON_SUBTYPE_FUNCTION = 0x01, + BSON_SUBTYPE_BINARY_DEPRECATED = 0x02, + BSON_SUBTYPE_UUID_DEPRECATED = 0x03, + BSON_SUBTYPE_UUID = 0x04, + BSON_SUBTYPE_MD5 = 0x05, + BSON_SUBTYPE_COLUMN = 0x07, + BSON_SUBTYPE_SENSITIVE = 0x08, + BSON_SUBTYPE_USER = 0x80, + } bson_subtype_t; + +Description +----------- + +This enumeration contains the various subtypes that may be used in a binary field. See +`http://bsonspec.org `_ for more information. + +Example +------- + +.. code-block:: c + + bson_t doc = BSON_INITIALIZER; + + BSON_APPEND_BINARY (&doc, "binary", BSON_SUBTYPE_BINARY, data, data_len); + diff --git a/source/libbson/api/bson_t.txt b/source/libbson/api/bson_t.txt new file mode 100644 index 00000000..924eb95c --- /dev/null +++ b/source/libbson/api/bson_t.txt @@ -0,0 +1,249 @@ +.. _bson_t: + +====== +bson_t +====== + +BSON Document Abstraction + +Synopsis +-------- + +.. code-block:: c + + #include + + /** + * 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) /* ... */ + + /** + * bson_empty0: + * + * Like bson_empty() but treats NULL the same as an empty bson_t document. + */ + #define bson_empty0(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) /* ... */ + + /** + * BSON_MAX_SIZE: + * + * The maximum size in bytes of a BSON document. + */ + #define BSON_MAX_SIZE /* ... */ + + #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_ALIGNED_BEGIN (128) + typedef struct { + uint32_t flags; /* Internal flags for the bson_t. */ + uint32_t len; /* Length of BSON data. */ + uint8_t padding[120]; /* Padding for stack allocation. */ + } bson_t BSON_ALIGNED_END (128); + +Description +----------- + +The :ref:`bson_t` structure represents a BSON document. This structure manages the +underlying BSON encoded buffer. For mutable documents, it can append new data to the +document. + +Performance Notes +----------------- + +The :ref:`bson_t` structure attempts to use an inline allocation within the structure +to speed up performance of small documents. When this internal buffer has been exhausted, +a heap allocated buffer will be dynamically allocated. Therefore, it is essential to call +:ref:`bson_destroy` on allocated documents. + +Duplicate Keys +-------------- + +The `BSON specification `_ allows BSON documents to have +duplicate keys. Documents are stored as an ordered list of key-value pairs. A +:ref:`bson_t` may contain duplicate keys. Applications should refrain from +generating such documents, because MongoDB server behavior is undefined when a +BSON document contains duplicate keys. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_t/bson_append_array + /libbson/api/bson_t/bson_append_array_begin + /libbson/api/bson_t/bson_append_array_end + /libbson/api/bson_t/bson_append_binary + /libbson/api/bson_t/bson_append_bool + /libbson/api/bson_t/bson_append_code + /libbson/api/bson_t/bson_append_code_with_scope + /libbson/api/bson_t/bson_append_date_time + /libbson/api/bson_t/bson_append_dbpointer + /libbson/api/bson_t/bson_append_decimal128 + /libbson/api/bson_t/bson_append_document + /libbson/api/bson_t/bson_append_document_begin + /libbson/api/bson_t/bson_append_document_end + /libbson/api/bson_t/bson_append_double + /libbson/api/bson_t/bson_append_int32 + /libbson/api/bson_t/bson_append_int64 + /libbson/api/bson_t/bson_append_iter + /libbson/api/bson_t/bson_append_maxkey + /libbson/api/bson_t/bson_append_minkey + /libbson/api/bson_t/bson_append_now_utc + /libbson/api/bson_t/bson_append_null + /libbson/api/bson_t/bson_append_oid + /libbson/api/bson_t/bson_append_regex + /libbson/api/bson_t/bson_append_regex_w_len + /libbson/api/bson_t/bson_append_symbol + /libbson/api/bson_t/bson_append_time_t + /libbson/api/bson_t/bson_append_timestamp + /libbson/api/bson_t/bson_append_timeval + /libbson/api/bson_t/bson_append_undefined + /libbson/api/bson_t/bson_append_utf8 + /libbson/api/bson_t/bson_append_value + /libbson/api/bson_t/bson_array_as_canonical_extended_json + /libbson/api/bson_t/bson_array_as_json + /libbson/api/bson_t/bson_array_as_relaxed_extended_json + /libbson/api/bson_t/bson_as_canonical_extended_json + /libbson/api/bson_t/bson_as_json + /libbson/api/bson_t/bson_as_json_with_opts + /libbson/api/bson_t/bson_as_relaxed_extended_json + /libbson/api/bson_t/bson_compare + /libbson/api/bson_t/bson_concat + /libbson/api/bson_t/bson_copy + /libbson/api/bson_t/bson_copy_to + /libbson/api/bson_t/bson_copy_to_excluding + /libbson/api/bson_t/bson_copy_to_excluding_noinit + /libbson/api/bson_t/bson_copy_to_excluding_noinit_va + /libbson/api/bson_t/bson_count_keys + /libbson/api/bson_t/bson_destroy + /libbson/api/bson_t/bson_destroy_with_steal + /libbson/api/bson_t/bson_equal + /libbson/api/bson_t/bson_get_data + /libbson/api/bson_t/bson_has_field + /libbson/api/bson_t/bson_init + /libbson/api/bson_t/bson_init_from_json + /libbson/api/bson_t/bson_init_static + /libbson/api/bson_t/bson_json_mode_t + /libbson/api/bson_t/bson_json_opts_t + /libbson/api/bson_t/bson_new + /libbson/api/bson_t/bson_new_from_buffer + /libbson/api/bson_t/bson_new_from_data + /libbson/api/bson_t/bson_new_from_json + /libbson/api/bson_t/bson_reinit + /libbson/api/bson_t/bson_reserve_buffer + /libbson/api/bson_t/bson_sized_new + /libbson/api/bson_t/bson_steal + /libbson/api/bson_t/bson_validate + /libbson/api/bson_t/bson_validate_with_error + +Example +------- + +.. code-block:: c + + static void + create_on_heap (void) + { + bson_t *b = bson_new (); + + BSON_APPEND_INT32 (b, "foo", 123); + BSON_APPEND_UTF8 (b, "bar", "foo"); + BSON_APPEND_DOUBLE (b, "baz", 1.23f); + + bson_destroy (b); + } + diff --git a/source/libbson/api/bson_t/bson_append_array.txt b/source/libbson/api/bson_t/bson_append_array.txt new file mode 100644 index 00000000..798b855c --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_array.txt @@ -0,0 +1,44 @@ +.. _bson_append_array: + +=================== +bson_append_array() +=================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_ARRAY(b, key, val) \ + bson_append_array (b, key, (int) strlen (key), val) + + bool + bson_append_array (bson_t *bson, + const char *key, + int key_length, + const bson_t *array); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen``. +- ``array``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_append_array` function shall append ``array`` to ``bson`` using the specified +key. The type of the field will be an array, but it is the responsibility of the caller to ensure +that the keys of ``array`` are properly formatted with string keys such as "0", "1", "2" and so forth. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function fails if appending the array +grows ``bson`` larger than INT32_MAX. + +.. seealso:: + + | :ref:`bson_array_builder_t` diff --git a/source/libbson/api/bson_t/bson_append_array_begin.txt b/source/libbson/api/bson_t/bson_append_array_begin.txt new file mode 100644 index 00000000..eb0fef0e --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_array_begin.txt @@ -0,0 +1,51 @@ +.. _bson_append_array_begin: + +========================= +bson_append_array_begin() +========================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \ + bson_append_array_begin (b, key, (int) strlen (key), child) + + bool + bson_append_array_begin (bson_t *bson, + const char *key, + int key_length, + bson_t *child); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: A string containing the name for the key. +- ``key_length``: The length of ``key`` or -1 to call ``strlen()``. +- ``child``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_append_array_begin` function shall begin appending an array field to +``bson``. This allows for incrementally building a sub-array. Doing so will generally yield +better performance as you will serialize to a single buffer. When done building the sub-array, +the caller *MUST* call :ref:`bson_append_array_end`. + +For generating array element keys, see :ref:`bson_uint32_to_string`. + +Consider using :ref:`bson_array_builder_t` to append an array without needing to generate +array element keys. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the array grows ``bson`` larger than INT32_MAX. + +.. seealso:: + + | :ref:`bson_array_builder_t` + diff --git a/source/libbson/api/bson_t/bson_append_array_end.txt b/source/libbson/api/bson_t/bson_append_array_end.txt new file mode 100644 index 00000000..7de3b036 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_array_end.txt @@ -0,0 +1,34 @@ +.. _bson_append_array_end: + +======================= +bson_append_array_end() +======================= + +Synopsis +-------- + +.. code-block:: c + + bool + bson_append_array_end (bson_t *bson, bson_t *child); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``child``: The :ref:`bson_t` initialized in a call to :ref:`bson_append_array_begin`. + +Description +----------- + +The :ref:`bson_append_array_end` function shall complete the appending of an array field +started with :ref:`bson_append_array_begin`. ``child`` is invalid after calling this function. + +Returns +------- + +Returns ``true`` if successful. + +.. seealso:: + + | :ref:`bson_array_builder_t` diff --git a/source/libbson/api/bson_t/bson_append_binary.txt b/source/libbson/api/bson_t/bson_append_binary.txt new file mode 100644 index 00000000..4eae4260 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_binary.txt @@ -0,0 +1,43 @@ +.. _bson_append_binary: + +==================== +bson_append_binary() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_BINARY(b, key, subtype, val, len) \ + bson_append_binary (b, key, (int) strlen (key), subtype, val, len) + + bool + bson_append_binary (bson_t *bson, + const char *key, + int key_length, + bson_subtype_t subtype, + const uint8_t *binary, + uint32_t length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: The key name. +- ``key_length``: The length of ``key`` in bytes or -1 to use strlen(). +- ``subtype``: A bson_subtype_t indicating the binary subtype. +- ``binary``: A buffer to embed as binary data. May be ``NULL`` for an empty binary value. +- ``length``: The length of ``buffer`` in bytes. Must be ``0`` if ``binary`` is NULL. + +Description +----------- + +The :ref:`bson_append_binary` function shall append a new element to ``bson`` containing +the binary data provided. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``binary`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_bool.txt b/source/libbson/api/bson_t/bson_append_bool.txt new file mode 100644 index 00000000..c5522b56 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_bool.txt @@ -0,0 +1,36 @@ +.. _bson_append_bool: + +================== +bson_append_bool() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_BOOL(b, key, val) \ + bson_append_bool (b, key, (int) strlen (key), val) + + bool + bson_append_bool (bson_t *bson, const char *key, int key_length, bool value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: The name of the field. +- ``key_length``: The length of ``key`` or -1 to use strlen(). +- ``value``: true or false. + +Description +----------- + +The :ref:`bson_append_bool` function shall append a new element to ``bson`` containing the +boolean provided. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_code.txt b/source/libbson/api/bson_t/bson_append_code.txt new file mode 100644 index 00000000..047ec524 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_code.txt @@ -0,0 +1,39 @@ +.. _bson_append_code: + +================== +bson_append_code() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_CODE(b, key, val) \ + bson_append_code (b, key, (int) strlen (key), val) + + bool + bson_append_code (bson_t *bson, + const char *key, + int key_length, + const char *javascript); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: The key name. +- ``key_length``: The length of ``key`` or -1 to use strlen(). +- ``javascript``: A UTF-8 encoded string containing the javascript. + +Description +----------- + +The :ref:`bson_append_code` function shall append a new element to ``bson`` using +the UTF-8 encoded ``javascript`` provided. ``javascript`` must be a NULL terminated C string. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``javascript`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_code_with_scope.txt b/source/libbson/api/bson_t/bson_append_code_with_scope.txt new file mode 100644 index 00000000..a5dd62a4 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_code_with_scope.txt @@ -0,0 +1,44 @@ +.. _bson_append_code_with_scope: + +============================= +bson_append_code_with_scope() +============================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \ + bson_append_code_with_scope (b, key, (int) strlen (key), val, scope) + + bool + bson_append_code_with_scope (bson_t *bson, + const char *key, + int key_length, + const char *javascript, + const bson_t *scope); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``javascript``: A NULL-terminated UTF-8 encoded string containing the javascript fragment. +- ``scope``: Optional :ref:`bson_t` containing the scope for ``javascript``. + +Description +----------- + +The :ref:`bson_append_code_with_scope` function shall perform like :ref:`bson_append_code` +except it allows providing a scope to the javascript function in the form of a bson document. + +If ``scope`` is NULL, this function appends an element with BSON type "code", otherwise with BSON +type "code with scope". + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``javascript`` and ``scope`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_date_time.txt b/source/libbson/api/bson_t/bson_append_date_time.txt new file mode 100644 index 00000000..690de24f --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_date_time.txt @@ -0,0 +1,40 @@ +.. _bson_append_date_time: + +======================= +bson_append_date_time() +======================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DATE_TIME(b, key, val) \ + bson_append_date_time (b, key, (int) strlen (key), val) + + bool + bson_append_date_time (bson_t *bson, + const char *key, + int key_length, + int64_t value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: The date and time as specified in milliseconds since the UNIX epoch. + +Description +----------- + +The :ref:`bson_append_date_time` function shall append a new element to a ``bson`` document +containing a date and time with no timezone information. ``value`` is assumed to be in UTC format +of milliseconds since the UNIX epoch. ``value`` *MAY* be negative. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_dbpointer.txt b/source/libbson/api/bson_t/bson_append_dbpointer.txt new file mode 100644 index 00000000..89dbbb40 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_dbpointer.txt @@ -0,0 +1,42 @@ +.. _bson_append_dbpointer: + +======================= +bson_append_dbpointer() +======================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DBPOINTER(b, key, coll, oid) \ + bson_append_dbpointer (b, key, (int) strlen (key), coll, oid) + + bool + bson_append_dbpointer (bson_t *bson, + const char *key, + int key_length, + const char *collection, + const bson_oid_t *oid); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``collection``: The target collection name. +- ``oid``: The target document identifier. + +Description +----------- + +.. warning:: + + The dbpointer field type is *DEPRECATED* and should only be used when interacting with legacy systems. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending the +array grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_decimal128.txt b/source/libbson/api/bson_t/bson_append_decimal128.txt new file mode 100644 index 00000000..511cf083 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_decimal128.txt @@ -0,0 +1,39 @@ +.. _bson_append_decimal128: + +======================== +bson_append_decimal128() +======================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DECIMAL128(b, key, val) \ + bson_append_decimal128 (b, key, (int) strlen (key), val) + + bool + bson_append_decimal128 (bson_t *bson, + const char *key, + int key_length, + const bson_decimal128_t *value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A :ref:`bson_decimal128_t`. + +Description +----------- + +The :ref:`bson_append_decimal128` function shall append a new element to ``bson`` containing +a Decimal 128. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_document.txt b/source/libbson/api/bson_t/bson_append_document.txt new file mode 100644 index 00000000..464fb2a6 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_document.txt @@ -0,0 +1,39 @@ +.. _bson_append_document: + +====================== +bson_append_document() +====================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DOCUMENT(b, key, val) \ + bson_append_document (b, key, (int) strlen (key), val) + + bool + bson_append_document (bson_t *bson, + const char *key, + int key_length, + const bson_t *value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A :ref:`bson_t` containing the sub-document to append. + +Description +----------- + +The :ref:`bson_append_document` function shall append ``child`` to ``bson`` using the +specified key. The type of the field will be a document. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_document_begin.txt b/source/libbson/api/bson_t/bson_append_document_begin.txt new file mode 100644 index 00000000..baf7b784 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_document_begin.txt @@ -0,0 +1,42 @@ +.. _bson_append_document_begin: + +============================ +bson_append_document_begin() +============================ + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \ + bson_append_document_begin (b, key, (int) strlen (key), child) + + bool + bson_append_document_begin (bson_t *bson, + const char *key, + int key_length, + bson_t *child); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``child``: An uninitialized :ref:`bson_t` be initialized as the sub-document. + +Description +----------- + +The :ref:`bson_append_document_begin` function shall begin appending a sub-document to +``bson``. Use ``child`` to add fields to the sub-document. When completed, call +:ref:`bson_append_document_end` complete the element. + +``child`` *MUST* be an uninitialized :ref:`bson_t` avoid leaking memory. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if ``bson`` +must grow larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_document_end.txt b/source/libbson/api/bson_t/bson_append_document_end.txt new file mode 100644 index 00000000..3c07bf6e --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_document_end.txt @@ -0,0 +1,30 @@ +.. _bson_append_document_end: + +========================== +bson_append_document_end() +========================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_append_document_end (bson_t *bson, bson_t *child); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``child``: The child :ref:`bson_t` initialized in a call to :ref:`bson_append_document_begin` + +Description +----------- + +The :ref:`bson_append_document_end` function shall complete the appending of a document with +:ref:`bson_append_document_begin`. ``child`` is invalid after calling this function. + +Returns +------- + +Returns ``true`` if successful. diff --git a/source/libbson/api/bson_t/bson_append_double.txt b/source/libbson/api/bson_t/bson_append_double.txt new file mode 100644 index 00000000..199704ce --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_double.txt @@ -0,0 +1,39 @@ +.. _bson_append_double: + +==================== +bson_append_double() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_DOUBLE(b, key, val) \ + bson_append_double (b, key, (int) strlen (key), val) + + bool + bson_append_double (bson_t *bson, + const char *key, + int key_length, + double value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A double value to append. + +Description +----------- + +The :ref:`bson_append_double` function shall append a new element to a bson document of +type ``double``. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_int32.txt b/source/libbson/api/bson_t/bson_append_int32.txt new file mode 100644 index 00000000..59126669 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_int32.txt @@ -0,0 +1,39 @@ +.. _bson_append_int32: + +=================== +bson_append_int32() +=================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_INT32(b, key, val) \ + bson_append_int32 (b, key, (int) strlen (key), val) + + bool + bson_append_int32 (bson_t *bson, + const char *key, + int key_length, + int32_t value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: An int32_t. + +Description +----------- + +The :ref:`bson_append_int32` function shall append a new element to ``bson`` containing +a 32-bit signed integer. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_int64.txt b/source/libbson/api/bson_t/bson_append_int64.txt new file mode 100644 index 00000000..9b2646e9 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_int64.txt @@ -0,0 +1,39 @@ +.. _bson_append_int64: + +=================== +bson_append_int64() +=================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_INT64(b, key, val) \ + bson_append_int64 (b, key, (int) strlen (key), val) + + bool + bson_append_int64 (bson_t *bson, + const char *key, + int key_length, + int64_t value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: An int64_t. + +Description +----------- + +The :ref:`bson_append_int64` function shall append a new element to ``bson`` containing +a 64-bit signed integer. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``value`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_iter.txt b/source/libbson/api/bson_t/bson_append_iter.txt new file mode 100644 index 00000000..a902dab5 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_iter.txt @@ -0,0 +1,35 @@ +.. _bson_append_iter: + +================== +bson_append_iter() +================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_append_iter (bson_t *bson, + const char *key, + int key_length, + const bson_iter_t *iter); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: Optional field name. If NULL, uses :ref:`bson_iter_key`. +- ``key_length``: The length of ``key`` or -1 to use strlen(). +- ``iter``: A :ref:`bson_iter_t` located on the position of the element to append. + +Description +----------- + +Appends the value at the current position of ``iter`` to the document. + +Returns +------- + +Returns ``true`` if successful; ``false`` if the operation would overflow the maximum document +size or another invalid state is detected. diff --git a/source/libbson/api/bson_t/bson_append_maxkey.txt b/source/libbson/api/bson_t/bson_append_maxkey.txt new file mode 100644 index 00000000..2609b6a0 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_maxkey.txt @@ -0,0 +1,36 @@ +.. _bson_append_maxkey: + +==================== +bson_append_maxkey() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_MAXKEY(b, key) \ + bson_append_maxkey (b, key, (int) strlen (key)) + + bool + bson_append_maxkey (bson_t *bson, const char *key, int key_length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_maxkey` function shall append an element of type BSON_TYPE_MAXKEY +to a bson document. This is primarily used in queries and unlikely to be used when storing a +document to MongoDB. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_minkey.txt b/source/libbson/api/bson_t/bson_append_minkey.txt new file mode 100644 index 00000000..6fac8643 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_minkey.txt @@ -0,0 +1,36 @@ +.. _bson_append_minkey: + +==================== +bson_append_minkey() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_MINKEY(b, key) \ + bson_append_minkey (b, key, (int) strlen (key)) + + bool + bson_append_minkey (bson_t *bson, const char *key, int key_length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_minkey` function shall append an element of type BSON_TYPE_MINKEY +to a bson document. This is primarily used in queries and unlikely to be used when storing a +document to MongoDB. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_now_utc.txt b/source/libbson/api/bson_t/bson_append_now_utc.txt new file mode 100644 index 00000000..c34d308b --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_now_utc.txt @@ -0,0 +1,34 @@ +.. _bson_append_now_utc: + +===================== +bson_append_now_utc() +===================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_append_now_utc (bson_t *bson, const char *key, int key_length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_now_utc` function is a helper to get the current date and time in +UTC and append it to ``bson`` as a BSON_TYPE_DATE_TIME element. + +This function calls :ref:`bson_append_date_time` internally. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_null.txt b/source/libbson/api/bson_t/bson_append_null.txt new file mode 100644 index 00000000..9af32f68 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_null.txt @@ -0,0 +1,34 @@ +.. _bson_append_null: + +================== +bson_append_null() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key)) + + bool + bson_append_null (bson_t *bson, const char *key, int key_length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_null` function shall append a new element to ``bson`` of type +BSON_TYPE_NULL. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_oid.txt b/source/libbson/api/bson_t/bson_append_oid.txt new file mode 100644 index 00000000..ed6a9a52 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_oid.txt @@ -0,0 +1,39 @@ +.. _bson_append_oid: + +================= +bson_append_oid() +================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_OID(b, key, val) \ + bson_append_oid (b, key, (int) strlen (key), val) + + bool + bson_append_oid (bson_t *bson, + const char *key, + int key_length, + const bson_oid_t *oid); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``oid``: A bson_oid_t. + +Description +----------- + +The :ref:`bson_append_oid` function shall append a new element to ``bson`` of type BSON_TYPE_OID. +``oid`` *MUST* be a pointer to a :ref:`bson_oid_t`. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +``oid`` grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_regex.txt b/source/libbson/api/bson_t/bson_append_regex.txt new file mode 100644 index 00000000..cc621801 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_regex.txt @@ -0,0 +1,50 @@ +.. _bson_append_regex: + +=================== +bson_append_regex() +=================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_REGEX(b, key, val, opt) \ + bson_append_regex (b, key, (int) strlen (key), val, opt) + + bool + bson_append_regex (bson_t *bson, + const char *key, + int key_length, + const char *regex, + const char *options); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``regex``: An ASCII string containing the regex. +- ``options``: An optional string containing the regex options as a string. + +Description +----------- + +Appends a new field to ``bson`` of type BSON_TYPE_REGEX. ``regex`` should be the regex string. +``options`` should contain the options for the regex. + +Valid characters for ``options`` include: + +- ``'i'`` for case-insensitive. +- ``'m'`` for multiple matching. +- ``'x'`` for verbose mode. +- ``'l'`` to make \w and \W locale dependent. +- ``'s'`` for dotall mode ('.' matches everything) +- ``'u'`` to make \w and \W match unicode. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the regex grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_regex_w_len.txt b/source/libbson/api/bson_t/bson_append_regex_w_len.txt new file mode 100644 index 00000000..3b1519c3 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_regex_w_len.txt @@ -0,0 +1,50 @@ +.. _bson_append_regex_w_len: + +========================= +bson_append_regex_w_len() +========================= + +Synopsis +-------- + +.. code-block:: c + + bool + bson_append_regex_w_len (bson_t *bson, + const char *key, + int key_length, + const char *regex, + int regex_length, + const char *options); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``regex``: An ASCII string containing the regex. +- ``regex_length``: The length of ``regex`` in bytes, or -1 to determine the length with ``strlen()``. +- ``options``: An optional string containing the regex options as a string. + +Description +----------- + +Appends a new field to ``bson`` of type BSON_TYPE_REGEX. ``regex`` should be the regex string. +``options`` should contain the options for the regex. + +Valid characters for ``options`` include: + +- ``'i'`` for case-insensitive. +- ``'m'`` for multiple matching. +- ``'x'`` for verbose mode. +- ``'l'`` to make \w and \W locale dependent. +- ``'s'`` for dotall mode ('.' matches everything) +- ``'u'`` to make \w and \W match unicode. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the regex grows ``bson`` larger than INT32_MAX. + diff --git a/source/libbson/api/bson_t/bson_append_symbol.txt b/source/libbson/api/bson_t/bson_append_symbol.txt new file mode 100644 index 00000000..f349779c --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_symbol.txt @@ -0,0 +1,44 @@ +.. _bson_append_symbol: + +==================== +bson_append_symbol() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_SYMBOL(b, key, val) \ + bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val)) + + bool + bson_append_symbol (bson_t *bson, + const char *key, + int key_length, + const char *value, + int length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: The symbol. +- ``length``: A length of ``symbol`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +Appends a new field to ``bson`` of type BSON_TYPE_SYMBOL. This BSON type is deprecated and should +not be used in new code. + +Due to legacy behavior, passing ``NULL`` for ``value`` appends a null value, *not* a symbol value. +To append a null value directly, prefer using :ref:`bson_append_null`. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending the +value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_time_t.txt b/source/libbson/api/bson_t/bson_append_time_t.txt new file mode 100644 index 00000000..4e96b68d --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_time_t.txt @@ -0,0 +1,39 @@ +.. _bson_append_time_t: + +==================== +bson_append_time_t() +==================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_TIME_T(b, key, val) \ + bson_append_time_t (b, key, (int) strlen (key), val) + + bool + bson_append_time_t (bson_t *bson, + const char *key, + int key_length, + time_t value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A time_t. + +Description +----------- + +The :ref:`bson_append_time_t` function is a helper that takes a ``time_t`` instead of +milliseconds since the UNIX epoch. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_timestamp.txt b/source/libbson/api/bson_t/bson_append_timestamp.txt new file mode 100644 index 00000000..23e16e35 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_timestamp.txt @@ -0,0 +1,46 @@ +.. _bson_append_timestamp: + +======================= +bson_append_timestamp() +======================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_TIMESTAMP(b, key, val, inc) \ + bson_append_timestamp (b, key, (int) strlen (key), val, inc) + + bool + bson_append_timestamp (bson_t *bson, + const char *key, + int key_length, + uint32_t timestamp, + uint32_t increment); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``timestamp``: A uint32_t. +- ``increment``: A uint32_t. + +Description +----------- + +This function is not similar in functionality to :ref:`bson_append_date_time`. Timestamp +elements are different in that they include only second precision and an increment field. + +They are primarily used for intra-MongoDB server communication. + +The :ref:`bson_append_timestamp` function shall append a new element of type +BSON_TYPE_TIMESTAMP. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_timeval.txt b/source/libbson/api/bson_t/bson_append_timeval.txt new file mode 100644 index 00000000..ee8ed1c5 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_timeval.txt @@ -0,0 +1,39 @@ +.. _bson_append_timeval: + +===================== +bson_append_timeval() +===================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_TIMEVAL(b, key, val) \ + bson_append_timeval (b, key, (int) strlen (key), val) + + bool + bson_append_timeval (bson_t *bson, + const char *key, + int key_length, + struct timeval *value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A struct timeval. + +Description +----------- + +The :ref:`bson_append_timeval` function is a helper that takes a ``struct timeval`` instead +of milliseconds since the UNIX epoch. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_undefined.txt b/source/libbson/api/bson_t/bson_append_undefined.txt new file mode 100644 index 00000000..5b7dbbfb --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_undefined.txt @@ -0,0 +1,36 @@ +.. _bson_append_undefined: + +======================= +bson_append_undefined() +======================= + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_UNDEFINED(b, key) \ + bson_append_undefined (b, key, (int) strlen (key)) + + bool + bson_append_undefined (bson_t *bson, const char *key, int key_length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_undefined` function shall append a new element to ``bson`` of +type BSON_TYPE_UNDEFINED. Undefined is common in Javascript. However, this element type +is deprecated and should not be used in new code. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if +appending the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_utf8.txt b/source/libbson/api/bson_t/bson_append_utf8.txt new file mode 100644 index 00000000..86fee448 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_utf8.txt @@ -0,0 +1,53 @@ +.. _bson_append_utf8: + +================== +bson_append_utf8() +================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_UTF8(b, key, val) \ + bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val)) + + bool + bson_append_utf8 (bson_t *bson, + const char *key, + int key_length, + const char *value, + int length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A UTF-8 encoded string. +- ``length``: The number of bytes in ``value`` excluding the trailing ``\0``, or -1 to determine + the length with ``strlen()``. + +Description +----------- + +The :ref:`bson_append_utf8` function shall append a UTF-8 encoded string to ``bson``. + +``value`` *MUST* be valid UTF-8. + +Some UTF-8 implementations allow for ``\0`` to be contained within the string (excluding the termination +``\0``). This is allowed, but remember that it could cause issues with communicating with external systems +that do not support it. + +It is suggested to use modified UTF-8 which uses a 2 byte representation for embedded ``\0`` within the +string. This will allow these UTF-8 encoded strings to used with many libc functions. + +Due to legacy behavior, passing ``NULL`` for ``value`` appends a null value, *not* a UTF8 value. To append +a null value directly, prefer using :ref:`bson_append_null`. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending the value +grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_append_value.txt b/source/libbson/api/bson_t/bson_append_value.txt new file mode 100644 index 00000000..4fc717c4 --- /dev/null +++ b/source/libbson/api/bson_t/bson_append_value.txt @@ -0,0 +1,39 @@ +.. _bson_append_value: + +=================== +bson_append_value() +=================== + +Synopsis +-------- + +.. code-block:: c + + #define BSON_APPEND_VALUE(b, key, val) \ + bson_append_value (b, key, (int) strlen (key), (val)) + + bool + bson_append_value (bson_t *bson, + const char *key, + int key_length, + const bson_value_t *value); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: An ASCII C string containing the name of the field. +- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``. +- ``value``: A :ref:`bson_value_t`. + +Description +----------- + +Appends a new field to ``bson`` by determining the boxed type in ``value``. This is useful if you +want to copy fields between documents but do not know the field type until runtime. + +Returns +------- + +Returns ``true`` if the operation was applied successfully. The function will fail if appending +the value grows ``bson`` larger than INT32_MAX. diff --git a/source/libbson/api/bson_t/bson_array_as_canonical_extended_json.txt b/source/libbson/api/bson_t/bson_array_as_canonical_extended_json.txt new file mode 100644 index 00000000..8ca702f8 --- /dev/null +++ b/source/libbson/api/bson_t/bson_array_as_canonical_extended_json.txt @@ -0,0 +1,70 @@ +.. _bson_array_as_canonical_extended_json: + +======================================= +bson_array_as_canonical_extended_json() +======================================= + +Synopsis +-------- + +.. code-block:: c + + char * + bson_array_as_canonical_extended_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_array_as_canonical_extended_json` encodes ``bson`` as a UTF-8 string +in the canonical `MongoDB Extended JSON format `_, except the outermost element is encoded +as a JSON array, rather than a JSON document. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + #include + + int main () + { + bson_t bson; + char *str; + + bson_init (&bson); + /* BSON array is a normal BSON document with integer values for the keys, + * starting with 0 and continuing sequentially + */ + BSON_APPEND_INT32 (&bson, "0", 1); + BSON_APPEND_UTF8 (&bson, "1", "bar"); + + str = bson_array_as_canonical_extended_json (&bson, NULL); + /* Prints + * [ { "$numberInt" : 1 }, "bar" ] + */ + printf ("%s\n", str); + bson_free (str); + + bson_destroy (&bson); + } + + +.. include:: /libbson/includes/seealso/bson-as-json.rst diff --git a/source/libbson/api/bson_t/bson_array_as_json.txt b/source/libbson/api/bson_t/bson_array_as_json.txt new file mode 100644 index 00000000..9ace55ad --- /dev/null +++ b/source/libbson/api/bson_t/bson_array_as_json.txt @@ -0,0 +1,72 @@ +.. _bson_array_as_json: + +==================== +bson_array_as_json() +==================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_array_as_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_array_as_json` function shall encode ``bson`` as a UTF-8 +string using libbson's legacy JSON format, except the outermost element is +encoded as a JSON array, rather than a JSON document. This function is +superseded by :ref:`bson_array_as_canonical_extended_json` and +:ref:`bson_array_as_relaxed_extended_json`, which use the same +`MongoDB Extended JSON format `_ as all other MongoDB drivers. +The caller is responsible for freeing the resulting UTF-8 encoded string by +calling :ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + #include + + int main () + { + bson_t bson; + char *str; + + bson_init (&bson); + /* BSON array is a normal BSON document with integer values for the keys, + * starting with 0 and continuing sequentially + */ + BSON_APPEND_UTF8 (&bson, "0", "foo"); + BSON_APPEND_UTF8 (&bson, "1", "bar"); + + str = bson_array_as_json (&bson, NULL); + /* Prints + * [ "foo", "bar" ] + */ + printf ("%s\n", str); + bson_free (str); + + bson_destroy (&bson); + } + + +.. include:: /libbson/includes/seealso/bson-as-json.rst diff --git a/source/libbson/api/bson_t/bson_array_as_relaxed_extended_json.txt b/source/libbson/api/bson_t/bson_array_as_relaxed_extended_json.txt new file mode 100644 index 00000000..6fccfa46 --- /dev/null +++ b/source/libbson/api/bson_t/bson_array_as_relaxed_extended_json.txt @@ -0,0 +1,69 @@ +.. _bson_array_as_relaxed_extended_json: + +===================================== +bson_array_as_relaxed_extended_json() +===================================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_array_as_relaxed_extended_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_as_relaxed_extended_json` encodes ``bson`` as a UTF-8 string in +the relaxed `MongoDB Extended JSON format `_, except the outermost element is encoded +as a JSON array, rather than a JSON document. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + #include + + int main () + { + bson_t bson; + char *str; + + bson_init (&bson); + /* BSON array is a normal BSON document with integer values for the keys, + * starting with 0 and continuing sequentially + */ + BSON_APPEND_DOUBLE (&bson, "0", 3.14); + BSON_APPEND_UTF8 (&bson, "1", "bar"); + + str = bson_array_as_relaxed_extended_json (&bson, NULL); + /* Prints + * [ 3.14, "bar" ] + */ + printf ("%s\n", str); + bson_free (str); + + bson_destroy (&bson); + } + +.. include:: /libbson/includes/seealso/bson-as-json.rst diff --git a/source/libbson/api/bson_t/bson_as_canonical_extended_json.txt b/source/libbson/api/bson_t/bson_as_canonical_extended_json.txt new file mode 100644 index 00000000..c8aed368 --- /dev/null +++ b/source/libbson/api/bson_t/bson_as_canonical_extended_json.txt @@ -0,0 +1,49 @@ +.. _bson_as_canonical_extended_json: + +================================= +bson_as_canonical_extended_json() +================================= + +Synopsis +-------- + +.. code-block:: c + + char * + bson_as_canonical_extended_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_as_canonical_extended_json` encodes ``bson`` as a UTF-8 string +in the canonical `MongoDB Extended JSON format `_. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + char *str = bson_as_canonical_extended_json (doc, NULL); + printf ("%s\n", str); + bson_free (str); + + +.. include:: /libbson/includes/seealso/bson-as-json.rst diff --git a/source/libbson/api/bson_t/bson_as_json.txt b/source/libbson/api/bson_t/bson_as_json.txt new file mode 100644 index 00000000..a6752aeb --- /dev/null +++ b/source/libbson/api/bson_t/bson_as_json.txt @@ -0,0 +1,67 @@ +.. _bson_as_json: + +============== +bson_as_json() +============== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_as_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_as_json` function shall encode ``bson`` as a UTF-8 string using +libbson's legacy JSON format. This function is superseded by :ref:`bson_as_canonical_extended_json` +and :ref:`bson_as_relaxed_extended_json`, which use the same `MongoDB Extended JSON format `_ +as all other MongoDB drivers. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + #include + + int main () + { + bson_t bson; + char *str; + + bson_init (&bson); + BSON_APPEND_UTF8 (&bson, "0", "foo"); + BSON_APPEND_UTF8 (&bson, "1", "bar"); + + str = bson_as_json (&bson, NULL); + /* Prints + * { "0" : "foo", "1" : "bar" } + */ + printf ("%s\n", str); + bson_free (str); + + bson_destroy (&bson); + } + +.. include:: /libbson/includes/seealso/bson-as-json.rst \ No newline at end of file diff --git a/source/libbson/api/bson_t/bson_as_json_with_opts.txt b/source/libbson/api/bson_t/bson_as_json_with_opts.txt new file mode 100644 index 00000000..e4544fbe --- /dev/null +++ b/source/libbson/api/bson_t/bson_as_json_with_opts.txt @@ -0,0 +1,55 @@ +.. _bson_as_json_with_opts: + +======================== +bson_as_json_with_opts() +======================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_as_json_with_opts (const bson_t *bson, size_t *length, const bson_json_opts_t *opts); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``length``: An optional location for the length of the resulting string. +- ``opts``: A :ref:`bson_json_opts_t`. + +Description +----------- + +The :ref:`bson_as_json_with_opts` encodes ``bson`` as a UTF-8 string in the +`MongoDB Extended JSON format `_. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +The ``opts`` structure is used to pass options for the encoding process. Please refer to +the documentation of :ref:`bson_json_opts_t` for more details. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + bson_json_opts_t *opts = bson_json_opts_new (BSON_JSON_MODE_CANONICAL, BSON_MAX_LEN_UNLIMITED); + char *str = bson_as_json_with_opts (doc, NULL, opts); + printf ("%s\n", str); + bson_free (str); + bson_json_opts_destroy (opts); + + +.. include:: /libbson/includes/seealso/bson-as-json.rst \ No newline at end of file diff --git a/source/libbson/api/bson_t/bson_as_relaxed_extended_json.txt b/source/libbson/api/bson_t/bson_as_relaxed_extended_json.txt new file mode 100644 index 00000000..9811dcac --- /dev/null +++ b/source/libbson/api/bson_t/bson_as_relaxed_extended_json.txt @@ -0,0 +1,49 @@ +.. _bson_as_relaxed_extended_json: + +=============================== +bson_as_relaxed_extended_json() +=============================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_as_relaxed_extended_json (const bson_t *bson, size_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``length``: An optional location for the length of the resulting string. + +Description +----------- + +The :ref:`bson_as_relaxed_extended_json` encodes ``bson`` as a UTF-8 string in +the relaxed `MongoDB Extended JSON format `_. + +The caller is responsible for freeing the resulting UTF-8 encoded string by calling +:ref:`bson_free` with the result. + +If non-NULL, ``length`` will be set to the length of the result in bytes. + +Returns +------- + +If successful, a newly allocated UTF-8 encoded string and ``length`` is set. + +Upon failure, NULL is returned. + +Example +------- + +.. code-block:: c + + char *str = bson_as_relaxed_extended_json (doc, NULL); + printf ("%s\n", str); + bson_free (str); + + +.. include:: /libbson/includes/seealso/bson-as-json.rst diff --git a/source/libbson/api/bson_t/bson_compare.txt b/source/libbson/api/bson_t/bson_compare.txt new file mode 100644 index 00000000..4a3ae02c --- /dev/null +++ b/source/libbson/api/bson_t/bson_compare.txt @@ -0,0 +1,38 @@ +.. _bson_compare: + +============== +bson_compare() +============== + +Synopsis +-------- + +.. code-block:: c + + int + bson_compare (const bson_t *bson, const bson_t *other); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``other``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_compare` function shall compare two bson documents for equality. + +This can be useful in conjunction with _qsort()_. + +If equal, 0 is returned. + +.. tip:: + + This function uses _memcmp()_ internally, so the semantics are the same. + +Returns +------- + +Less than zero, zero, or greater than zero in ``qsort()`` style. + diff --git a/source/libbson/api/bson_t/bson_concat.txt b/source/libbson/api/bson_t/bson_concat.txt new file mode 100644 index 00000000..aee88c7e --- /dev/null +++ b/source/libbson/api/bson_t/bson_concat.txt @@ -0,0 +1,31 @@ +.. _bson_concat: + +============= +bson_concat() +============= + +Synopsis +-------- + +.. code-block:: c + + bool + bson_concat (bson_t *dst, const bson_t *src); + +Parameters +---------- + +- ``dst``: A :ref:`bson_t`. +- ``src``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_concat` function shall append the contents of ``src`` to ``dst``. + +Returns +------- + +Returns ``true`` if successful; ``false`` if the operation would overflow the maximum document size or another invalid state is detected. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_copy.txt b/source/libbson/api/bson_t/bson_copy.txt new file mode 100644 index 00000000..7e180d5f --- /dev/null +++ b/source/libbson/api/bson_t/bson_copy.txt @@ -0,0 +1,32 @@ +.. _bson_copy: + +=========== +bson_copy() +=========== + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_copy (const bson_t *bson); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_copy` function shall copy the contents of a bson document +into a new :ref:`bson_t`. + +The resulting :ref:`bson_t` should be freed with :ref:`bson_destroy`. + +Returns +------- + +A newly allocated :ref:`bson_t` that should be freed with :ref:`bson_destroy`. + diff --git a/source/libbson/api/bson_t/bson_copy_to.txt b/source/libbson/api/bson_t/bson_copy_to.txt new file mode 100644 index 00000000..294817a9 --- /dev/null +++ b/source/libbson/api/bson_t/bson_copy_to.txt @@ -0,0 +1,28 @@ +.. _bson_copy_to: + +============== +bson_copy_to() +============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_copy_to (const bson_t *src, bson_t *dst); + +Parameters +---------- + +- ``src``: A :ref:`bson_t`. +- ``dst``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_copy_to` function shall initialize ``dst`` with a copy of the contents +of ``src``. + +``dst`` *MUST* be an uninitialized :ref:`bson_t` to avoid leaking memory. + diff --git a/source/libbson/api/bson_t/bson_copy_to_excluding.txt b/source/libbson/api/bson_t/bson_copy_to_excluding.txt new file mode 100644 index 00000000..4988d902 --- /dev/null +++ b/source/libbson/api/bson_t/bson_copy_to_excluding.txt @@ -0,0 +1,43 @@ +.. _bson_copy_to_excluding: + +======================== +bson_copy_to_excluding() +======================== + +.. warning:: + .. deprecated:: 1.1.0 + + This function is deprecated and should not be used in new code. + + Please use :ref:`bson_copy_to_excluding_noinit` in new code. + +Synopsis +-------- + +.. code-block:: c + + void + bson_copy_to_excluding (const bson_t *src, + bson_t *dst, + const char *first_exclude, + ...) BSON_GNUC_NULL_TERMINATED + BSON_GNUC_DEPRECATED_FOR (bson_copy_to_excluding_noinit); + +Parameters +---------- + +- ``src``: A :ref:`bson_t`. +- ``dst``: A :ref:`bson_t`. +- ``first_exclude``: The first field name to exclude. + +Description +----------- + +The :ref:`bson_copy_to_excluding` function shall copy all fields from +``src`` to ``dst`` except those specified by the variadic, NULL terminated list +of keys starting from ``first_exclude``. + +.. warning:: + + :ref:`bson_init` is called on ``dst``. + diff --git a/source/libbson/api/bson_t/bson_copy_to_excluding_noinit.txt b/source/libbson/api/bson_t/bson_copy_to_excluding_noinit.txt new file mode 100644 index 00000000..d2426eec --- /dev/null +++ b/source/libbson/api/bson_t/bson_copy_to_excluding_noinit.txt @@ -0,0 +1,70 @@ +.. _bson_copy_to_excluding_noinit: + +=============================== +bson_copy_to_excluding_noinit() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_copy_to_excluding_noinit (const bson_t *src, + bson_t *dst, + const char *first_exclude, + ...) BSON_GNUC_NULL_TERMINATED; + +Parameters +---------- + +- ``src``: A :ref:`bson_t` +- ``dst``: A :ref:`bson_t` +- ``first_exclude``: The first field name to exclude. + +Description +----------- + +The :ref:`bson_copy_to_excluding_noinit` function shall copy all fields +from ``src`` to ``dst`` except those specified by the variadic, NULL terminated +list of keys starting from ``first_exclude``. +Works the same way as :ref:`bson_copy_to_excluding` except does **not** call +:ref:`bson_init` ``dst``. +This function should be preferred in new code over :ref:`bson_copy_to_excluding` + +.. warning:: + + This is generally not needed except in very special situations. + +Example +------- + +.. code-block:: c + + #include + + int main () + { + bson_t bson; + bson_t bson2; + char *str; + + bson_init (&bson); + bson_append_int32 (&bson, "a", 1, 1); + bson_append_int32 (&bson, "b", 1, 2); + bson_append_int32 (&bson, "c", 1, 2); + + bson_init (&bson2); + bson_copy_to_excluding_noinit (&bson, &bson2, "b", NULL); + + str = bson_as_json (&bson2, NULL); + /* Prints + * { "a" : 1, "c" : 2 } + */ + printf ("%s\n", str); + bson_free (str); + + bson_destroy (&bson); + bson_destroy (&bson2); + } + diff --git a/source/libbson/api/bson_t/bson_copy_to_excluding_noinit_va.txt b/source/libbson/api/bson_t/bson_copy_to_excluding_noinit_va.txt new file mode 100644 index 00000000..c6374237 --- /dev/null +++ b/source/libbson/api/bson_t/bson_copy_to_excluding_noinit_va.txt @@ -0,0 +1,38 @@ +.. _bson_copy_to_excluding_noinit_va: + +================================== +bson_copy_to_excluding_noinit_va() +================================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_copy_to_excluding_noinit_va (const bson_t *src, + bson_t *dst, + const char *first_exclude, + va_list args); + +Parameters +---------- + +- ``src``: A :ref:`bson_t`. +- ``dst``: A :ref:`bson_t`. +- ``first_exclude``: The first field name to exclude. +- ``args``: A va_list. + +Description +----------- + +The :ref:`bson_copy_to_excluding_noinit_va` function shall copy all fields from +``src`` to ``dst`` except those specified by ``first_exclude`` and ``args``. + +This method works the same way as :ref:`bson_copy_to_excluding_noinit`, except it +takes a va_list. This method does not call :ref:`bson_init` on ``dst``. + +.. seealso:: + + | :ref:`bson_copy_to_excluding_noinit` + diff --git a/source/libbson/api/bson_t/bson_count_keys.txt b/source/libbson/api/bson_t/bson_count_keys.txt new file mode 100644 index 00000000..8d632120 --- /dev/null +++ b/source/libbson/api/bson_t/bson_count_keys.txt @@ -0,0 +1,29 @@ +.. _bson_count_keys: + +================= +bson_count_keys() +================= + +Synopsis +-------- + +.. code-block:: c + + uint32_t + bson_count_keys (const bson_t *bson); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` + +Description +----------- + +The :ref:`bson_count_keys` function shall count the number of elements within ``bson``. + +Returns +------- + +A positive integer or zero. + diff --git a/source/libbson/api/bson_t/bson_destroy.txt b/source/libbson/api/bson_t/bson_destroy.txt new file mode 100644 index 00000000..d6cddf5f --- /dev/null +++ b/source/libbson/api/bson_t/bson_destroy.txt @@ -0,0 +1,28 @@ +.. _bson_destroy: + +============== +bson_destroy() +============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_destroy (bson_t *bson); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_destroy` function shall free an allocated :ref:`bson_t` +structure. Does nothing if ``bson`` is NULL. + +This function should always be called when you are done with a :ref:`bson_t` +unless otherwise specified. + diff --git a/source/libbson/api/bson_t/bson_destroy_with_steal.txt b/source/libbson/api/bson_t/bson_destroy_with_steal.txt new file mode 100644 index 00000000..93bb3bba --- /dev/null +++ b/source/libbson/api/bson_t/bson_destroy_with_steal.txt @@ -0,0 +1,40 @@ +.. _bson_destroy_with_steal: + +========================= +bson_destroy_with_steal() +========================= + +Synopsis +-------- + +.. code-block:: c + + uint8_t * + bson_destroy_with_steal (bson_t *bson, bool steal, uint32_t *length); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``steal``: A bool indicating if the underlying buffer should be stolen. +- ``length``: A location for storing the resulting buffer length. + +Description +----------- + +The :ref:`bson_destroy_with_steal` function shall destroy a :ref:`bson_t` structure but return the underlying +buffer instead of freeing it. If steal is false, this is equivalent to calling bson_destroy(). It is a +programming error to call this function on a :ref:`bson_t` that is not a top-level :ref:`bson_t`, such as those +initialized with :ref:`bson_append_document_begin`, :ref:`bson_append_array_begin`, and :ref:`bson_writer_begin`. + +Returns +------- + +:ref:`bson_destroy_with_steal` shall return a buffer containing the contents of the :ref:`bson_t` if ``steal`` is +non-zero. This should be freed with :ref:`bson_free` when no longer in use. ``length`` will be set to the length of the +bson document if non-NULL. + +.. seealso:: + + | :ref:`bson_steal`, a higher-level function that efficiently transfers the contents of one :ref:`bson_t` to another. + diff --git a/source/libbson/api/bson_t/bson_equal.txt b/source/libbson/api/bson_t/bson_equal.txt new file mode 100644 index 00000000..b4c9fbe5 --- /dev/null +++ b/source/libbson/api/bson_t/bson_equal.txt @@ -0,0 +1,30 @@ +.. _bson_equal: + +============ +bson_equal() +============ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_equal (const bson_t *bson, const bson_t *other); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``other``: A :ref:`bson_t` + +Description +----------- + +The :ref:`bson_equal` function shall return true if both documents are equal. + +Returns +------- + +True if both documents are equal. + diff --git a/source/libbson/api/bson_t/bson_get_data.txt b/source/libbson/api/bson_t/bson_get_data.txt new file mode 100644 index 00000000..89c32d4b --- /dev/null +++ b/source/libbson/api/bson_t/bson_get_data.txt @@ -0,0 +1,31 @@ +.. _bson_get_data: + +=============== +bson_get_data() +=============== + +Synopsis +-------- + +.. code-block:: c + + const uint8_t * + bson_get_data (const bson_t *bson); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_get_data` function shall return the raw buffer of a bson document. +This can be used in conjunction with the ``len`` property of a :ref:`bson_t` if you +want to copy the raw buffer around. + +Returns +------- + +A buffer which should not be modified or freed. + diff --git a/source/libbson/api/bson_t/bson_has_field.txt b/source/libbson/api/bson_t/bson_has_field.txt new file mode 100644 index 00000000..beb2dace --- /dev/null +++ b/source/libbson/api/bson_t/bson_has_field.txt @@ -0,0 +1,30 @@ +.. _bson_has_field: + +================ +bson_has_field() +================ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_has_field (const bson_t *bson, const char *key); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``key``: A string containing the name of the field to check for. + +Description +----------- + +Checks to see if key contains an element named ``key``. This also accepts "dotkey" notation such as "a.b.c.d". + +Returns +------- + +True if ``key`` was found within ``bson``; otherwise false. + diff --git a/source/libbson/api/bson_t/bson_init.txt b/source/libbson/api/bson_t/bson_init.txt new file mode 100644 index 00000000..ee1cda1a --- /dev/null +++ b/source/libbson/api/bson_t/bson_init.txt @@ -0,0 +1,26 @@ +.. _bson_init: + +=========== +bson_init() +=========== + +Synopsis +-------- + +.. code-block:: c + + void + bson_init (bson_t *b); + +Parameters +---------- + +- ``b``: A :ref:`bson_t`. + +Description +----------- + +The :ref:`bson_init` function shall initialize a :ref:`bson_t` that is placed on +the stack. This is equivalent to initializing a :ref:`bson_t` to ``BSON_INITIALIZER``. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_init_from_json.txt b/source/libbson/api/bson_t/bson_init_from_json.txt new file mode 100644 index 00000000..f61aba1b --- /dev/null +++ b/source/libbson/api/bson_t/bson_init_from_json.txt @@ -0,0 +1,62 @@ +.. _bson_init_from_json: + +===================== +bson_init_from_json() +===================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_init_from_json (bson_t *bson, + const char *data, + ssize_t len, + bson_error_t *error); + +Parameters +---------- + +- ``bson``: Pointer to an uninitialized :ref:`bson_t` +- ``data``: A UTF-8 encoded string containing valid JSON. +- ``len``: The length of ``data`` in bytes excluding a trailing ``\0`` or -1 to determine + the length with ``strlen()``. +- ``error``: An optional location for a :ref:`bson_error_t` + +Description +----------- + +The ``bson_init_from_json()`` function will initialize a new :ref:`bson_t` parsing the +JSON found in ``data``. Only a single JSON object may exist in ``data`` or an error will be +set and false returned. + +``data`` should be in `MongoDB Extended JSON `_ +format. + +Deprecated behavior +------------------- + +If there are multiple comma-separated JSONs in ``data``, the keys from all JSONs are merged in +the returned BSON. For example, ``{"a": 1},{"b": 2}`` is parsed as ``{"a": 1, "b": 2}``. + +If the first character encountered after the last valid +JSON object is ``{``, all following characters are ignored and no error is set. +Otherwise, an error will be set and NULL returned. + +This deprecated behavior is subject to change in a future release. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if valid JSON was parsed, otherwise ``false`` and ``error`` is set. On success, +``bson`` is initialized and must be freed with :ref:`bson_destroy` otherwise ``bson`` is invalid. + +.. include:: /libbson/includes/seealso/create-bson.rst + +.. include:: /libbson/includes/seealso/json.rst diff --git a/source/libbson/api/bson_t/bson_init_static.txt b/source/libbson/api/bson_t/bson_init_static.txt new file mode 100644 index 00000000..158e468f --- /dev/null +++ b/source/libbson/api/bson_t/bson_init_static.txt @@ -0,0 +1,38 @@ +.. _bson_init_static: + +================== +bson_init_static() +================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_init_static (bson_t *b, const uint8_t *data, size_t length); + +Parameters +---------- + +- ``b``: A :ref:`bson_t` +- ``data``: A buffer to initialize with. +- ``length``: The length of ``data`` in bytes. + +Description +----------- + +The :ref:`bson_init_static` function shall initialize a read-only :ref:`bson_t` +on the stack using the data provided. No copies of the data will be made and therefore must +remain valid for the lifetime of the :ref:`bson_t`. + +The resulting ``bson_t`` has internal references ands therefore must not be copied to avoid dangling +pointers in the copy. + +Returns +------- + +Returns ``true`` if :ref:`bson_t` was successfully initialized, otherwise ``false``. The +function can fail if ``data`` or ``length`` are invalid. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_json_mode_t.txt b/source/libbson/api/bson_t/bson_json_mode_t.txt new file mode 100644 index 00000000..7c6129e8 --- /dev/null +++ b/source/libbson/api/bson_t/bson_json_mode_t.txt @@ -0,0 +1,32 @@ +.. _bson_json_mode_t: + +================ +bson_json_mode_t +================ + +BSON JSON encoding mode enumeration + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef enum { + BSON_JSON_MODE_LEGACY, + BSON_JSON_MODE_CANONICAL, + BSON_JSON_MODE_RELAXED, + } bson_json_mode_t; + +Description +----------- + +The :ref:`bson_json_mode_t` enumeration contains all available modes for encoding BSON +into `MongoDB Extended JSON`_. + +.. seealso:: + + | :ref:`bson_as_json_with_opts` + +.. _MongoDB Extended JSON: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst diff --git a/source/libbson/api/bson_t/bson_json_opts_destroy.txt b/source/libbson/api/bson_t/bson_json_opts_destroy.txt new file mode 100644 index 00000000..956ad790 --- /dev/null +++ b/source/libbson/api/bson_t/bson_json_opts_destroy.txt @@ -0,0 +1,23 @@ +.. _bson_json_opts_destroy: + +======================== +bson_json_opts_destroy() +======================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_json_opts_destroy (bson_json_opts_t *opts); + +Parameters +---------- + +- ``opts``: A :ref:`bson_json_opts_t`. + +Description +----------- + +Destroys and releases all resources associated with ``opts``. Does nothing if ``opts`` is NULL. diff --git a/source/libbson/api/bson_t/bson_json_opts_new.txt b/source/libbson/api/bson_t/bson_json_opts_new.txt new file mode 100644 index 00000000..ac702164 --- /dev/null +++ b/source/libbson/api/bson_t/bson_json_opts_new.txt @@ -0,0 +1,36 @@ +.. _bson_json_opts_new: + +==================== +bson_json_opts_new() +==================== + +Synopsis +-------- + +.. code-block:: c + + bson_json_opts_t * + bson_json_opts_new (bson_json_mode_t mode, int32_t max_len); + +Parameters +---------- + +- ``mode``: A bson_json_mode_t. +- ``max_len``: An int32_t. + +Description +----------- + +The :ref:`bson_json_opts_new` function shall create a new :ref:`bson_json_opts_t` using +the mode and length supplied. The ``mode`` member is a :ref:`bson_json_mode_t` defining the +encoding mode. + +The ``max_len`` member holds a maximum length for the resulting JSON string. Encoding will stop +once the serialised string has reached this length. To encode the full BSON document, +``BSON_MAX_LEN_UNLIMITED`` can be used. + +Returns +------- + +A newly allocated :ref:`bson_json_opts_t`. + diff --git a/source/libbson/api/bson_t/bson_json_opts_set_outermost_array.txt b/source/libbson/api/bson_t/bson_json_opts_set_outermost_array.txt new file mode 100644 index 00000000..d295cbe4 --- /dev/null +++ b/source/libbson/api/bson_t/bson_json_opts_set_outermost_array.txt @@ -0,0 +1,26 @@ +.. _bson_json_opts_set_outermost_array: + +==================================== +bson_json_opts_set_outermost_array() +==================================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_json_opts_set_outermost_array (bson_json_opts_t *opts, bool is_outermost_array); + +Parameters +---------- + +- ``opts``: A :ref:`bson_json_opts_t` +- ``is_outermost_array``: A value determining what we want to set the is_outermost_array +- variable to. + +Description +----------- + +The :ref:`bson_json_opts_set_outermost_array` function shall set the ``is_outermost_array`` +variable on the :ref:`bson_json_opts_t` parameter using the boolean provided. diff --git a/source/libbson/api/bson_t/bson_json_opts_t.txt b/source/libbson/api/bson_t/bson_json_opts_t.txt new file mode 100644 index 00000000..396f3c80 --- /dev/null +++ b/source/libbson/api/bson_t/bson_json_opts_t.txt @@ -0,0 +1,57 @@ +.. _bson_json_opts_t: + +================ +bson_json_opts_t +================ + +BSON to JSON encoding options + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct _bson_json_opts_t bson_json_opts_t; + + bson_json_opts_t * + bson_json_opts_new (bson_json_mode_t mode, int32_t max_len); + + void + bson_json_opts_destroy (bson_json_opts_t *opts); + + +Description +----------- + +The :ref:`bson_json_opts_t` structure contains options for encoding BSON into +`MongoDB Extended JSON`_. + +The ``mode`` member is a :ref:`bson_json_mode_t` defining the encoding mode. + +The ``max_len`` member holds a maximum length for the resulting JSON string. Encoding will +stop once the serialised string has reached this length. To encode the full BSON document, +``BSON_MAX_LEN_UNLIMITED`` can be used. + +.. seealso:: + + | :ref:`bson_as_json_with_opts` + +.. _MongoDB Extended JSON: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst + + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_t/bson_json_opts_new + /libbson/api/bson_t/bson_json_opts_destroy + /libbson/api/bson_t/bson_json_opts_set_outermost_array + +- :ref:`bson_json_opts_new` +- :ref:`bson_json_opts_destroy` +- :ref:`bson_json_opts_set_outermost_array` \ No newline at end of file diff --git a/source/libbson/api/bson_t/bson_new.txt b/source/libbson/api/bson_t/bson_new.txt new file mode 100644 index 00000000..e30a5b42 --- /dev/null +++ b/source/libbson/api/bson_t/bson_new.txt @@ -0,0 +1,26 @@ +.. _bson_new: + +========== +bson_new() +========== + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_new (void); + +Description +----------- + +The :ref:`bson_new` function shall create a new :ref:`bson_t` structure on the heap. +It should be freed with :ref:`bson_destroy` when it is no longer in use. + +Returns +------- + +A newly allocated :ref:`bson_t` that should be freed with :ref:`bson_destroy`. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_new_from_buffer.txt b/source/libbson/api/bson_t/bson_new_from_buffer.txt new file mode 100644 index 00000000..8b632c87 --- /dev/null +++ b/source/libbson/api/bson_t/bson_new_from_buffer.txt @@ -0,0 +1,43 @@ +.. _bson_new_from_buffer: + +====================== +bson_new_from_buffer() +====================== + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_new_from_buffer (uint8_t **buf, + size_t *buf_len, + bson_realloc_func realloc_func, + void *realloc_func_ctx); + +Parameters +---------- + +- ``buf``: An out-pointer to a buffer containing a serialized BSON document, or to NULL. +- ``buf_len``: An out-pointer to the length of the buffer in bytes. +- ``realloc_func``: Optional :ref:`bson_realloc_func` for reallocating the buffer. +- ``realloc_func_ctx``: Optional pointer that will be passed as ``ctx`` to ``realloc_func``. + +Description +----------- + +Creates a new :ref:`bson_t` using the data provided. + +The ``realloc_func``, if provided, is called to resize ``buf`` if the document is later expanded, +for example by a call to one of the ``bson_append`` functions. + +If ``*buf`` is initially NULL then it is allocated, using ``realloc_func`` or the default allocator, +and initialized with an empty BSON document, and ``*buf_len`` is set to 5, the size of an empty +document. + +Returns +------- + +A newly-allocated :ref:`bson_t` on success, or NULL. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_new_from_data.txt b/source/libbson/api/bson_t/bson_new_from_data.txt new file mode 100644 index 00000000..1f33e1f6 --- /dev/null +++ b/source/libbson/api/bson_t/bson_new_from_data.txt @@ -0,0 +1,33 @@ +.. _bson_new_from_data: + +==================== +bson_new_from_data() +==================== + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_new_from_data (const uint8_t *data, size_t length); + +Parameters +---------- + +- ``data``: A BSON encoded document buffer. +- ``length``: The length of ``data`` in bytes. + +Description +----------- + +The :ref:`bson_new_from_data` function shall create a new :ref:`bson_t` on the +heap and copy the contents of ``data``. This may be helpful when working with language +bindings but is generally expected to be slower. + +Returns +------- + +A newly allocated :ref:`bson_t` if successful, otherwise NULL. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_new_from_json.txt b/source/libbson/api/bson_t/bson_new_from_json.txt new file mode 100644 index 00000000..34f11c4b --- /dev/null +++ b/source/libbson/api/bson_t/bson_new_from_json.txt @@ -0,0 +1,48 @@ +.. _bson_new_from_json: + +==================== +bson_new_from_json() +==================== + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_new_from_json (const uint8_t *data, ssize_t len, bson_error_t *error); + +Parameters +---------- + +- ``data``: A UTF-8 encoded string containing valid JSON. +- ``len``: The length of ``data`` in bytes excluding a trailing ``\0`` or -1 to determine + the length with ``strlen()``. +- ``error``: An optional location for a :ref:`bson_error_t`. + +Description +----------- + +The ``bson_new_from_json()`` function allocates and initializes a new :ref:`bson_t` +by parsing the JSON found in ``data``. Only a single JSON object may exist in ``data`` +or an error will be set and NULL returned. + +Deprecated behavior: If there are multiple comma-separated JSONs in ``data``, the keys +from all JSONs are merged in the returned BSON. For example, ``{"a": 1},{"b": 2}`` is parsed +as ``{"a": 1, "b": 2}``. If the first character encountered after the last valid JSON object +is ``{``, all following characters are ignored and no error is set. Otherwise, an error will +be set and NULL returned. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +A newly allocated :ref:`bson_t` if successful, otherwise NULL and ``error`` is set. + +.. include:: /libbson/includes/seealso/create-bson.rst + +.. include:: /libbson/includes/seealso/json.rst diff --git a/source/libbson/api/bson_t/bson_reinit.txt b/source/libbson/api/bson_t/bson_reinit.txt new file mode 100644 index 00000000..6059086c --- /dev/null +++ b/source/libbson/api/bson_t/bson_reinit.txt @@ -0,0 +1,29 @@ +.. _bson_reinit: + +============= +bson_reinit() +============= + +Synopsis +-------- + +.. code-block:: c + + void + bson_reinit (bson_t *b); + +Parameters +---------- + +- ``b``: A :ref:`bson_t`. + +Description +----------- + +Reinitializes a :ref:`bson_t`. + +If the :ref:`bson_t` structure contains a malloc()'d buffer, it may be reused. To be +certain that any buffer is freed, always call :ref:`bson_destroy` on any :ref:`bson_t` +structure, whether initialized or reinitialized, after its final use. + +.. include:: /libbson/includes/seealso/create-bson.rst \ No newline at end of file diff --git a/source/libbson/api/bson_t/bson_reserve_buffer.txt b/source/libbson/api/bson_t/bson_reserve_buffer.txt new file mode 100644 index 00000000..79cb7b33 --- /dev/null +++ b/source/libbson/api/bson_t/bson_reserve_buffer.txt @@ -0,0 +1,116 @@ +.. _bson_reserve_buffer: + +===================== +bson_reserve_buffer() +===================== + +Synopsis +-------- + +.. code-block:: c + + uint8_t * + bson_reserve_buffer (bson_t *bson, uint32_t size); + +Parameters +---------- + +- ``bson``: An initialized :ref:`bson_t`. +- ``size``: The length in bytes of the new buffer. + +Description +----------- + +Grow the internal buffer of ``bson`` to ``size`` and set the document length to ``size``. +Useful for eliminating copies when reading BSON bytes from a stream. + +First, initialize ``bson`` with :ref:`bson_init` or :ref:`bson_new`, then call this +function. After it returns, the length of ``bson`` is set to ``size`` but its contents are +uninitialized memory: you must fill the contents with a BSON document of the correct length +before any other operations. + +The document must be freed with :ref:`bson_destroy`. + +Returns +------- + +A pointer to the internal buffer, which is at least ``size`` bytes, or NULL if the space +could not be allocated. + +Example +------- + +Use ``bson_reserve_buffer`` to write a function that takes a :ref:`bson_t` pointer and +reads a file into it directly: + +.. code-block:: c + + #include + #include + + bool + read_into (bson_t *bson, FILE *fp) + { + uint8_t *buffer; + long size; + + if (fseek (fp, 0L, SEEK_END) < 0) { + perror ("Couldn't get file size"); + return 1; + } + + size = ftell (fp); + if (size == EOF) { + perror ("Couldn't get file size"); + return 1; + } + + if (size > INT32_MAX) { + fprintf (stderr, "File too large\n"); + return 1; + } + + /* reserve buffer space - bson is temporarily invalid */ + buffer = bson_reserve_buffer (bson, (uint32_t) size); + if (!buffer) { + fprintf (stderr, "Couldn't reserve %ld bytes", size); + return false; + } + + /* read file directly into the buffer */ + rewind (fp); + if (fread ((void *) buffer, 1, (size_t) size, fp) < (size_t) size) { + perror ("Couldn't read file"); + return false; + } + + return true; + } + + int + main () + { + FILE *fp; + char *json; + + /* stack-allocated, initialized bson_t */ + bson_t bson = BSON_INITIALIZER; + + if (!(fp = fopen ("document.bson", "rb"))) { + perror ("Couldn't read file"); + return 1; + } + + read_into (&bson, fp); + fclose (fp); + + json = bson_as_canonical_extended_json (&bson, NULL); + printf ("%s\n", json); + + bson_free (json); + bson_destroy (&bson); + + return 0; + } + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_sized_new.txt b/source/libbson/api/bson_t/bson_sized_new.txt new file mode 100644 index 00000000..4d1719b7 --- /dev/null +++ b/source/libbson/api/bson_t/bson_sized_new.txt @@ -0,0 +1,32 @@ +.. _bson_sized_new: + +================ +bson_sized_new() +================ + +Synopsis +-------- + +.. code-block:: c + + bson_t * + bson_sized_new (size_t size); + +Parameters +---------- + +- ``size``: The size to pre-allocate for the underlying buffer. + +Description +----------- + +The :ref:`bson_sized_new` function shall create a new :ref:`bson_t` on the heap +with a preallocated buffer. This is useful if you have a good idea of the size of the resulting +document. + +Returns +------- + +A newly allocated :ref:`bson_t` that should be freed with :ref:`bson_destroy`. + +.. include:: /libbson/includes/seealso/create-bson.rst diff --git a/source/libbson/api/bson_t/bson_steal.txt b/source/libbson/api/bson_t/bson_steal.txt new file mode 100644 index 00000000..93933302 --- /dev/null +++ b/source/libbson/api/bson_t/bson_steal.txt @@ -0,0 +1,86 @@ +.. _bson_steal: + +============ +bson_steal() +============ + +Synopsis +-------- + +.. code-block:: c + + bool + bson_steal (bson_t *dst, bson_t *src); + +Parameters +---------- + +- ``dst``: An uninitialized :ref:`bson_t` +- ``src``: A :ref:`bson_t` + +Description +----------- + +Efficiently transfer the contents of ``src`` to ``dst`` and destroy ``src``. + +Before calling this function, ``src`` must be initialized and ``dst`` must be uninitialized. +After this function returns successfully, ``src`` is destroyed, and ``dst`` is initialized +and must be freed with :ref:`bson_destroy`. + +For example, if you have a higher-level structure that wraps a :ref:`bson_t`, use ``bson_steal`` +to transfer BSON data into it: + +.. code-block:: c + + typedef struct { + bson_t bson; + } bson_wrapper_t; + + + bson_wrapper_t * + wrap_bson (bson_t *b) + { + bson_wrapper_t *wrapper = bson_malloc (sizeof (bson_wrapper_t)); + + if (bson_steal (&wrapper->bson, b)) { + return wrapper; + } + + bson_free (wrapper); + return NULL; + } + + + void + bson_wrapper_destroy (bson_wrapper_t *wrapper) + { + bson_destroy (&wrapper->bson); + bson_free (wrapper); + } + + + int + main (int argc, char *argv[]) + { + bson_t bson = BSON_INITIALIZER; + bson_wrapper_t *wrapper; + + BSON_APPEND_UTF8 (&bson, "key", "value"); + + /* now "bson" is destroyed */ + wrapper = wrap_bson (&bson); + + /* clean up */ + bson_wrapper_destroy (wrapper); + } + +Returns +------- + +Returns ``true`` if ``src`` was successfully moved to ``dst``, ``false`` if ``src`` is invalid, +or was statically initialized, or another error occurred. + +.. seealso:: + + | :ref:`bson_destroy_with_steal` lower-level function that returns the raw contents of a :ref:`bson_t`. + diff --git a/source/libbson/api/bson_t/bson_validate.txt b/source/libbson/api/bson_t/bson_validate.txt new file mode 100644 index 00000000..3cb84538 --- /dev/null +++ b/source/libbson/api/bson_t/bson_validate.txt @@ -0,0 +1,42 @@ +.. _bson_validate: + +=============== +bson_validate() +=============== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_validate (const bson_t *bson, bson_validate_flags_t flags, size_t *offset); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t` +- ``flags``: A bitwise-or of all desired :ref:`bson_validate_with_error`. +- ``offset``: A location for the offset within ``bson`` where the error occurred. + +Description +----------- + +Validates a BSON document by walking through the document and inspecting the keys and values for valid +content. + +You can modify how the validation occurs through the use of the ``flags`` parameter, see +:ref:`bson_validate_with_error` for details. + +Returns +------- + +Returns true if ``bson`` is valid; otherwise false and ``offset`` is set to the byte offset where the +error was detected. + +.. seealso:: + + | :ref:`bson_validate_with_error` + + | :ref:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`. + diff --git a/source/libbson/api/bson_t/bson_validate_with_error.txt b/source/libbson/api/bson_t/bson_validate_with_error.txt new file mode 100644 index 00000000..6bfbda1b --- /dev/null +++ b/source/libbson/api/bson_t/bson_validate_with_error.txt @@ -0,0 +1,65 @@ +.. _bson_validate_with_error: + +========================== +bson_validate_with_error() +========================== + +Synopsis +-------- + +.. code-block:: c + + typedef enum { + BSON_VALIDATE_NONE = 0, + BSON_VALIDATE_UTF8 = (1 << 0), + BSON_VALIDATE_DOLLAR_KEYS = (1 << 1), + BSON_VALIDATE_DOT_KEYS = (1 << 2), + BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3), + BSON_VALIDATE_EMPTY_KEYS = (1 << 4), + } bson_validate_flags_t; + + bool + bson_validate_with_error (const bson_t *bson, + bson_validate_flags_t flags, + bson_error_t *error); + +Parameters +---------- + +- ``bson``: A :ref:`bson_t`. +- ``flags``: A bitwise-or of all desired validation flags. +- ``error``: Optional :ref:`bson_error_t`. + +Description +----------- + +Validates a BSON document by walking through the document and inspecting the keys and +values for valid content. + +You can modify how the validation occurs through the use of the ``flags`` parameter. A +description of their effect is below. + +- ``BSON_VALIDATE_NONE`` Basic validation of BSON length and structure. +- ``BSON_VALIDATE_UTF8`` All keys and string values are checked for invalid UTF-8. +- ``BSON_VALIDATE_UTF8_ALLOW_NULL`` String values are allowed to have embedded NULL bytes. +- ``BSON_VALIDATE_DOLLAR_KEYS`` Prohibit keys that start with ``$`` outside of a "DBRef" subdocument. +- ``BSON_VALIDATE_DOT_KEYS`` Prohibit keys that contain ``.`` anywhere in the string. +- ``BSON_VALIDATE_EMPTY_KEYS`` Prohibit zero-length keys. + +Returns +------- + +Returns true if ``bson`` is valid; otherwise false and ``error`` is filled out. + +The :ref:`bson_error_t` domain is set to ``BSON_ERROR_INVALID``. Its code is set to one of the +``bson_validate_flags_t`` flags indicating which validation failed; for example, if a key contains +invalid UTF-8, then the code is set to ``BSON_VALIDATE_UTF8``, but if the basic structure of the +BSON document is corrupt, the code is set to ``BSON_VALIDATE_NONE``. The error message is filled out, +and gives more detail if possible. + +.. seealso:: + + | :ref:`bson_validate`. + + | :ref:`bson_visitor_t` can be used for custom validation, :ref:`example_custom_validation`. + diff --git a/source/libbson/api/bson_type_t.txt b/source/libbson/api/bson_type_t.txt new file mode 100644 index 00000000..a837890a --- /dev/null +++ b/source/libbson/api/bson_type_t.txt @@ -0,0 +1,58 @@ +.. _bson_type_t: + +=========== +bson_type_t +=========== + +BSON Type Enumeration + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef enum { + BSON_TYPE_EOD = 0x00, + BSON_TYPE_DOUBLE = 0x01, + BSON_TYPE_UTF8 = 0x02, + BSON_TYPE_DOCUMENT = 0x03, + BSON_TYPE_ARRAY = 0x04, + BSON_TYPE_BINARY = 0x05, + BSON_TYPE_UNDEFINED = 0x06, + BSON_TYPE_OID = 0x07, + BSON_TYPE_BOOL = 0x08, + BSON_TYPE_DATE_TIME = 0x09, + BSON_TYPE_NULL = 0x0A, + BSON_TYPE_REGEX = 0x0B, + BSON_TYPE_DBPOINTER = 0x0C, + BSON_TYPE_CODE = 0x0D, + BSON_TYPE_SYMBOL = 0x0E, + BSON_TYPE_CODEWSCOPE = 0x0F, + BSON_TYPE_INT32 = 0x10, + BSON_TYPE_TIMESTAMP = 0x11, + BSON_TYPE_INT64 = 0x12, + BSON_TYPE_DECIMAL128 = 0x13, + BSON_TYPE_MAXKEY = 0x7F, + BSON_TYPE_MINKEY = 0xFF, + } bson_type_t; + +Description +----------- + +The :ref:`bson_type_t` enumeration contains all of the types from the `BSON Specification +`_. It can be used to determine the type of a field at runtime. + +Example +------- + +.. code-block:: c + + bson_iter_t iter; + + if (bson_iter_init_find (&iter, doc, "foo") && + (BSON_TYPE_INT32 == bson_iter_type (&iter))) { + printf ("'foo' is an int32.\n"); + } + diff --git a/source/libbson/api/bson_unichar_t.txt b/source/libbson/api/bson_unichar_t.txt new file mode 100644 index 00000000..bc705ff5 --- /dev/null +++ b/source/libbson/api/bson_unichar_t.txt @@ -0,0 +1,38 @@ +.. _bson_unichar_t: + +============== +bson_unichar_t +============== + +Unicode Character Abstraction + +Synopsis +-------- + +.. code-block:: c + + typedef uint32_t bson_unichar_t; + +Description +----------- + +:ref:`bson_unichar_t` provides an abstraction on a single unicode character. It is the 32-bit +representation of a character. As UTF-8 can contain multi-byte characters, this should be used +when iterating through UTF-8 text. + +Example +------- + +.. code-block:: c + + static void + print_each_char (const char *str) + { + bson_unichar_t c; + + for (; *str; str = bson_utf8_next_char (str)) { + c = bson_utf8_get_char (str); + printf ("The numberic value is %u.\n", (unsigned) c); + } + } + diff --git a/source/libbson/api/bson_value_t.txt b/source/libbson/api/bson_value_t.txt new file mode 100644 index 00000000..d9507c19 --- /dev/null +++ b/source/libbson/api/bson_value_t.txt @@ -0,0 +1,100 @@ +.. _bson_value_t: + +============ +bson_value_t +============ + +BSON Boxed Container Type + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct _bson_value_t { + bson_type_t value_type; + union { + bson_oid_t v_oid; + int64_t v_int64; + int32_t v_int32; + int8_t v_int8; + double v_double; + bool v_bool; + int64_t v_datetime; + struct { + uint32_t timestamp; + uint32_t increment; + } v_timestamp; + struct { + uint32_t len; + char *str; + } v_utf8; + struct { + uint32_t data_len; + uint8_t *data; + } v_doc; + struct { + uint32_t data_len; + uint8_t *data; + bson_subtype_t subtype; + } v_binary; + struct { + char *regex; + char *options; + } v_regex; + struct { + char *collection; + uint32_t collection_len; + bson_oid_t oid; + } v_dbpointer; + struct { + uint32_t code_len; + char *code; + } v_code; + struct { + uint32_t code_len; + char *code; + uint32_t scope_len; + uint8_t *scope_data; + } v_codewscope; + struct { + uint32_t len; + char *symbol; + } v_symbol; + bson_decimal128_t v_decimal128; + } value; + } bson_value_t; + +Description +----------- + +The :ref:`bson_value_t` structure is a boxed type for encapsulating a runtime determined type. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_value_t/bson_value_copy + /libbson/api/bson_value_t/bson_value_destroy + +- :ref:`bson_value_copy` +- :ref:`bson_value_destroy` + +Example +------- + +.. code-block:: c + + const bson_value_t *value; + + value = bson_iter_value (&iter); + + if (value->value_type == BSON_TYPE_INT32) { + printf ("%d\n", value->value.v_int32); + } + diff --git a/source/libbson/api/bson_value_t/bson_value_copy.txt b/source/libbson/api/bson_value_t/bson_value_copy.txt new file mode 100644 index 00000000..b394af8f --- /dev/null +++ b/source/libbson/api/bson_value_t/bson_value_copy.txt @@ -0,0 +1,26 @@ +.. _bson_value_copy: + +================= +bson_value_copy() +================= + +Synopsis +-------- + +.. code-block:: c + + void + bson_value_copy (const bson_value_t *src, bson_value_t *dst); + +Parameters +---------- + +- ``src``: A :ref:`bson_value_t` to copy from. +- ``dst``: A :ref:`bson_value_t` to copy into. + +Description +----------- + +This function will copy the boxed content in ``src`` into ``dst``. ``dst`` must be freed +with :ref:`bson_value_destroy` when no longer in use. + diff --git a/source/libbson/api/bson_value_t/bson_value_destroy.txt b/source/libbson/api/bson_value_t/bson_value_destroy.txt new file mode 100644 index 00000000..48c86db1 --- /dev/null +++ b/source/libbson/api/bson_value_t/bson_value_destroy.txt @@ -0,0 +1,23 @@ +.. _bson_value_destroy: + +==================== +bson_value_destroy() +==================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_value_destroy (bson_value_t *value); + +Parameters +---------- + +- ``value``: A :ref:`bson_value_t`. + +Description +----------- + +Releases any resources associated with ``value``. Does nothing if ``value`` is NULL. diff --git a/source/libbson/api/bson_visitor_t.txt b/source/libbson/api/bson_visitor_t.txt new file mode 100644 index 00000000..abfc8397 --- /dev/null +++ b/source/libbson/api/bson_visitor_t.txt @@ -0,0 +1,231 @@ +.. _bson_visitor_t: + +============== +bson_visitor_t +============== + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct { + /* run before / after descending into a document */ + bool (*visit_before) (const bson_iter_t *iter, const char *key, void *data); + bool (*visit_after) (const bson_iter_t *iter, const char *key, void *data); + /* corrupt BSON, or unsupported type and visit_unsupported_type not set */ + void (*visit_corrupt) (const bson_iter_t *iter, void *data); + /* normal bson field callbacks */ + bool (*visit_double) (const bson_iter_t *iter, + const char *key, + double v_double, + void *data); + bool (*visit_utf8) (const bson_iter_t *iter, + const char *key, + size_t v_utf8_len, + const char *v_utf8, + void *data); + bool (*visit_document) (const bson_iter_t *iter, + const char *key, + const bson_t *v_document, + void *data); + bool (*visit_array) (const bson_iter_t *iter, + const char *key, + const bson_t *v_array, + void *data); + bool (*visit_binary) (const bson_iter_t *iter, + const char *key, + bson_subtype_t v_subtype, + size_t v_binary_len, + const uint8_t *v_binary, + void *data); + /* normal field with deprecated "Undefined" BSON type */ + bool (*visit_undefined) (const bson_iter_t *iter, + const char *key, + void *data); + bool (*visit_oid) (const bson_iter_t *iter, + const char *key, + const bson_oid_t *v_oid, + void *data); + bool (*visit_bool) (const bson_iter_t *iter, + const char *key, + bool v_bool, + void *data); + bool (*visit_date_time) (const bson_iter_t *iter, + const char *key, + int64_t msec_since_epoch, + void *data); + bool (*visit_null) (const bson_iter_t *iter, const char *key, void *data); + bool (*visit_regex) (const bson_iter_t *iter, + const char *key, + const char *v_regex, + const char *v_options, + void *data); + bool (*visit_dbpointer) (const bson_iter_t *iter, + const char *key, + size_t v_collection_len, + const char *v_collection, + const bson_oid_t *v_oid, + void *data); + bool (*visit_code) (const bson_iter_t *iter, + const char *key, + size_t v_code_len, + const char *v_code, + void *data); + bool (*visit_symbol) (const bson_iter_t *iter, + const char *key, + size_t v_symbol_len, + const char *v_symbol, + void *data); + bool (*visit_codewscope) (const bson_iter_t *iter, + const char *key, + size_t v_code_len, + const char *v_code, + const bson_t *v_scope, + void *data); + bool (*visit_int32) (const bson_iter_t *iter, + const char *key, + int32_t v_int32, + void *data); + bool (*visit_timestamp) (const bson_iter_t *iter, + const char *key, + uint32_t v_timestamp, + uint32_t v_increment, + void *data); + bool (*visit_int64) (const bson_iter_t *iter, + const char *key, + int64_t v_int64, + void *data); + bool (*visit_maxkey) (const bson_iter_t *iter, const char *key, void *data); + bool (*visit_minkey) (const bson_iter_t *iter, const char *key, void *data); + /* if set, called instead of visit_corrupt when an apparently valid BSON + * includes an unrecognized field type (reading future version of BSON) */ + void (*visit_unsupported_type) (const bson_iter_t *iter, + const char *key, + uint32_t type_code, + void *data); + bool (*visit_decimal128) (const bson_iter_t *iter, + const char *key, + const bson_decimal128_t *v_decimal128, + void *data); + + void *padding[7]; + } bson_visitor_t bson_visitor_t; + +Description +----------- + +The :ref:`bson_visitor_t` structure provides a series of callbacks that can be called +while iterating a BSON document. This may simplify the conversion of a :ref:`bson_t` +to a higher level language structure. + +If the optional callback ``visit_unsupported_type`` is set, it is called instead of ``visit_corrupt`` +in the specific case of an unrecognized field type. (Parsing is aborted in either case.) Use this +callback to report an error like "unrecognized type" instead of simply "corrupt BSON". This future-proofs +code that may use an older version of libbson to parse future BSON formats. + +Basic Example +------------- + +.. code-block:: c + + #include + #include + + static bool + my_visit_before (const bson_iter_t *iter, const char *key, void *data) + { + int *count = (int *) data; + + (*count)++; + + /* returning true stops further iteration of the document */ + + return false; + } + + static void + count_fields (bson_t *doc) + { + bson_visitor_t visitor = {0}; + bson_iter_t iter; + int count = 0; + + visitor.visit_before = my_visit_before; + + if (bson_iter_init (&iter, doc)) { + bson_iter_visit_all (&iter, &visitor, &count); + } + + printf ("Found %d fields.\n", count); + } + +The example below demonstrates how to set your own callbacks to provide information about +the location of corrupt or unsupported BSON document entries. + +Example Corruption Check +------------------------ + +.. code-block:: c + + #include + #include + + typedef struct { + ssize_t *err_offset; + } my_state_t; + + static void + my_visit_corrupt (const bson_iter_t *iter, void *data) + { + *(((my_state_t *) data)->err_offset) = iter->off; + } + + static void + my_visit_unsupported_type (const bson_iter_t *iter, + const char *key, + uint32_t type_code, + void *data) + { + *(((my_state_t *) data)->err_offset) = iter->off; + } + + static void + find_error_location (bson_t *doc) + { + bson_visitor_t visitors = {0}; + bson_iter_t iter; + my_state_t state; + ssize_t err_offset = -1; + + visitors.visit_corrupt = my_visit_corrupt; + visitors.visit_unsupported_type = my_visit_unsupported_type; + /* provide additional visitors as needed based on your requirements */ + state.err_offset = &err_offset; + + if (!bson_iter_init (&iter, doc)) { + printf ("Could not initialize iterator!"); + exit (1); + } + + if (bson_iter_visit_all (&iter, &visitors, &state) || + err_offset != -1) { + printf ("Found error at offset %d.\n", err_offset); + } else { + printf ("BSON document had no errors.\n"); + } + } + + The example below demonstrates how to use a visitor to validate a BSON document's maximum depth. + +.. _example_custom_validation: + +Example Custom Validation +------------------------- + +.. literalinclude:: ../includes/examples/bson-check-depth.c + :language: c + :caption: bson-check-depth.c + :start-after: -- sphinx-include-start -- \ No newline at end of file diff --git a/source/libbson/api/bson_writer_t.txt b/source/libbson/api/bson_writer_t.txt new file mode 100644 index 00000000..c4ce57a1 --- /dev/null +++ b/source/libbson/api/bson_writer_t.txt @@ -0,0 +1,86 @@ +.. _bson_writer_t: + +============= +bson_writer_t +============= + +Bulk BSON serialization Abstraction + +Synopsis +-------- + +.. code-block:: c + + #include + + 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 *realloc_func_ctx); + void + bson_writer_destroy (bson_writer_t *writer); + +Description +----------- + +The :ref:`bson_writer_t` API provides an abstraction for serializing many BSON documents +to a single memory region. The memory region may be dynamically allocated and re-allocated +as more memory is demanded. This can be useful when building network packets from a high-level +language. For example, you can serialize a Python Dictionary directly to a single buffer +destined for a TCP packet. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/bson_writer_t/bson_writer_begin + /libbson/api/bson_writer_t/bson_writer_destroy + /libbson/api/bson_writer_t/bson_writer_end + /libbson/api/bson_writer_t/bson_writer_get_length + /libbson/api/bson_writer_t/bson_writer_new + /libbson/api/bson_writer_t/bson_writer_rollback + +- :ref:`bson_writer_begin` +- :ref:`bson_writer_destroy` +- :ref:`bson_writer_end` +- :ref:`bson_writer_get_length` +- :ref:`bson_writer_new` +- :ref:`bson_writer_rollback` + +Example +------- + +.. code-block:: c + + #include + + int + main (int argc, char *argv[]) + { + bson_writer_t *writer; + uint8_t *buf = NULL; + size_t buflen = 0; + bson_t *doc; + + writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL); + + for (i = 0; i < 1000; i++) { + bson_writer_begin (writer, &doc); + BSON_APPEND_INT32 (&doc, "i", i); + bson_writer_end (writer); + } + + bson_writer_destroy (writer); + + bson_free (buf); + + return 0; + } + diff --git a/source/libbson/api/bson_writer_t/bson_writer_begin.txt b/source/libbson/api/bson_writer_t/bson_writer_begin.txt new file mode 100644 index 00000000..6fd60f3b --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_begin.txt @@ -0,0 +1,32 @@ +.. _bson_writer_begin: + +=================== +bson_writer_begin() +=================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_writer_begin (bson_writer_t *writer, bson_t **bson); + +Parameters +---------- + +- ``writer``: A :ref:`bson_writer_t`. +- ``bson``: A :ref:`bson_t`. + +Description +----------- + +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 :ref:`bson_writer_end` +or :ref:`bson_writer_rollback`. + +Returns +------- + +true if there was space in the underlying buffers to begin the document. + diff --git a/source/libbson/api/bson_writer_t/bson_writer_destroy.txt b/source/libbson/api/bson_writer_t/bson_writer_destroy.txt new file mode 100644 index 00000000..fe50396d --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_destroy.txt @@ -0,0 +1,25 @@ +.. _bson_writer_destroy: + +===================== +bson_writer_destroy() +===================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_writer_destroy (bson_writer_t *writer); + +Parameters +---------- + +- ``writer``: A :ref:`bson_writer_t`. + +Description +----------- + +Cleanup after ``writer`` and release any allocated memory. Does nothing if ``writer`` is +NULL. Note that the buffer supplied to :ref:`bson_writer_new` is *NOT* freed from +this method. The caller is responsible for that. diff --git a/source/libbson/api/bson_writer_t/bson_writer_end.txt b/source/libbson/api/bson_writer_t/bson_writer_end.txt new file mode 100644 index 00000000..0ded9cc2 --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_end.txt @@ -0,0 +1,24 @@ +.. _bson_writer_end: + +================= +bson_writer_end() +================= + +Synopsis +-------- + +.. code-block:: c + + void + bson_writer_end (bson_writer_t *writer); + +Parameters +---------- + +- ``writer``: A :ref:`bson_writer_t`. + +Description +----------- + +Complete writing of a :ref:`bson_writer_t` to the buffer supplied. + diff --git a/source/libbson/api/bson_writer_t/bson_writer_get_length.txt b/source/libbson/api/bson_writer_t/bson_writer_get_length.txt new file mode 100644 index 00000000..c76b41af --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_get_length.txt @@ -0,0 +1,33 @@ +.. _bson_writer_get_length: + +======================== +bson_writer_get_length() +======================== + +Synopsis +-------- + +.. code-block:: c + + size_t + bson_writer_get_length (bson_writer_t *writer); + +Parameters +---------- + +- ``writer``: A :ref:`bson_writer_t`. + +Description +----------- + +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 boundary that cannot +be sent in a packet. See :ref:`bson_writer_rollback` to abort the current document being written. + +Returns +------- + +The length of the underlying buffer. + diff --git a/source/libbson/api/bson_writer_t/bson_writer_new.txt b/source/libbson/api/bson_writer_t/bson_writer_new.txt new file mode 100644 index 00000000..9f960b1b --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_new.txt @@ -0,0 +1,40 @@ +.. _bson_writer_new: + +================= +bson_writer_new() +================= + +Synopsis +-------- + +.. code-block:: c + + bson_writer_t * + bson_writer_new (uint8_t **buf, + size_t *buflen, + size_t offset, + bson_realloc_func realloc_func, + void *realloc_func_ctx); + +Parameters +---------- + +- ``buf``: A uint8_t. +- ``buflen``: A size_t. +- ``offset``: A size_t. +- ``realloc_func``: A bson_realloc_func. +- ``realloc_func_ctx``: A bson_realloc_func. + +Description +----------- + +Creates a new instance of :ref:`bson_writer_t` using the ``buffer``, ``length``, ``offset``, +and _realloc()_ function supplied. + +The caller is expected to clean up the structure when finished using :ref:`bson_writer_destroy`. + +Returns +------- + +A newly allocated bson_writer_t. + diff --git a/source/libbson/api/bson_writer_t/bson_writer_rollback.txt b/source/libbson/api/bson_writer_t/bson_writer_rollback.txt new file mode 100644 index 00000000..5d14c661 --- /dev/null +++ b/source/libbson/api/bson_writer_t/bson_writer_rollback.txt @@ -0,0 +1,26 @@ +.. _bson_writer_rollback: + +====================== +bson_writer_rollback() +====================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_writer_rollback (bson_writer_t *writer); + +Parameters +---------- + +- ``writer``: A :ref:`bson_writer_t`. + +Description +----------- + +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. + diff --git a/source/libbson/api/character_and_string_routines.txt b/source/libbson/api/character_and_string_routines.txt new file mode 100644 index 00000000..6ea83870 --- /dev/null +++ b/source/libbson/api/character_and_string_routines.txt @@ -0,0 +1,54 @@ +.. _bson_character_and_string_routines: + +============================= +Character and String Routines +============================= + +We provide a small number of character and string routines to substitute for those that +are not available on all platforms, and routines to make UTF-8 character manipulation +convenient. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/character_string_routines/bson_ascii_strtoll + /libbson/api/character_string_routines/bson_isspace + /libbson/api/character_string_routines/bson_snprintf + /libbson/api/character_string_routines/bson_strcasecmp + /libbson/api/character_string_routines/bson_strdup + /libbson/api/character_string_routines/bson_strdup_printf + /libbson/api/character_string_routines/bson_strdupv_printf + /libbson/api/character_string_routines/bson_strfreev + /libbson/api/character_string_routines/bson_strncpy + /libbson/api/character_string_routines/bson_strndup + /libbson/api/character_string_routines/bson_strnlen + /libbson/api/character_string_routines/bson_uint32_to_string + /libbson/api/character_string_routines/bson_utf8_escape_for_json + /libbson/api/character_string_routines/bson_utf8_from_unichar + /libbson/api/character_string_routines/bson_utf8_get_char + /libbson/api/character_string_routines/bson_utf8_next_char + /libbson/api/character_string_routines/bson_utf8_validate + /libbson/api/character_string_routines/bson_vsnprintf + +- :ref:`bson_ascii_strtoll` +- :ref:`bson_isspace` +- :ref:`bson_snprintf` +- :ref:`bson_strcasecmp` +- :ref:`bson_strdup` +- :ref:`bson_strdup_printf` +- :ref:`bson_strdupv_printf` +- :ref:`bson_strfreev` +- :ref:`bson_strncpy` +- :ref:`bson_strndup` +- :ref:`bson_strnlen` +- :ref:`bson_uint32_to_string` +- :ref:`bson_utf8_escape_for_json` +- :ref:`bson_utf8_from_unichar` +- :ref:`bson_utf8_get_char` +- :ref:`bson_utf8_next_char` +- :ref:`bson_utf8_validate` +- :ref:`bson_vsnprintf` \ No newline at end of file diff --git a/source/libbson/api/character_string_routines/bson_ascii_strtoll.txt b/source/libbson/api/character_string_routines/bson_ascii_strtoll.txt new file mode 100644 index 00000000..bc411cfe --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_ascii_strtoll.txt @@ -0,0 +1,45 @@ +.. _bson_ascii_strtoll: + +==================== +bson_ascii_strtoll() +==================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + bson_ascii_strtoll (const char *str, char **endptr, int base); + +Parameters +---------- + +- ``str``: The string to convert. +- ``endptr``: Address of the first invalid character of ``str``, or null. +- ``base``: The base to use for the conversion. + +Description +----------- + +A portable version of ``strtoll()``. + + +Converts a string to a 64-bit signed integer according to the given ``base``, +which must be 16, 10, or 8. Leading whitespace will be ignored. + +If base is 0 is passed in, the base is inferred from the string's leading +characters. Base-16 numbers start with "0x" or "0X", base-8 numbers start with +"0", base-10 numbers start with a digit from 1 to 9. + +If ``endptr`` is not NULL, it will be assigned the address of the first invalid +character of ``str``, or its null terminating byte if the entire string was valid. + +If an invalid value is encountered, errno will be set to EINVAL and zero will +be returned. If the number is out of range, errno is set to ERANGE and +LLONG_MAX or LLONG_MIN is returned. + +Returns +------- + +The result of the conversion. diff --git a/source/libbson/api/character_string_routines/bson_isspace.txt b/source/libbson/api/character_string_routines/bson_isspace.txt new file mode 100644 index 00000000..d071e60d --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_isspace.txt @@ -0,0 +1,30 @@ +.. _bson_isspace: + +============== +bson_isspace() +============== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_isspace (int c); + +Parameters +---------- + +- ``c``: A character. + +Description +----------- + +A safer alternative to ``isspace`` with additional bounds checking. + +It is equivalent to ``isspace``, excepts always returns false if ``c`` is out of the inclusive bounds [-1, 255]. + +Returns +------- + +A boolean indicating if the ``c`` is considered white-space (as determined by the ``isspace`` function). diff --git a/source/libbson/api/character_string_routines/bson_snprintf.txt b/source/libbson/api/character_string_routines/bson_snprintf.txt new file mode 100644 index 00000000..ef7025af --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_snprintf.txt @@ -0,0 +1,33 @@ +.. _bson_snprintf: + +=============== +bson_snprintf() +=============== + +Synopsis +-------- + +.. code-block:: c + + int + bson_snprintf (char *str, size_t size, const char *format, ...) + BSON_GNUC_PRINTF (3, 4); + +Parameters +---------- + +- ``str``: The destination buffer. +- ``size``: The size of ``str``. +- ``format``: A printf style format string. + +Description +----------- + +This is a portable wrapper around ``snprintf()``. It also enforces a trailing ``\0`` in +the resulting string. + +Returns +------- + +The number of bytes written to ``str``. + diff --git a/source/libbson/api/character_string_routines/bson_strcasecmp.txt b/source/libbson/api/character_string_routines/bson_strcasecmp.txt new file mode 100644 index 00000000..c01f629b --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strcasecmp.txt @@ -0,0 +1,31 @@ +.. _bson_strcasecmp: + +================= +bson_strcasecmp() +================= + +Synopsis +-------- + +.. code-block:: c + + int + bson_strcasecmp (const char *s1, const char *s2); + +Parameters +---------- + +- ``s1``: A string. +- ``s2``: A string. + +Description +----------- + +A portable version of ``strcasecmp()``. + +Returns +------- + +Returns a negative integer if s1 sorts lexicographically before s2, a positive +integer if it sorts after, or 0 if they are equivalent, after translating both +strings to lower case. diff --git a/source/libbson/api/character_string_routines/bson_strdup.txt b/source/libbson/api/character_string_routines/bson_strdup.txt new file mode 100644 index 00000000..4e984313 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strdup.txt @@ -0,0 +1,29 @@ +.. _bson_strdup: + +============= +bson_strdup() +============= + +Synopsis +-------- + +.. code-block:: c + + char * + bson_strdup (const char *str); + +Parameters +---------- + +- ``str``: A string. + +Description +----------- + +Copies ``str`` into a new string. If ``str`` is NULL, then NULL is returned. + +Returns +------- + +A newly allocated string that should be freed with bson_free(). + diff --git a/source/libbson/api/character_string_routines/bson_strdup_printf.txt b/source/libbson/api/character_string_routines/bson_strdup_printf.txt new file mode 100644 index 00000000..9782f63a --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strdup_printf.txt @@ -0,0 +1,29 @@ +.. _bson_strdup_printf: + +==================== +bson_strdup_printf() +==================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_strdup_printf (const char *format, ...) BSON_GNUC_PRINTF (1, 2); + +Parameters +---------- + +- ``format``: A printf style format string. + +Description +----------- + +This function performs a printf style format but into a newly allocated string. + +Returns +------- + +A newly allocated string that should be freed with bson_free(). + diff --git a/source/libbson/api/character_string_routines/bson_strdupv_printf.txt b/source/libbson/api/character_string_routines/bson_strdupv_printf.txt new file mode 100644 index 00000000..d97cc883 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strdupv_printf.txt @@ -0,0 +1,30 @@ +.. _bson_strdupv_printf: + +===================== +bson_strdupv_printf() +===================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_strdupv_printf (const char *format, va_list args) BSON_GNUC_PRINTF (1, 0); + +Parameters +---------- + +- ``format``: A printf style format string. +- ``args``: A va_list. + +Description +----------- + +This function is like :ref:`bson_strdup_printf` except takes a va_list of parameters. + +Returns +------- + +A newly allocated string that should be freed with bson_free(). + diff --git a/source/libbson/api/character_string_routines/bson_strfreev.txt b/source/libbson/api/character_string_routines/bson_strfreev.txt new file mode 100644 index 00000000..d30bad06 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strfreev.txt @@ -0,0 +1,24 @@ +.. _bson_strfreev: + +=============== +bson_strfreev() +=============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_strfreev (char **strv); + +Parameters +---------- + +- ``strv``: A NULL-terminated array of strings to free, including the array. + +Description +----------- + +This will free each string in a NULL-terminated array of strings and then the array itself. + diff --git a/source/libbson/api/character_string_routines/bson_strncpy.txt b/source/libbson/api/character_string_routines/bson_strncpy.txt new file mode 100644 index 00000000..731ccf73 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strncpy.txt @@ -0,0 +1,34 @@ +.. _bson_strncpy: + +============== +bson_strncpy() +============== + +Synopsis +-------- + +.. code-block:: c + + void + bson_strncpy (char *dst, const char *src, size_t size); + +Parameters +---------- + +- ``dst``: The destination buffer. +- ``src``: The src buffer. +- ``size``: The number of bytes to copy into dst, which must be at least that size. + +Description +----------- + +Copies up to ``size`` bytes from ``src`` into ``dst``. ``dst`` must be at least ``size`` +bytes in size. A trailing ``\0`` is always set. + +Does nothing if ``size`` is zero. + +``bson_strncpy`` matches the behavior of the C11 standard ``strncpy_s``, rather than +``strncpy``. This means that ``bson_strncpy`` always writes a null terminator to ``dst``, +even if ``dst`` is too short to fit the entire string from ``src``. If there is additional +space left in ``dst`` after copying ``src``, ``bson_strncpy`` does not fill the remaining +space with null characters. diff --git a/source/libbson/api/character_string_routines/bson_strndup.txt b/source/libbson/api/character_string_routines/bson_strndup.txt new file mode 100644 index 00000000..e66f8d2d --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strndup.txt @@ -0,0 +1,31 @@ +.. _bson_strndup: + +============== +bson_strndup() +============== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_strndup (const char *str, size_t n_bytes); + +Parameters +---------- + +- ``str``: A string to copy. +- ``n_bytes``: A size_t. + +Description +----------- + +Allocates a new string and copies up to ``n_bytes`` from ``str`` into it. A trailing ``\0`` +is always set. + +Returns +------- + +A newly allocated string that should be freed with bson_free(). + diff --git a/source/libbson/api/character_string_routines/bson_strnlen.txt b/source/libbson/api/character_string_routines/bson_strnlen.txt new file mode 100644 index 00000000..724fa4b2 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_strnlen.txt @@ -0,0 +1,30 @@ +.. _bson_strnlen: + +============== +bson_strnlen() +============== + +Synopsis +-------- + +.. code-block:: c + + size_t + bson_strnlen (const char *s, size_t maxlen); + +Parameters +---------- + +- ``s``: A string. +- ``maxlen``: The maximum size of string to check. + +Description +----------- + +A portable version of ``strnlen()``. + +Returns +------- + +The length of ``s`` in bytes or ``maxlen`` if no ``\0`` was found. + diff --git a/source/libbson/api/character_string_routines/bson_uint32_to_string.txt b/source/libbson/api/character_string_routines/bson_uint32_to_string.txt new file mode 100644 index 00000000..d07a06d1 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_uint32_to_string.txt @@ -0,0 +1,59 @@ +.. _bson_uint32_to_string: + +======================= +bson_uint32_to_string() +======================= + +Synopsis +-------- + +.. code-block:: c + + size_t + bson_uint32_to_string (uint32_t value, + const char **strptr, + char *str, + size_t size); + + +Parameters +---------- + +- ``value``: A uint32_t. +- ``strptr``: A location for the resulting string pointer. +- ``str``: A location to buffer the string. +- ``size``: A size_t containing the size of ``str``. + +Description +----------- + +Converts ``value`` to a string. + +If ``value`` is from 0 to 999, it will use a constant string in the data section of the library. + +If not, a string will be formatted using ``str`` and ``snprintf()``. + +``strptr`` will always be set. It will either point to ``str`` or a constant string. Use this as your key. + +Array Element Key Building +-------------------------- + +Each element in a BSON array has a monotonic string key like ``"0"``, ``"1"``, etc. This function is +optimized for generating such string keys. + +.. code-block:: c + + char str[16]; + const char *key; + uint32_t i; + + for (i = 0; i < 10; i++) { + bson_uint32_to_string (i, &key, str, sizeof str); + printf ("Key: %s\n", key); + } + +Returns +------- + +The number of bytes in the resulting string. + diff --git a/source/libbson/api/character_string_routines/bson_utf8_escape_for_json.txt b/source/libbson/api/character_string_routines/bson_utf8_escape_for_json.txt new file mode 100644 index 00000000..41af03f4 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_utf8_escape_for_json.txt @@ -0,0 +1,35 @@ +.. _bson_utf8_escape_for_json: + +=========================== +bson_utf8_escape_for_json() +=========================== + +Synopsis +-------- + +.. code-block:: c + + char * + bson_utf8_escape_for_json (const char *utf8, ssize_t utf8_len); + +Parameters +---------- + +- ``utf8``: A UTF-8 encoded string. +- ``utf8_len``: The length of ``utf8`` in bytes or -1 if it is NULL terminated. + +Description +----------- + +Allocates a new string matching ``utf8`` except that special +characters in JSON are escaped. The resulting string is also +UTF-8 encoded. + +Both " and \\ characters will be backslash-escaped. If a NUL +byte is found before ``utf8_len`` bytes, it is converted to +"\\u0000". Other non-ASCII characters in the input are preserved. + +Returns +------- + +A newly allocated string that should be freed with :ref:`bson_free`. diff --git a/source/libbson/api/character_string_routines/bson_utf8_from_unichar.txt b/source/libbson/api/character_string_routines/bson_utf8_from_unichar.txt new file mode 100644 index 00000000..f5ad42c5 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_utf8_from_unichar.txt @@ -0,0 +1,27 @@ +.. _bson_utf8_from_unichar: + +======================== +bson_utf8_from_unichar() +======================== + +Synopsis +-------- + +.. code-block:: c + + void + bson_utf8_from_unichar (bson_unichar_t unichar, char utf8[6], uint32_t *len); + +Parameters +---------- + +- ``unichar``: A :ref:`bson_unichar_t` +- ``utf8``: A location for the utf8 sequence. +- ``len``: A location for the number of bytes in the resulting utf8 sequence. + +Description +----------- + +Converts a single unicode character to a multi-byte UTF-8 sequence. The result is stored in +``utf8`` and the number of bytes used in ``len``. + diff --git a/source/libbson/api/character_string_routines/bson_utf8_get_char.txt b/source/libbson/api/character_string_routines/bson_utf8_get_char.txt new file mode 100644 index 00000000..24a89138 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_utf8_get_char.txt @@ -0,0 +1,30 @@ +.. _bson_utf8_get_char: + +==================== +bson_utf8_get_char() +==================== + +Synopsis +-------- + +.. code-block:: c + + bson_unichar_t + bson_utf8_get_char (const char *utf8); + +Parameters +---------- + +- ``utf8``: A UTF-8 encoded string. + +Description +----------- + +Converts the current character in a UTF-8 sequence to a bson_unichar_t, the 32-bit representation +of the multi-byte character. + +Returns +------- + +A bson_unichar_t. + diff --git a/source/libbson/api/character_string_routines/bson_utf8_next_char.txt b/source/libbson/api/character_string_routines/bson_utf8_next_char.txt new file mode 100644 index 00000000..8be28b0d --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_utf8_next_char.txt @@ -0,0 +1,32 @@ +.. _bson_utf8_next_char: + +===================== +bson_utf8_next_char() +===================== + +Synopsis +-------- + +.. code-block:: c + + const char * + bson_utf8_next_char (const char *utf8); + +Parameters +---------- + +- ``utf8``: A UTF-8 encoded string. + +Description +----------- + +Advances within ``utf8`` to the next UTF-8 character, which may be multiple bytes offset +from ``utf8``. A pointer to the next character is returned. + +It is invalid to call this function on a string whose current character is ``\0``. + +Returns +------- + +A pointer to the beginning of the next character in the UTF-8 encoded string. + diff --git a/source/libbson/api/character_string_routines/bson_utf8_validate.txt b/source/libbson/api/character_string_routines/bson_utf8_validate.txt new file mode 100644 index 00000000..98ef050d --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_utf8_validate.txt @@ -0,0 +1,32 @@ +.. _bson_utf8_validate: + +==================== +bson_utf8_validate() +==================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_utf8_validate (const char *utf8, size_t utf8_len, bool allow_null); + +Parameters +---------- + +- ``utf8``: A string to verify. +- ``utf8_len``: The length of ``utf8`` in bytes. +- ``allow_null``: A bool indicating that embedded ``\0`` bytes are allowed. + +Description +----------- + +Validates that the content within ``utf8`` is valid UTF-8 (by the RFC 3629 standard). If +``allow_null`` is ``true``, then embedded NULL bytes are allowed (``\0``). + +Returns +------- + +true if ``utf8`` contains valid UTF-8. + diff --git a/source/libbson/api/character_string_routines/bson_vsnprintf.txt b/source/libbson/api/character_string_routines/bson_vsnprintf.txt new file mode 100644 index 00000000..296578d5 --- /dev/null +++ b/source/libbson/api/character_string_routines/bson_vsnprintf.txt @@ -0,0 +1,33 @@ +.. _bson_vsnprintf: + +================ +bson_vsnprintf() +================ + +Synopsis +-------- + +.. code-block:: c + + int + bson_vsnprintf (char *str, size_t size, const char *format, va_list ap) + BSON_GNUC_PRINTF (3, 0); + +Parameters +---------- + +- ``str``: A location for the resulting string. +- ``size``: The size of str in bytes. +- ``format``: A printf style format string. +- ``ap``: A va_list of parameters for the format. + +Description +----------- + +Like bson_snprintf() but allows for variadic parameters. + +Returns +------- + +The number of bytes written to ``str`` excluding the ``\0`` byte. + diff --git a/source/libbson/api/version.txt b/source/libbson/api/version.txt new file mode 100644 index 00000000..46246710 --- /dev/null +++ b/source/libbson/api/version.txt @@ -0,0 +1,60 @@ +.. _bson_version: + +================== +Libbson Versioning +================== + +Versioning Macros and Functions + +Macros +------ + +The following preprocessor macros can be used to perform various checks based on the version +of the library you are compiling against. This may be useful if you only want to enable a +feature on a certain version of the library. + +Synopsis +-------- + +.. code-block:: c + + #define BSON_CHECK_VERSION(major, minor, micro) + + #define BSON_MAJOR_VERSION (1) + #define BSON_MINOR_VERSION (4) + #define BSON_MICRO_VERSION (1) + #define BSON_VERSION_S "1.4.1" + + #define BSON_VERSION_HEX \ + (BSON_MAJOR_VERSION << 24 | BSON_MINOR_VERSION << 16 | \ + BSON_MICRO_VERSION << 8) + +Only compile a block on Libbson 1.1.0 and newer. + +.. code-block:: c + + #if BSON_CHECK_VERSION(1, 1, 0) + static void + do_something (void) + { + } + #endif + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libbson/api/version/bson_check_version + /libbson/api/version/bson_get_major_version + /libbson/api/version/bson_get_micro_version + /libbson/api/version/bson_get_minor_version + /libbson/api/version/bson_get_version + +- :ref:`bson_check_version` +- :ref:`bson_get_major_version` +- :ref:`bson_get_micro_version` +- :ref:`bson_get_minor_version` +- :ref:`bson_get_version` \ No newline at end of file diff --git a/source/libbson/api/version/bson_check_version.txt b/source/libbson/api/version/bson_check_version.txt new file mode 100644 index 00000000..ec560e32 --- /dev/null +++ b/source/libbson/api/version/bson_check_version.txt @@ -0,0 +1,31 @@ +.. _bson_check_version: + +==================== +bson_check_version() +==================== + +Synopsis +-------- + +.. code-block:: c + + bool + bson_check_version (int required_major, int required_minor, int required_micro); + +Parameters +---------- + +- ``required_major``: The minimum major version required. +- ``required_minor``: The minimum minor version required. +- ``required_micro``: The minimum micro version required. + +Description +----------- + +Check at runtime if this release of libbson meets a required version. + +Returns +------- + +True if libbson's version is greater than or equal to the required version. + diff --git a/source/libbson/api/version/bson_get_major_version.txt b/source/libbson/api/version/bson_get_major_version.txt new file mode 100644 index 00000000..43d0e25e --- /dev/null +++ b/source/libbson/api/version/bson_get_major_version.txt @@ -0,0 +1,24 @@ +.. _bson_get_major_version: + +======================== +bson_get_major_version() +======================== + +Synopsis +-------- + +.. code-block:: c + + int + bson_get_major_version (void); + +Description +----------- + +Get the first number in libbson's MAJOR.MINOR.MICRO release version. + +Returns +------- + +The value of ``BSON_MAJOR_VERSION`` when Libbson was compiled. + diff --git a/source/libbson/api/version/bson_get_micro_version.txt b/source/libbson/api/version/bson_get_micro_version.txt new file mode 100644 index 00000000..eaa21ee8 --- /dev/null +++ b/source/libbson/api/version/bson_get_micro_version.txt @@ -0,0 +1,24 @@ +.. _bson_get_micro_version: + +======================== +bson_get_micro_version() +======================== + +Synopsis +-------- + +.. code-block:: c + + int + bson_get_micro_version (void); + +Description +----------- + +Get the third number in libbson's MAJOR.MINOR.MICRO release version. + +Returns +------- + +The value of ``BSON_MICRO_VERSION`` when Libbson was compiled. + diff --git a/source/libbson/api/version/bson_get_minor_version.txt b/source/libbson/api/version/bson_get_minor_version.txt new file mode 100644 index 00000000..9a1e4843 --- /dev/null +++ b/source/libbson/api/version/bson_get_minor_version.txt @@ -0,0 +1,24 @@ +.. _bson_get_minor_version: + +======================== +bson_get_minor_version() +======================== + +Synopsis +-------- + +.. code-block:: c + + int + bson_get_minor_version (void); + +Description +----------- + +Get the middle number in libbson's MAJOR.MINOR.MICRO release version. + +Returns +------- + +The value of ``BSON_MINOR_VERSION`` when Libbson was compiled. + diff --git a/source/libbson/api/version/bson_get_version.txt b/source/libbson/api/version/bson_get_version.txt new file mode 100644 index 00000000..e0fa889d --- /dev/null +++ b/source/libbson/api/version/bson_get_version.txt @@ -0,0 +1,25 @@ +.. _bson_get_version: + +================== +bson_get_version() +================== + +Synopsis +-------- + +.. code-block:: c + + const char * + bson_get_version (void); + +Description +----------- + +A string representation of Libbson's version, formatted something like "1.2.3" or +"1.2.3-pre". + +Returns +------- + +A string you must not modify or free. + diff --git a/source/libbson/cross-platform-notes/threading.txt b/source/libbson/cross-platform-notes/threading.txt index dc7ee73d..e59a8605 100644 --- a/source/libbson/cross-platform-notes/threading.txt +++ b/source/libbson/cross-platform-notes/threading.txt @@ -8,7 +8,7 @@ Libbson's data structures are *NOT* thread-safe. You are responsible for accessi structures from one thread at a time. Libbson requires POSIX threads (pthreads) on all UNIX-like platforms. On Windows, the native threading -interface is used. Libbson uses your system's threading library to safely generate unique `ObjectIds -<{+api-libbson+}/bson_oid_t.html>`__, and to provide a fallback implementation for atomic operations on -platforms without built-in atomics. +interface is used. Libbson uses your system's threading library to safely generate unique :ref:`ObjectIds +`, and to provide a fallback implementation for atomic operations on platforms without built-in +atomics. diff --git a/source/libbson/guides/json.txt b/source/libbson/guides/json.txt index dd2831af..e908d1b4 100644 --- a/source/libbson/guides/json.txt +++ b/source/libbson/guides/json.txt @@ -19,9 +19,9 @@ Converting BSON to JSON There are often times where you might want to convert a BSON document to JSON. It is convenient for debugging as well as an interchange format. To help with this, Libbson contains the functions -`bson_as_canonical_extended_json <{+api-libbson+}/bson_as_canonical_extended_json.html>`__ and `bson_as_relaxed_extended_json -<{+api-libbson+}/bson_as_relaxed_extended_json.html>`__. The canonical format preserves BSON type information -for values that may have ambiguous representations in JSON (e.g. numeric types). +:ref:`bson_as_canonical_extended_json` and :ref:`bson_as_relaxed_extended_json`. The +canonical format preserves BSON type information for values that may have ambiguous representations +in JSON (e.g. numeric types). .. code-block:: c @@ -65,10 +65,10 @@ not required. Converting JSON to BSON ----------------------- -Converting back from JSON is also useful and common enough that we added `bson_init_from_json <{+api-libbson+}/bson_init_from_json.html>`__ -and `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__. +Converting back from JSON is also useful and common enough that we added :ref:`bson_init_from_json` +and :ref:`bson_new_from_json`. -The following example creates a new `bson_t <{+api-libbson+}/bson_t.html>`__ from the JSON string ``{"a":1}``. +The following example creates a new :ref:`bson_t` from the JSON string ``{"a":1}``. .. code-block:: c @@ -86,10 +86,9 @@ The following example creates a new `bson_t <{+api-libbson+}/bson_t.html>`__ fro Streaming JSON Parsing ---------------------- -Libbson provides `bson_json_reader_t <{+api-libbson+}/bson_json_reader_t.html>`__ to allow for parsing a -sequence of JSON documents into BSON. The interface is similar to `bson_reader_t <{+api-libbson+}/bson_reader_t/html>`__ -but expects the input to be in the `MongoDB extended JSON `_ -format. +Libbson provides :ref:`bson_json_reader_t` to allow for parsing a sequence of JSON documents into BSON. +The interface is similar to :ref:`bson_reader_t` but expects the input to be in the `MongoDB extended JSON +`_ format. .. code-block:: c diff --git a/source/libbson/guides/lifetimes.txt b/source/libbson/guides/lifetimes.txt index 15e9e782..274ad0a0 100644 --- a/source/libbson/guides/lifetimes.txt +++ b/source/libbson/guides/lifetimes.txt @@ -10,21 +10,20 @@ bson_t Lifetimes :depth: 2 :class: singlecol -A `bson_t <{+api-libbson+}/bson_t.html>`__ may contain its data directly or may contain pointers to heap-allocated memory. -Overwriting an existing `bson_t <{+api-libbson+}/bson_t.html>`__ or allowing a stack-allocated `bson_t <{+api-libbson+}/bson_t.html>`__ to go out of -scope may cause a memory leak. A `bson_t <{+api-libbson+}/bson_t.html>`__ should always be destroyed with `bson_destroy <{+api-libbson+}/bson_destroy.html>`__. +A :ref:`bson_t` may contain its data directly or may contain pointers to heap-allocated memory. +Overwriting an existing :ref:`bson_t` or allowing a stack-allocated :ref:`bson_t` to go out of +scope may cause a memory leak. A :ref:`bson_t` should always be destroyed with :ref:`bson_destroy`. bson_t Out Parameters --------------------- -A `bson_t <{+api-libbson+}/bson_t.html>`__ pointer used as an out parameter must point to valid overwritable storage for a -new `bson_t <{+api-libbson+}/bson_t.html>`__ which must be one of: +A :ref:`bson_t` pointer used as an out parameter must point to valid overwritable storage for a +new :ref:`bson_t` which must be one of: -- Uninitialized storage for a `bson_t <{+api-libbson+}/bson_t.html>`__. -- A zero-initialized `bson_t <{+api-libbson+}/bson_t.html>`__ object. -- A `bson_t <{+api-libbson+}/bson_t.html>`__ object initialized with ``BSON_INITIALIZER``. -- A `bson_t <{+api-libbson+}/bson_t.html>`__ object not created with `bson_new <{+api-libbson+}/bson_new.html>`__ that was destroyed - with `bson_destroy <{+api-libbson+}/bson_destroy.html>`__. +- Uninitialized storage for a :ref:`bson_t`. +- A zero-initialized :ref:`bson_t` object. +- A :ref:`bson_t` object initialized with ``BSON_INITIALIZER``. +- A :ref:`bson_t` object not created with :ref:`bson_new` that was destroyed with :ref:`bson_destroy`. This can be on the stack: @@ -43,12 +42,11 @@ Or on the heap: bson_destroy (heap_doc); bson_free (heap_doc); -Omitting `bson_destroy <{+api-libbson+}/bson_destroy.html>`__ in either case may cause memory leaks. +Omitting :ref:`bson_destroy` in either case may cause memory leaks. .. warning:: - Passing a `bson_t <{+api-libbson+}/bson_t.html>`__ pointer obtained from `bson_new <{+api-libbson+}/bson_new.html>`__ as an - out parameter will result in a leak of the `bson_t <{+api-libbson+}/bson_t.html>`__ struct. + Passing a :ref:`bson_t` pointer obtained from :ref:`bson_new` as an out parameter will result in a leak of the :ref:`bson_t` struct. .. code-block:: c diff --git a/source/libbson/guides/streaming-bson.txt b/source/libbson/guides/streaming-bson.txt index 1a3ecacd..257fc8f5 100644 --- a/source/libbson/guides/streaming-bson.txt +++ b/source/libbson/guides/streaming-bson.txt @@ -10,17 +10,17 @@ Streaming BSON :depth: 2 :class: singlecol -`bson_reader_t <{+api-libbson+}/bson_reader_t.html>`__ provides a streaming reader which can be initialized with a -filedescriptor or memory region. `bson_writer_t <{+api-libbson+}/bson_writer_t.html>`__ provides a streaming writer +:ref:`bson_reader_t` provides a streaming reader which can be initialized with a +filedescriptor or memory region. :ref:`bson_writer_t` provides a streaming writer which can be initialized with a memory region. (Streaming BSON to a file descriptor is not yet supported.) Reading from a BSON Stream -------------------------- -`bson_reader_t <{+api-libbson+}/bson_reader_t.html>`__ provides a convenient API to read sequential BSON documents from -a file-descriptor or memory buffer. The `bson_reader_read <{+api-libbson+}/bson_reader_read.html>`__ function will read -forward in the underlying stream and return a `bson_t <{+api-libbson+}/bson_t.html>`__ that can be inspected and +:ref:`bson_reader_t` provides a convenient API to read sequential BSON documents from +a file-descriptor or memory buffer. The :ref:`bson_reader_read` function will read +forward in the underlying stream and return a :ref:`bson_t` that can be inspected and iterated upon. .. code-block:: c @@ -60,17 +60,15 @@ iterated upon. return 0; } -See `bson_reader_new_from_fd <{+api-libbson+}/bson_reader_new_from_fd.html>`__, -`bson_reader_new_from_file <{+api-libbson+}/bson_reader_new_from_file.html>`__, and -`bson_reader_new_from_data <{+api-libbson+}/bson_reader_new_from_data.html>`__ for more information. +See :ref:`bson_reader_new_from_fd`, :ref:`bson_reader_new_from_file`, and +:ref:`bson_reader_new_from_data` for more information. Writing a Sequence of BSON Documents ------------------------------------ -`bson_writer_t <{+api-libbson+}/bson_writer_t.html>`__ provides a convenient API to write a sequence of BSON documents to a -memory buffer that can grow with ``realloc()``. The `bson_writer_begin <{+api-libbson+}/bson_writer_begin.html>`__ -and `bson_writer_end <{+api-libbson+}/bson_writer_end.html>`__ functions will manage the underlying buffer while building -the sequence of documents. +:ref:`bson_writer_t` provides a convenient API to write a sequence of BSON documents to a +memory buffer that can grow with ``realloc()``. The :ref:`bson_writer_begin` and :ref:`bson_writer_end` +functions will manage the underlying buffer while building the sequence of documents. This could also be useful if you want to write to a network packet while serializing the documents from a higher level language, (but do so just after the packets header). @@ -108,5 +106,5 @@ a higher level language, (but do so just after the packets header). return 0; } -See `bson_writer_new <{+api-libbson+}/bson_writer_new.html>`__ for more information. +See :ref:`bson_writer_new` for more information. diff --git a/source/libbson/includes/seealso/bson-as-json.rst b/source/libbson/includes/seealso/bson-as-json.rst index cd65baec..be17bed5 100644 --- a/source/libbson/includes/seealso/bson-as-json.rst +++ b/source/libbson/includes/seealso/bson-as-json.rst @@ -1,15 +1,15 @@ .. seealso:: - | `bson_array_as_canonical_extended_json <{+api-libbson+}/bson_array_as_canonical_extended_json.html>`__ + | :ref:`bson_array_as_canonical_extended_json` - | `bson_array_as_json <{+api-libbson+}/bson_array_as_json.html>`__ + | :ref:`bson_array_as_json` - | `bson_array_as_relaxed_extended_json <{+api-libbson+}/bson_array_as_relaxed_extended_json.html>`__ + | :ref:`bson_array_as_relaxed_extended_json` - | `bson_as_canonical_extended_json <{+api-libbson+}/bson_as_canonical_extended_json.html>`__ + | :ref:`bson_as_canonical_extended_json` - | `bson_as_json <{+api-libbson+}/bson_as_json.html>`__ + | :ref:`bson_as_json` - | `bson_as_json_with_opts <{+api-libbson+}/bson_as_json_with_opts.html>`__ + | :ref:`bson_as_json_with_opts` - | `bson_as_relaxed_extended_json <{+api-libbson+}/bson_as_relaxed_extended_json.html>`__ + | :ref:`bson_as_relaxed_extended_json` diff --git a/source/libbson/includes/seealso/create-bson.rst b/source/libbson/includes/seealso/create-bson.rst index 1f4c938d..7be772fd 100644 --- a/source/libbson/includes/seealso/create-bson.rst +++ b/source/libbson/includes/seealso/create-bson.rst @@ -1,23 +1,23 @@ .. seealso:: - | `bson_concat <{+api-libbson+}/bson_concat.html>`__ + | :ref:`bson_concat` - | `bson_init <{+api-libbson+}/bson_init.html>`__ + | :ref:`bson_init` - | `bson_init_from_json <{+api-libbson+}/bson_init_from_json.html>`__ + | :ref:`bson_init_from_json` - | `bson_init_static <{+api-libbson+}/bson_init_static.html>`__ + | :ref:`bson_init_static` - | `bson_new <{+api-libbson+}/bson_new.html>`__ + | :ref:`bson_new` - | `bson_new_from_buffer <{+api-libbson+}/bson_new_from_buffer.html>`__ + | :ref:`bson_new_from_buffer` - | `bson_new_from_data <{+api-libbson+}/bson_new_from_data.html>`__ + | :ref:`bson_new_from_data` - | `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__ + | :ref:`bson_new_from_json` - | `bson_reinit <{+api-libbson+}/bson_reinit.html>`__ + | :ref:`bson_reinit` - | `bson_reserve_buffer <{+api-libbson+}/bson_reserve_buffer.html>`__ + | :ref:`bson_reserve_buffer` - | `bson_sized_new <{+api-libbson+}/bson_sized_new.html>`__ + | :ref:`bson_sized_new` diff --git a/source/libbson/includes/seealso/iter-init.rst b/source/libbson/includes/seealso/iter-init.rst index bef73466..b575387d 100644 --- a/source/libbson/includes/seealso/iter-init.rst +++ b/source/libbson/includes/seealso/iter-init.rst @@ -1,9 +1,9 @@ .. seealso:: - | `bson_iter_init <{+api-libbson+}/bson_iter_init.html>`__ + | :ref:`bson_iter_init` - | `bson_iter_init_find <{+api-libbson+}/bson_iter_init_find.html>`__ + | :ref:`bson_iter_init_find` - | `bson_iter_init_find_case <{+api-libbson+}/bson_iter_init_find_case.html>`__ + | :ref:`bson_iter_init_find_case` - | `bson_iter_init_from_data <{+api-libbson+}/bson_iter_init_from_data.html>`__ + | :ref:`bson_iter_init_from_data` diff --git a/source/libbson/includes/seealso/json.rst b/source/libbson/includes/seealso/json.rst index 0bfaf1f4..a54aff10 100644 --- a/source/libbson/includes/seealso/json.rst +++ b/source/libbson/includes/seealso/json.rst @@ -1,7 +1,7 @@ .. seealso:: - | `bson_init_from_json <{+api-libbson+}/bson_init_from_json.html>`__ + | :ref:`bson_init_from_json` - | `bson_json_reader_read <{+api-libbson+}/bson_json_reader_read.html>`__ + | :ref:`bson_json_reader_read` - | `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__ + | :ref:`bson_new_from_json` diff --git a/source/libbson/tutorials/creating.txt b/source/libbson/tutorials/creating.txt index 54e6e3dd..724e2c58 100644 --- a/source/libbson/tutorials/creating.txt +++ b/source/libbson/tutorials/creating.txt @@ -13,9 +13,9 @@ Creating a BSON Document The bson_t Structure -------------------- -BSON documents are created using the `bson_t <{+api-libbson+}/bson_t.html>`__ structure. This structure encapsulates the +BSON documents are created using the :ref:`bson_t` structure. This structure encapsulates the necessary logic for encoding using the `BSON Specification `_. At the core, -`bson_t <{+api-libbson+}/bson_t.html>`__ is a buffer manager and set of encoding routines. +:ref:`bson_t` is a buffer manager and set of encoding routines. .. tip:: @@ -63,13 +63,13 @@ Now let's take a look at an example that adds a few different field types to a B BSON_APPEND_UTF8 (&b, "hello", "world"); BSON_APPEND_BOOL (&b, "bool", true); -Notice that we omitted the call to `bson_init <{+api-libbson+}/bson_init.html>`__. By specifying ``BSON_INITIALIZER`` +Notice that we omitted the call to :ref:`bson_init`. By specifying ``BSON_INITIALIZER`` we can remove the need to initialize the structure to a base state. Sub-Documents and Sub-Arrays ---------------------------- -To simplify the creation of sub-documents `bson_append_document_begin <{+api-libbson+}/bson_append_document_begin.html>`__ can be used +To simplify the creation of sub-documents :ref:`bson_append_document_begin` can be used to build a sub-document using the parent's memory region as the destination buffer. .. literalinclude:: ../includes/examples/creating.c @@ -78,7 +78,7 @@ to build a sub-document using the parent's memory region as the destination buff :end-before: // bson_append_document_begin example ... end :dedent: 6 -To simplify the creation of sub-arrays `bson_array_builder_t <{+api-libbson+}/bson_array_builder_t.html>`__ can be used to build a sub-array +To simplify the creation of sub-arrays :ref:`bson_array_builder_t` can be used to build a sub-array using the parent's memory region as the destination buffer. .. literalinclude:: ../includes/examples/creating.c diff --git a/source/libbson/tutorials/errors.txt b/source/libbson/tutorials/errors.txt index be80b475..662e390e 100644 --- a/source/libbson/tutorials/errors.txt +++ b/source/libbson/tutorials/errors.txt @@ -7,7 +7,7 @@ Handling Errors Description ----------- -Many libbson functions report errors by returning ``NULL`` or -1 and filling out a `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ +Many libbson functions report errors by returning ``NULL`` or -1 and filling out a :ref:`bson_error_t` structure with an error domain, error code, and message. - ``error.domain`` names the subsystem that generated the error. @@ -23,10 +23,10 @@ Some error codes overlap with others; always check both the domain and code to d - ``BSON_JSON_ERROR_READ_CORRUPT_JS`` ``BSON_JSON_ERROR_READ_INVALID_PARAM`` ``BSON_JSON_ERROR_READ_CB_FAILURE`` - - `bson_json_reader_t <{+api-libbson+}/bson_json_reader_t.html>`__ tried to parse invalid MongoDB Extended JSON. + - :ref:`bson_json_reader_t` tried to parse invalid MongoDB Extended JSON. Tried to parse a valid JSON document that is invalid as MongoDBExtended JSON. An internal callback failure during JSON parsing. * - ``BSON_ERROR_READER`` - ``BSON_ERROR_READER_BADFD`` - - `bson_json_reader_new_from_file <{+api-libbson+}/bson_json_reader_new_from_file.html>`__ could not open the file. + - :ref:`bson_json_reader_new_from_file` could not open the file. diff --git a/source/libbson/tutorials/oid.txt b/source/libbson/tutorials/oid.txt index a4bc6b3d..0958a541 100644 --- a/source/libbson/tutorials/oid.txt +++ b/source/libbson/tutorials/oid.txt @@ -13,7 +13,7 @@ ObjectIDs Libbson provides a simple way to generate ObjectIDs. It can be used in a single-threaded or multi-threaded manner depending on your requirements. -The `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__ structure represents an ``ObjectID`` in MongoDB. It is a 96-bit +The :ref:`bson_oid_t` structure represents an ``ObjectID`` in MongoDB. It is a 96-bit identifier. Composition @@ -27,19 +27,19 @@ Sorting ObjectIDs ----------------- The typical way to sort in C is using ``qsort()``. Therefore, Libbson provides a ``qsort()`` -compatible callback function named `bson_oid_compare <{+api-libbson+}/bson_oid_compare.html>`__. It returns ``less than 1``, -``greater than 1``, or ``0`` depending on the equality of two `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__ structures. +compatible callback function named :ref:`bson_oid_compare`. It returns ``less than 1``, +``greater than 1``, or ``0`` depending on the equality of two :ref:`bson_oid_t` structures. Comparing Object IDs -------------------- -If you simply want to compare two `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__ structures for equality, use -`bson_oid_equal <{+api-libbson+}/bson_oid_equal.html>`__. +If you simply want to compare two :ref:`bson_oid_t` structures for equality, use +:ref:`bson_oid_equal`. Generating ---------- -To generate a `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__, you may use the following. +To generate a :ref:`bson_oid_t`, you may use the following. .. code-block:: c @@ -50,7 +50,7 @@ To generate a `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__, you may use the Parsing ObjectID Strings ------------------------ -You can also parse a string containing a `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__. The input string *MUST* be 24 characters +You can also parse a string containing a :ref:`bson_oid_t`. The input string *MUST* be 24 characters or more in length. .. code-block:: c @@ -68,7 +68,7 @@ or more in length. Hashing ObjectIDs ----------------- -If you need to store items in a hashtable, you may want to use the `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__ as the key. +If you need to store items in a hashtable, you may want to use the :ref:`bson_oid_t` as the key. Libbson provides a hash function for just this purpose. It is based on DJB hash. .. code-block:: c @@ -80,8 +80,7 @@ Libbson provides a hash function for just this purpose. It is based on DJB hash. Fetching ObjectID Creation Time ------------------------------- -You can easily fetch the time that a `bson_oid_t <{+api-libbson+}/bson_oid_t.html>`__ was generated using -`bson_oid_get_time_t <{+api-libbson+}/bson_oid_get_time_t.html>`__. +You can easily fetch the time that a :ref:`bson_oid_t` was generated using :ref:`bson_oid_get_time_t`. .. code-block:: c diff --git a/source/libbson/tutorials/parsing.txt b/source/libbson/tutorials/parsing.txt index 74f30d3f..627eff31 100644 --- a/source/libbson/tutorials/parsing.txt +++ b/source/libbson/tutorials/parsing.txt @@ -14,13 +14,13 @@ Parsing ------- BSON documents are lazily parsed as necessary. To begin parsing a BSON document, use one of the -provided Libbson functions to create a new `bson_t <{+api-libbson+}/bson_t.html>`__ from existing data such as -`bson_new_from_data <{+api-libbson+}/bson_new_from_data.html>`__. This will make a copy of the data so -that additional mutations may occur to the BSON document. +provided Libbson functions to create a new :ref:`bson_t` from existing data such as +:ref:`bson_new_from_data`. This will make a copy of the data so that additional mutations +may occur to the BSON document. .. tip:: - If you only want to parse a BSON document and have no need to mutate it, you may use `bson_init_static <{+api-libbson+}/bson_init_static.html>`__ + If you only want to parse a BSON document and have no need to mutate it, you may use :ref:`bson_init_static` to avoid making a copy of the data. .. code-block:: c @@ -36,11 +36,11 @@ that additional mutations may occur to the BSON document. bson_destroy (b); -Only two checks are performed when creating a new `bson_t <{+api-libbson+}/bson_t.html>`__ from an existing buffer. First, +Only two checks are performed when creating a new :ref:`bson_t` from an existing buffer. First, the document must begin with the buffer length, matching what was expected by the caller. Second, the document must end with the expected trailing ``\0`` byte. -To parse the document further we use a `bson_iter_t <{+api-libbson+}/bson_iter_t.html>`__ to iterate the elements within the document. +To parse the document further we use a :ref:`bson_iter_t` to iterate the elements within the document. Let's print all of the field names in the document. .. code-block:: c @@ -57,9 +57,8 @@ Let's print all of the field names in the document. bson_destroy (b); } -Converting a document to JSON uses a `bson_iter_t <{+api-libbson+}/bson_iter_t.html>`__ and -`bson_visitor_t <{+api-libbson+}/bson_visitor_t.html>`__ to iterate all fields of a BSON document recursively and generate a -UTF-8 encoded JSON string. +Converting a document to JSON uses a :ref:`bson_iter_t` and :ref:`bson_visitor_t` to iterate +all fields of a BSON document recursively and generate a UTF-8 encoded JSON string. .. code-block:: c @@ -97,9 +96,8 @@ an example that will dive into a sub-document named "foo" and print it's field n Finding Fields Using Dot Notation --------------------------------- -Using the `bson_iter_recurse <{+api-libbson+}/bson_iter_recurse.html>`__ function exemplified above, -`bson_iter_find_descendant <{+api-libbson+}/bson_iter_find_descendant.html>`__ can find a field -for you using the MongoDB style path notation such as "foo.bar.0.baz". +Using the :ref:`bson_iter_recurse` function exemplified above, :ref:`bson_iter_find_descendant` +can find a field for you using the MongoDB style path notation such as "foo.bar.0.baz". Let's create a document like ``{"foo": {"bar": [{"baz: 1}]}}`` and locate the ``"baz"`` field. @@ -123,7 +121,7 @@ Let's create a document like ``{"foo": {"bar": [{"baz: 1}]}}`` and locate the `` Validating a BSON Document -------------------------- -If all you want to do is validate that a BSON document is valid, you can use `bson_validate <{+api-libbson+}/bson_validate.html>`__. +If all you want to do is validate that a BSON document is valid, you can use :ref:`bson_validate`. .. code-block:: c @@ -135,5 +133,5 @@ If all you want to do is validate that a BSON document is valid, you can use `bs (unsigned) err_offset); } -See the `bson_validate <{+api-libbson+}/bson_validate.html>`__ documentation for more information and examples. +See the :ref:`bson_validate` documentation for more information and examples. diff --git a/source/libbson/tutorials/utf8.txt b/source/libbson/tutorials/utf8.txt index 29aa524c..ddcb9f47 100644 --- a/source/libbson/tutorials/utf8.txt +++ b/source/libbson/tutorials/utf8.txt @@ -33,5 +33,5 @@ format. Notice the ``true`` at the end indicating ``\0`` is allowed. printf ("Validation failed.\n"); } -For more information see the API reference for `bson_utf8_validate <{+api-libbson+}/bson_utf8_validate.html>`__. +For more information see the API reference for :ref:`bson_utf8_validate`. diff --git a/source/libmongoc.txt b/source/libmongoc.txt index 91e732ec..9964d9dd 100644 --- a/source/libmongoc.txt +++ b/source/libmongoc.txt @@ -23,8 +23,8 @@ libmongoc /libmongoc/authentication /libmongoc/basic-troubleshooting /libmongoc/guides - API Documentation - Application Performance Monitoring + /libmongoc/api + /libmongoc/application-performance-monitoring Introduction ------------ diff --git a/source/libmongoc/api.txt b/source/libmongoc/api.txt new file mode 100644 index 00000000..b97a2604 --- /dev/null +++ b/source/libmongoc/api.txt @@ -0,0 +1,97 @@ +.. _libmongoc-api: + +============= +API Reference +============= + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/init-cleanup + /libmongoc/api/logging + /libmongoc/api/errors + /libmongoc/api/lifecycle + /libmongoc/api/gridfs + /libmongoc/api/mongoc_auto_encryption_opts_t + /libmongoc/api/mongoc_bulk_operation_t + /libmongoc/api/mongoc_change_stream_t + /libmongoc/api/mongoc_client_encryption_t + /libmongoc/api/mongoc_client_pool_t + /libmongoc/api/mongoc_client_session_t + /libmongoc/api/mongoc_client_t + /libmongoc/api/mongoc_collection_t + /libmongoc/api/mongoc_cursor_t + /libmongoc/api/mongoc_database_t + /libmongoc/api/mongoc_delete_flags_t + /libmongoc/api/mongoc_find_and_modify_opts_t + /libmongoc/api/mongoc_gridfs_t + /libmongoc/api/mongoc_host_list_t + /libmongoc/api/mongoc_index_opt_t + /libmongoc/api/mongoc_insert_flags_t + /libmongoc/api/mongoc_iovec_t + /libmongoc/api/mongoc_optional_t + /libmongoc/api/mongoc_query_flags_t + /libmongoc/api/mongoc_rand + /libmongoc/api/mongoc_read_concern_t + /libmongoc/api/mongoc_read_mode_t + /libmongoc/api/mongoc_read_prefs_t + /libmongoc/api/mongoc_remove_flags_t + /libmongoc/api/mongoc_reply_flags_t + /libmongoc/api/mongoc_server_api_t + /libmongoc/api/mongoc_server_description_t + /libmongoc/api/mongoc_session_opt_t + /libmongoc/api/mongoc_socket_t + /libmongoc/api/mongoc_ssl_opt_t + /libmongoc/api/mongoc_stream_t + /libmongoc/api/mongoc_topology_description_t + /libmongoc/api/mongoc_transaction_opt_t + /libmongoc/api/mongoc_transaction_state_t + /libmongoc/api/mongoc_update_flags_t + /libmongoc/api/mongoc_uri_t + /libmongoc/api/mongoc_version + /libmongoc/api/mongoc_write_concern_t + +- :ref:`mongoc_init_cleanup` +- :ref:`mongoc_logging` +- :ref:`mongoc_errors` +- :ref:`object-lifecycle` +- :ref:`gridfs` +- :ref:`mongoc_auto_encryption_opts_t` +- :ref:`mongoc_bulk_operation_t` +- :ref:`mongoc_change_stream_t` +- :ref:`mongoc_client_encryption_t` +- :ref:`mongoc_client_pool_t` +- :ref:`mongoc_client_session_t` +- :ref:`mongoc_client_t` +- :ref:`mongoc_collection_t` +- :ref:`mongoc_cursor_t` +- :ref:`mongoc_database_t` +- :ref:`mongoc_delete_flags_t` +- :ref:`mongoc_find_and_modify_opts_t` +- :ref:`mongoc_gridfs_t` +- :ref:`mongoc_host_list_t` +- :ref:`mongoc_index_opt_t` +- :ref:`mongoc_insert_flags_t` +- :ref:`mongoc_iovec_t` +- :ref:`mongoc_optional_t` +- :ref:`mongoc_query_flags_t` +- :ref:`mongoc_rand` +- :ref:`mongoc_read_concern_t` +- :ref:`mongoc_read_mode_t` +- :ref:`mongoc_read_prefs_t` +- :ref:`mongoc_remove_flags_t` +- :ref:`mongoc_reply_flags_t` +- :ref:`mongoc_server_api_t` +- :ref:`mongoc_server_description_t` +- :ref:`mongoc_session_opt_t` +- :ref:`mongoc_socket_t` +- :ref:`mongoc_ssl_opt_t` +- :ref:`mongoc_stream_t` +- :ref:`mongoc_topology_description_t` +- :ref:`mongoc_transaction_opt_t` +- :ref:`mongoc_transaction_state_t` +- :ref:`mongoc_update_flags_t` +- :ref:`mongoc_uri_t` +- :ref:`mongoc_version` +- :ref:`mongoc_write_concern_t` diff --git a/source/libmongoc/api/errors.txt b/source/libmongoc/api/errors.txt new file mode 100644 index 00000000..8972da71 --- /dev/null +++ b/source/libmongoc/api/errors.txt @@ -0,0 +1,329 @@ +.. _mongoc_errors: + +=============== +Error Reporting +=============== + +Description +----------- + +Many C Driver functions report errors by returning ``false`` or -1 and filling out a :ref:`bson_error_t` structure +with an error domain, error code, and message. Use ``domain`` to determine which subsystem generated the error, and +``code`` for the specific error. ``message`` is a human-readable error description. + +.. seealso:: + + | :ref:`Handling Errors in libbson `. + +Error code from server: https://github.com/mongodb/mongo/blob/master/src/mongo/base/error_codes.yml + +.. list-table:: + :widths: 1 1 2 + :stub-columns: 1 + :header-rows: 1 + + * - Code + - Code + - Description + + * - | ``MONGOC_ERROR_CLIENT`` + - | ``MONGOC_ERROR_CLIENT_TOO_BIG`` + - | You tried to send a message larger than the server's max message size. + + * - + - ``MONGOC_ERROR_CLIENT_AUTHENTICATE`` + - Wrong credentials, or failure sending or receiving authentication messages. + + * - | + - | ``MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER`` + - | You tried an TLS connection but the driver was not built with TLS. + + * - + - ``MONGOC_ERROR_CLIENT_IN_EXHAUST`` + - You began iterating an exhaust cursor, then tried to begin another operation + with the same :ref:`mongoc_client_t`. + + * - | + - | ``MONGOC_ERROR_CLIENT_SESSION_FAILURE`` + - Failure related to creating or using a logical session. + + * - + - ``MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_ARG`` + - Failure related to arguments passed when initializing In-Use Encryption. + + * - | + - | ``MONGOC_ERROR_CLIENT_INVALID_ENCRYPTION_STATE`` + - | Failure related to In-Use Encryption. + + * - + - ``MONGOC_ERROR_CLIENT_INVALID_LOAD_BALANCER`` + - You attempted to connect to a MongoDB server behind a load balancer, but the server does + not advertize load balanced support. + + * - | ``MONGOC_ERROR_STREAM`` + - | ``MONGOC_ERROR_STREAM_NAME_RESOLUTION`` + - | DNS failure. + + * - + - ``MONGOC_ERROR_STREAM_SOCKET`` + - Timeout communicating with server, or connection closed. + + * - | + - | ``MONGOC_ERROR_STREAM_CONNECT`` + - | Failed to connect to server. + + * - ``MONGOC_ERROR_PROTOCOL`` + - ``MONGOC_ERROR_PROTOCOL_INVALID_REPLY`` + - Corrupt response from server. + + * - | + - | ``MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION`` + - | The server version is too old or too new to communicate with the driver. + + * - ``MONGOC_ERROR_CURSOR`` + - ``MONGOC_ERROR_CURSOR_INVALID_CURSOR`` + - You passed bad arguments to :ref:`mongoc_collection_find_with_opts`, or you called :ref:`mongoc_cursor_next` + on a completed or failed cursor, or the cursor timed out on the server. + + * - | + - | ``MONGOC_ERROR_CHANGE_STREAM_NO_RESUME_TOKEN`` + - | A resume token was not returned in a document found with :ref:`mongoc_change_stream_next` + + * - ``MONGOC_ERROR_QUERY`` + - ``MONGOC_ERROR_QUERY_FAILURE`` + - :ref:`Error API Version 1\:\ ` Server error from command or query. The server error message is in message. + + * - | ``MONGOC_ERROR_SERVER`` + - | ``MONGOC_ERROR_QUERY_FAILURE`` + - | :ref:`Error API Version 2\:\ ` Server error from command or query. The server error message is in message. + + * - ``MONGOC_ERROR_SASL`` + - A SASL error code. + - ``man sasl_errors`` for a list of codes. + + * - | ``MONGOC_ERROR_BSON`` + - | ``MONGOC_ERROR_BSON_INVALID`` + - | You passed an invalid or oversized BSON document as a parameter, or called :ref:`mongoc_collection_create_index` + with invalid keys, or the server reply was corrupt. + + * - ``MONGOC_ERROR_NAMESPACE`` + - ``MONGOC_ERROR_NAMESPACE_INVALID`` + - You tried to create a collection with an invalid name. + + * - | ``MONGOC_ERROR_COMMAND`` + - | ``MONGOC_ERROR_COMMAND_INVALID_ARG`` + - | Many functions set this error code when passed bad parameters. Print the error message for details. + + * - + - ``MONGOC_ERROR_PROTOCOL_BAD_WIRE_VERSION`` + - You tried to use a command option the server does not support. + + * - | + - | ``MONGOC_ERROR_DUPLICATE_KEY`` + - | An insert or update failed because because of a duplicate ``_id`` or other unique-index violation. + + * - + - ``MONGOC_ERROR_MAX_TIME_MS_EXPIRED`` + - The operation failed because maxTimeMS expired. + + * - | + - | ``MONGOC_ERROR_SERVER_SELECTION_INVALID_ID`` + - | The ``serverId`` option for an operation conflicts with the pinned server for that operation's + client session (denoted by the ``sessionId`` option) + + * - ``MONGOC_ERROR_COMMAND`` + - :github:`Error code from server `. + - :ref:`Error API Version 1\:\ ` Server error from a command. The server error message is in message. + + * - | ``MONGOC_ERROR_SERVER`` + - | :github:`Error code from server `. + - | :ref:`Error API Version 2\:\ ` Server error from a command. The server error message is in message. + + * - ``MONGOC_ERROR_COLLECTION`` + - ``MONGOC_ERROR_COLLECTION_INSERT_FAILED``, + ``MONGOC_ERROR_COLLECTION_UPDATE_FAILED``, + ``MONGOC_ERROR_COLLECTION_DELETE_FAILED``. + - Invalid or empty input to :ref:`mongoc_collection_insert_one`, :ref:`mongoc_collection_insert_bulk`, :ref:`mongoc_collection_update_one`, + :ref:`mongoc_collection_update_many`, :ref:`mongoc_collection_replace_one`, :ref:`mongoc_collection_delete_one`, or + :ref:`mongoc_collection_delete_many`. + + * - | ``MONGOC_ERROR_COLLECTION`` + - | :github:`Error code from server `. + - | :ref:`Error API Version 1\:\ ` Server error from :ref:`mongoc_collection_insert_one`, :ref:`mongoc_collection_insert_bulk`, :ref:`mongoc_collection_update_one`, + :ref:`mongoc_collection_update_many`, or :ref:`mongoc_collection_replace_one`. + + * - ``MONGOC_ERROR_SERVER`` + - :github:`Error code from server `. + - :ref:`Error API Version 2\:\ ` Server error from :ref:`mongoc_collection_insert_one`, :ref:`mongoc_collection_insert_bulk`, :ref:`mongoc_collection_update_one`, + :ref:`mongoc_collection_update_many`, or :ref:`mongoc_collection_replace_one`. + + * - | ``MONGOC_ERROR_GRIDFS`` + - | ``MONGOC_ERROR_GRIDFS_CHUNK_MISSING`` + - | The GridFS file is missing a document in its ``chunks`` collection. + + * - + - ``MONGOC_ERROR_GRIDFS_CORRUPT`` + - A data inconsistency was detected in GridFS. + + * - | + - | ``MONGOC_ERROR_GRIDFS_INVALID_FILENAME`` + - | You passed a NULL filename to :ref:`mongoc_gridfs_remove_by_filename`. + + * - + - ``MONGOC_ERROR_GRIDFS_PROTOCOL_ERROR`` + - You called :ref:`mongoc_gridfs_file_set_id` after :ref:`mongoc_gridfs_file_save`, or tried to write on a closed GridFS stream. + + * - | + - | ``MONGOC_ERROR_GRIDFS_BUCKET_FILE_NOT_FOUND`` + - | A GridFS file is missing from ``files`` collection. + + * - + - ``MONGOC_ERROR_GRIDFS_BUCKET_STREAM`` + - An error occurred on a stream created from a GridFS operation like :ref:`mongoc_gridfs_bucket_upload_from_stream`. + + * - | ``MONGOC_ERROR_SCRAM`` + - | ``MONGOC_ERROR_SCRAM_PROTOCOL_ERROR`` + - | Failure in SCRAM-SHA-1 or SCRAM-SHA-256 authentication. + + * - ``MONGOC_ERROR_SERVER_SELECTION`` + - ``MONGOC_ERROR_SERVER_SELECTION_FAILURE`` + - No replica set member or mongos is available, or none matches your read preference, or you supplied an invalid + :ref:`mongoc_read_prefs_t`. + + * - | ``MONGOC_ERROR_WRITE_CONCERN`` + - | :github:`Error code from server `. + - | There was a :ref:`write concern error ` or :ref:`timeout ` + from the server. + + * - ``MONGOC_ERROR_TRANSACTION`` + - ``MONGOC_ERROR_TRANSACTION_INVALID`` + - You attempted to start a transaction when one is already in progress, or commit or abort when there is no transaction. + + * - | ``MONGOC_ERROR_CLIENT_SIDE_ENCRYPTION`` + - | Error code produced by libmongocrypt. + - | An error occurred in the library responsible for In-Use Encryption + + * - ``MONGOC_ERROR_AZURE`` + - ``MONGOC_ERROR_KMS_SERVER_HTTP`` + - An Azure HTTP service responded with an error status + + * - | + - | ``MONGOC_ERROR_KMS_SERVER_BAD_JSON`` + - | An Azure service responded with invalid JSON data + + * - ``MONGOC_ERROR_GCP`` + - ``MONGOC_ERROR_KMS_SERVER_HTTP`` + - A GCP HTTP service responded with an error status + + * - | + - | ``MONGOC_ERROR_KMS_SERVER_BAD_JSON`` + - | A GCP service responded with invalid JSON data + +.. _error_labels: + +Error Labels +------------ + +In some cases your application must make decisions based on what category of error the driver has returned, +but these categories do not correspond perfectly to an error domain or code. In such cases, error *labels* +provide a reliable way to determine how your application should respond to an error. + +Any C Driver function that has a :ref:`bson_t` out-parameter named ``reply`` may include error labels +to the reply, in the form of a BSON field named "errorLabels" containing an array of strings: + +.. code-block:: none + + { "errorLabels": [ "TransientTransactionError" ] } + +Use :ref:`mongoc_error_has_label` to test if a reply contains a specific label. See :ref:`mongoc_client_session_start_transaction` +for example code that demonstrates the use of error labels in application logic. + +The following error labels are currently defined. Future versions of MongoDB may introduce new labels. + +TransientTransactionError +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Within a multi-document transaction, certain errors can leave the transaction in an unknown or aborted state. +These include write conflicts, primary stepdowns, and network errors. In response, the application should abort +the transaction and try the same sequence of operations again in a new transaction. + +UnknownTransactionCommitResult +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When :ref:`mongoc_client_session_commit_transaction` encounters a network error or certain server errors, +it is not known whether the transaction was committed. Applications should attempt to commit the transaction +again until: the commit succeeds, the commit fails with an error *not* labeled "UnknownTransactionCommitResult", +or the application chooses to give up. + +.. _errors_error_api_version: +.. _error_api_version: + +Setting the Error API Version +----------------------------- + +The driver's error reporting began with a design flaw: when the error *domain* is ``MONGOC_ERROR_COLLECTION``, +``MONGOC_ERROR_QUERY``, or ``MONGOC_ERROR_COMMAND``, the error *code* might originate from the server or the driver. +An application cannot always know where an error originated, and therefore cannot tell what the code means. + +For example, if :ref:`mongoc_collection_update_one` sets the error's domain to ``MONGOC_ERROR_COLLECTION`` and its +code to 24, the application cannot know whether 24 is the generic driver error code ``MONGOC_ERROR_COLLECTION_UPDATE_FAILED`` +or the specific server error code "LockTimeout". + +To fix this flaw while preserving backward compatibility, the C Driver 1.4 introduces "Error API Versions". Version 1, +the default Error API Version, maintains the flawed behavior. Version 2 adds a new error domain, ``MONGOC_ERROR_SERVER``. +In Version 2, error codes originating on the server always have error domain ``MONGOC_ERROR_SERVER`` or ``MONGOC_ERROR_WRITE_CONCERN``. +When the driver uses Version 2 the application can always determine the origin and meaning of error codes. New applications should +use Version 2, and existing applications should be updated to use Version 2 as well. + +.. list-table:: + :widths: 1 1 2 + :stub-columns: 1 + :header-rows: 1 + + * - Error Source + - API Version 1 + - API Version 2 + + * - | :ref:`mongoc_cursor_error` + - | ``MONGOC_ERROR_QUERY`` + - | ``MONGOC_ERROR_SERVER`` + + * - :ref:`mongoc_client_command_with_opts`, :ref:`mongoc_database_command_with_opts`, and other command functions + - ``MONGOC_ERROR_QUERY`` + - ``MONGOC_ERROR_SERVER`` + + * - | :ref:`mongoc_collection_count_with_opts`, :ref:`mongoc_client_get_database_names_with_opts`, and other command helper functions + - | ``MONGOC_ERROR_QUERY`` + - | ``MONGOC_ERROR_SERVER`` + + * - :ref:`mongoc_collection_insert_one`, :ref:`mongoc_collection_insert_bulk`, :ref:`mongoc_collection_update_one`, + :ref:`mongoc_collection_update_many`, :ref:`mongoc_collection_replace_one`, :ref:`mongoc_collection_delete_one`, + :ref:`mongoc_collection_delete_many` + - ``MONGOC_ERROR_COMMAND`` + - ``MONGOC_ERROR_SERVER`` + + * - | :ref:`mongoc_bulk_operation_execute` + - | ``MONGOC_ERROR_COMMAND`` + - | ``MONGOC_ERROR_SERVER`` + + * - Write-concern timeout + - ``MONGOC_ERROR_WRITE_CONCERN`` + - ``MONGOC_ERROR_WRITE_CONCERN`` + +The Error API Versions are defined with ``MONGOC_ERROR_API_VERSION_LEGACY`` and ``MONGOC_ERROR_API_VERSION_2``. +Set the version with :ref:`mongoc_client_set_error_api` or :ref:`mongoc_client_pool_set_error_api`. + +.. seealso:: + + | `MongoDB Server Error Codes `_ + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/errors/mongoc_error_has_label + +- :ref:`mongoc_error_has_label` diff --git a/source/libmongoc/api/errors/mongoc_error_has_label.txt b/source/libmongoc/api/errors/mongoc_error_has_label.txt new file mode 100644 index 00000000..ee0ad245 --- /dev/null +++ b/source/libmongoc/api/errors/mongoc_error_has_label.txt @@ -0,0 +1,28 @@ +.. _mongoc_error_has_label: + +======================== +mongoc_error_has_label() +======================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_error_has_label (const bson_t *reply, const char *label); + +Test whether a reply from a failed operation includes a specific error label. See +:ref:`Error Labels ` for details, and see :ref:`mongoc_client_session_start_transaction` +for example code that demonstrates their use. + +Parameters +---------- + +- ``reply``: A ``bson_t-storage-ptr`` to contain the results. +- ``label``: The label to test for, such as "TransientTransactionError" or "UnknownTransactionCommitResult". + +Returns +------- + +Returns true if ``reply`` contains the error label. diff --git a/source/libmongoc/api/gridfs.txt b/source/libmongoc/api/gridfs.txt new file mode 100644 index 00000000..eedda603 --- /dev/null +++ b/source/libmongoc/api/gridfs.txt @@ -0,0 +1,13 @@ +.. _gridfs: + +====== +GridFS +====== + +The C driver includes two APIs for GridFS. + +The older API consists of :ref:`mongoc_gridfs_t` and its derivatives. It contains deprecated API, does not support read preferences, and is not recommended in new applications. It does not conform to the `MongoDB GridFS specification `_. + +The newer API consists of :ref:`mongoc_gridfs_bucket_t` and allows uploading/downloading through derived :ref:`mongoc_stream_t` objects. It conforms to the `MongoDB GridFS specification `_. + +There is not always a straightforward upgrade path from an application built with :ref:`mongoc_gridfs_t` to :ref:`mongoc_gridfs_bucket_t` (e.g. a :ref:`mongoc_gridfs_file_t` provides functions to seek but :ref:`mongoc_stream_t` does not). But users are encouraged to upgrade when possible. \ No newline at end of file diff --git a/source/libmongoc/api/init-cleanup.txt b/source/libmongoc/api/init-cleanup.txt new file mode 100644 index 00000000..317187ca --- /dev/null +++ b/source/libmongoc/api/init-cleanup.txt @@ -0,0 +1,34 @@ +.. _mongoc_init_cleanup: + +========================== +Initialization and cleanup +========================== + +Synopsis +-------- + +.. include:: /libmongoc/includes/init_cleanup.txt + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/init-cleanup/mongoc_init + /libmongoc/api/init-cleanup/mongoc_cleanup + +Deprecated feature: automatic initialization and cleanup +-------------------------------------------------------- + +On some platforms the driver can automatically call :ref:`mongoc_init` before ``main``, +and call :ref:`mongoc_cleanup` as the process exits. This is problematic in situations where related +libraries also execute cleanup code on shutdown, and it creates inconsistent rules across platforms. +Therefore the automatic initialization and cleanup feature is deprecated, and will be dropped in +version 2.0. Meanwhile, for backward compatibility, the feature is *enabled* by default on platforms +where it is available. + +For portable, future-proof code, always call :ref:`mongoc_init` and :ref:`mongoc_cleanup` yourself, +and configure the driver like: + +.. code-block:: none + + cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF diff --git a/source/libmongoc/api/init-cleanup/mongoc_cleanup.txt b/source/libmongoc/api/init-cleanup/mongoc_cleanup.txt new file mode 100644 index 00000000..ca433b19 --- /dev/null +++ b/source/libmongoc/api/init-cleanup/mongoc_cleanup.txt @@ -0,0 +1,18 @@ +.. _mongoc_cleanup: + +================ +mongoc_cleanup() +================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_cleanup (void); + +Description +----------- + +.. include:: /libmongoc/includes/init_cleanup.txt diff --git a/source/libmongoc/api/init-cleanup/mongoc_init.txt b/source/libmongoc/api/init-cleanup/mongoc_init.txt new file mode 100644 index 00000000..9385785c --- /dev/null +++ b/source/libmongoc/api/init-cleanup/mongoc_init.txt @@ -0,0 +1,18 @@ +.. _mongoc_init: + +============= +mongoc_init() +============= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_init (void); + +Description +----------- + +.. include:: /libmongoc/includes/init_cleanup.txt diff --git a/source/libmongoc/api/lifecycle.txt b/source/libmongoc/api/lifecycle.txt new file mode 100644 index 00000000..dfdb6960 --- /dev/null +++ b/source/libmongoc/api/lifecycle.txt @@ -0,0 +1,70 @@ +.. _object-lifecycle: + +================ +Object Lifecycle +================ + +This page documents the order of creation and destruction for libmongoc's main struct types. + +Clients and pools +----------------- + +Call :ref:`mongoc_init` once, before calling any other libmongoc functions, and call +:ref:`mongoc_cleanup` once before your program exits. + +A program that uses libmongoc from multiple threads should create a :ref:`mongoc_client_pool_t` +with :ref:`mongoc_client_pool_new`. Each thread acquires a :ref:`mongoc_client_t` from the pool +with :ref:`mongoc_client_pool_pop` and returns it with :ref:`mongoc_client_pool_push` when the +thread is finished using it. To destroy the pool, first return all clients, then call :ref:`mongoc_client_pool_destroy`. + +If your program uses libmongoc from only one thread, create a :ref:`mongoc_client_t` directly +with :ref:`mongoc_client_new` or :ref:`mongoc_client_new_from_uri`. Destroy it with :ref:`mongoc_client_destroy`. + +Databases, collections, and related objects +------------------------------------------- + +You can create a :ref:`mongoc_database_t` or :ref:`mongoc_collection_t` from a :ref:`mongoc_client_t`, +and create a :ref:`mongoc_cursor_t` or :ref:`mongoc_bulk_operation_t` from a :ref:`mongoc_collection_t`. + +Each of these objects must be destroyed before the client they were created from, but their lifetimes +are otherwise independent. + +GridFS objects +-------------- + +You can create a :ref:`mongoc_gridfs_t` from a :ref:`mongoc_client_t`, create a :ref:`mongoc_gridfs_file_t` +or :ref:`mongoc_gridfs_file_list_t` from a :ref:`mongoc_gridfs_t`, create a :ref:`mongoc_gridfs_file_t` from +a :ref:`mongoc_gridfs_file_list_t`, and create a :ref:`mongoc_stream_t` from a :ref:`mongoc_gridfs_file_t`. + +Each of these objects depends on the object it was created from. Always destroy GridFS objects in the reverse +of the order they were created. The sole exception is that a :ref:`mongoc_gridfs_file_t` need not be destroyed +before the :ref:`mongoc_gridfs_file_list_t` it was created from. + +GridFS bucket objects +--------------------- + +Create :ref:`mongoc_gridfs_bucket_t` with a :ref:`mongoc_database_t` derived from a :ref:`mongoc_client_t`. +The :ref:`mongoc_database_t` is independent from the :ref:`mongoc_gridfs_bucket_t`. But the :ref:`mongoc_client_t` +must outlive the :ref:`mongoc_gridfs_bucket_t`. + +A :ref:`mongoc_stream_t` may be created from the :ref:`mongoc_gridfs_bucket_t`. The :ref:`mongoc_gridfs_bucket_t` +must outlive the :ref:`mongoc_stream_t`. + +Sessions +-------- + +.. include:: /libmongoc/includes/session-lifecycle.txt + +Client Side Encryption +---------------------- + +When configuring a :ref:`mongoc_client_t` for automatic encryption via :ref:`mongoc_client_enable_auto_encryption`, +if a separate key vault client is set in the options (via :ref:`mongoc_auto_encryption_opts_set_keyvault_client`) +the key vault client must outlive the encrypted client. + +When configuring a :ref:`mongoc_client_pool_t` for automatic encryption via :ref:`mongoc_client_pool_enable_auto_encryption`, +if a separate key vault client pool is set in the options (via :ref:`mongoc_auto_encryption_opts_set_keyvault_client_pool`) +the key vault client pool must outlive the encrypted client pool. + +When creating a :ref:`mongoc_client_encryption_t`, the configured key vault client (set via :ref:`mongoc_client_encryption_opts_set_keyvault_client`) +must outlive the :ref:`mongoc_client_encryption_t`. \ No newline at end of file diff --git a/source/libmongoc/api/logging.txt b/source/libmongoc/api/logging.txt new file mode 100644 index 00000000..7d038bf0 --- /dev/null +++ b/source/libmongoc/api/logging.txt @@ -0,0 +1,141 @@ +.. _mongoc_logging: + +======= +Logging +======= + +MongoDB C driver Logging Abstraction + +Synopsis +-------- + +.. code-block:: c + + typedef enum { + MONGOC_LOG_LEVEL_ERROR, + MONGOC_LOG_LEVEL_CRITICAL, + MONGOC_LOG_LEVEL_WARNING, + MONGOC_LOG_LEVEL_MESSAGE, + MONGOC_LOG_LEVEL_INFO, + MONGOC_LOG_LEVEL_DEBUG, + MONGOC_LOG_LEVEL_TRACE, + } mongoc_log_level_t; + + #define MONGOC_ERROR(...) + #define MONGOC_CRITICAL(...) + #define MONGOC_WARNING(...) + #define MONGOC_MESSAGE(...) + #define MONGOC_INFO(...) + #define MONGOC_DEBUG(...) + + typedef void (*mongoc_log_func_t) (mongoc_log_level_t log_level, + const char *log_domain, + const char *message, + void *user_data); + + void + mongoc_log_set_handler (mongoc_log_func_t log_func, void *user_data); + void + mongoc_log (mongoc_log_level_t log_level, + const char *log_domain, + const char *format, + ...) BSON_GNUC_PRINTF (3, 4); + const char * + mongoc_log_level_str (mongoc_log_level_t log_level); + void + mongoc_log_default_handler (mongoc_log_level_t log_level, + const char *log_domain, + const char *message, + void *user_data); + void + mongoc_log_trace_enable (void); + void + mongoc_log_trace_disable (void); + +The MongoDB C driver comes with an abstraction for logging that you can use in your application, +or integrate with an existing logging system. + +Macros +------ + +To make logging a little less painful, various helper macros are provided. See the following example. + +.. code-block:: c + + #undef MONGOC_LOG_DOMAIN + #define MONGOC_LOG_DOMAIN "my-custom-domain" + + MONGOC_WARNING ("An error occurred: %s", strerror (errno)); + +.. _custom_log_handlers: + +Custom Log Handlers +------------------- + +The default log handler prints a timestamp and the log message to ``stdout``, or to ``stderr`` +for warnings, critical messages, and errors. +You can override the handler with ``mongoc_log_set_handler()``. +Your handler function is called in a mutex for thread safety. + +For example, you could register a custom handler to suppress messages at INFO level and below: + +.. code-block:: c + + void + my_logger (mongoc_log_level_t log_level, + const char *log_domain, + const char *message, + void *user_data) + { + /* smaller values are more important */ + if (log_level < MONGOC_LOG_LEVEL_INFO) { + mongoc_log_default_handler (log_level, log_domain, message, user_data); + } + } + + int + main (int argc, char *argv[]) + { + mongoc_log_set_handler (my_logger, NULL); + mongoc_init (); + + /* ... your code ... */ + + mongoc_cleanup (); + return 0; + } + +Note that in the example above ``mongoc_log_set_handler()`` is called before ``mongoc_init()``. +Otherwise, some log traces could not be processed by the log handler. + +To restore the default handler: + +.. code-block:: c + + mongoc_log_set_handler (mongoc_log_default_handler, NULL); + +Disable logging +--------------- + +To disable all logging, including warnings, critical messages and errors, provide an empty log handler: + +.. code-block:: c + + mongoc_log_set_handler (NULL, NULL); + +Tracing +------- + +If compiling your own copy of the MongoDB C driver, consider configuring with ``-DENABLE_TRACING=ON`` +to enable function tracing and hex dumps of network packets to ``STDERR`` and ``STDOUT`` during development +and debugging. + +This is especially useful when debugging what may be going on internally in the driver. + +Trace messages can be enabled and disabled by calling ``mongoc_log_trace_enable()`` and ``mongoc_log_trace_disable()`` + +.. note:: + + Compiling the driver with ``-DENABLE_TRACING=ON`` will affect its performance. Disabling tracing + with ``mongoc_log_trace_disable()`` significantly reduces the overhead, but cannot remove it completely. + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t.txt new file mode 100644 index 00000000..8c4f4ba9 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t.txt @@ -0,0 +1,53 @@ +.. _mongoc_auto_encryption_opts_t: + +============================= +mongoc_auto_encryption_opts_t +============================= + +Options for enabling automatic encryption and decryption for :ref:`in-use-encryption`. + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_auto_encryption_opts_t mongoc_auto_encryption_opts_t; + +.. seealso:: + + | :ref:`in-use-encryption` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_new + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_destroy + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client_pool + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_namespace + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_providers + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_credential_provider_callback + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_schema_map + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_auto_encryption + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_extra + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_tls_opts + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_encrypted_fields_map + /libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_query_analysis + +- :ref:`mongoc_auto_encryption_opts_new` +- :ref:`mongoc_auto_encryption_opts_destroy` +- :ref:`mongoc_auto_encryption_opts_set_keyvault_client` +- :ref:`mongoc_auto_encryption_opts_set_keyvault_client_pool` +- :ref:`mongoc_auto_encryption_opts_set_keyvault_namespace` +- :ref:`mongoc_auto_encryption_opts_set_kms_providers` +- :ref:`mongoc_auto_encryption_opts_set_kms_credential_provider_callback` +- :ref:`mongoc_auto_encryption_opts_set_schema_map` +- :ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption` +- :ref:`mongoc_auto_encryption_opts_set_extra` +- :ref:`mongoc_auto_encryption_opts_set_tls_opts` +- :ref:`mongoc_auto_encryption_opts_set_encrypted_fields_map` +- :ref:`mongoc_auto_encryption_opts_set_bypass_query_analysis` diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_destroy.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_destroy.txt new file mode 100644 index 00000000..c56cda07 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_destroy.txt @@ -0,0 +1,27 @@ +.. _mongoc_auto_encryption_opts_destroy: + +===================================== +mongoc_auto_encryption_opts_destroy() +===================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_destroy (mongoc_auto_encryption_opts_t *opts); + +Destroy a :ref:`mongoc_auto_encryption_opts_t`. + +Parameters +---------- + +- ``opts`` The :ref:`mongoc_auto_encryption_opts_t` to destroy. + +.. seealso:: + + | :ref:`mongoc_auto_encryption_opts_new` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_new.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_new.txt new file mode 100644 index 00000000..6ff7548c --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_new.txt @@ -0,0 +1,44 @@ +.. _mongoc_auto_encryption_opts_new: + +================================= +mongoc_auto_encryption_opts_new() +================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_auto_encryption_opts_t * + mongoc_auto_encryption_opts_new (void) BSON_GNUC_WARN_UNUSED_RESULT; + + +Create a new :ref:`mongoc_auto_encryption_opts_t`. + +Caller must set the required options: + +- :ref:`mongoc_auto_encryption_opts_set_keyvault_namespace` +- :ref:`mongoc_auto_encryption_opts_set_kms_providers` + +Caller may set optionally set the following: + +- :ref:`mongoc_auto_encryption_opts_set_keyvault_client` +- :ref:`mongoc_auto_encryption_opts_set_schema_map` +- :ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption` +- :ref:`mongoc_auto_encryption_opts_set_extra` + +This options struct is used to enable auto encryption with :ref:`mongoc_client_enable_auto_encryption`. + +Returns +------- + +A new :ref:`mongoc_auto_encryption_opts_t`, which must be destroyed with :ref:`mongoc_auto_encryption_opts_destroy`. + +.. seealso:: + + | :ref:`mongoc_auto_encryption_opts_destroy` + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_auto_encryption.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_auto_encryption.txt new file mode 100644 index 00000000..320e3cf8 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_auto_encryption.txt @@ -0,0 +1,30 @@ +.. _mongoc_auto_encryption_opts_set_bypass_auto_encryption: + +======================================================== +mongoc_auto_encryption_opts_set_bypass_auto_encryption() +======================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_bypass_auto_encryption ( + mongoc_auto_encryption_opts_t *opts, bool bypass_auto_encryption); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``bypass_auto_encryption``: A boolean. If true, a :ref:`mongoc_client_t` configured with + :ref:`mongoc_client_enable_auto_encryption` will only perform automatic decryption (not + encryption). + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_query_analysis.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_query_analysis.txt new file mode 100644 index 00000000..087798e3 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_query_analysis.txt @@ -0,0 +1,34 @@ +.. _mongoc_auto_encryption_opts_set_bypass_query_analysis: + +======================================================= +mongoc_auto_encryption_opts_set_bypass_query_analysis() +======================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_bypass_query_analysis ( + mongoc_auto_encryption_opts_t *opts, bool bypass_query_analysis); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``bypass_query_analysis``: A boolean. + + +``bypass_query_analysis`` disables automatic analysis of outgoing commands. +``bypass_query_analysis`` is useful for encrypting indexed fields without the +``crypt_shared`` library or ``mongocryptd`` process. Set +``bypass_query_analysis`` to true to use explicit encryption on indexed fields. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_encrypted_fields_map.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_encrypted_fields_map.txt new file mode 100644 index 00000000..9a5bfd28 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_encrypted_fields_map.txt @@ -0,0 +1,36 @@ +.. _mongoc_auto_encryption_opts_set_encrypted_fields_map: + +====================================================== +mongoc_auto_encryption_opts_set_encrypted_fields_map() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_encrypted_fields_map ( + mongoc_auto_encryption_opts_t *opts, const bson_t *encrypted_fields_map); + +.. versionadded:: 1.22.0 + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``encrypted_fields_map``: A :ref:`bson_t` where keys are collection namespaces and values are encrypted + fields documents. + +Supplying an ``encrypted_fields_map`` provides more security than relying on an ``encryptedFields`` obtained +from the server. It protects against a malicious server advertising a false ``encryptedFields``. + +The schema map does not apply to collections encrypted with: :ref:`Client-Side Field Level Encryption `. +See :ref:`mongoc_auto_encryption_opts_set_schema_map` instead. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_extra.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_extra.txt new file mode 100644 index 00000000..c6ab36ad --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_extra.txt @@ -0,0 +1,69 @@ +.. _mongoc_auto_encryption_opts_set_extra: + +======================================= +mongoc_auto_encryption_opts_set_extra() +======================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_extra (mongoc_auto_encryption_opts_t *opts, + const bson_t *extra); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``extra``: A :ref:`bson_t` of additional options. + +``extra`` is a :ref:`bson_t` containing any of the following optional fields: + +- ``mongocryptdURI`` set to a URI to connect to the mongocryptd process (default is "mongodb://localhost:27020"). +- ``mongocryptdBypassSpawn`` set to true to prevent the driver from spawning the mongocryptd process (default behavior is to spawn). +- ``mongocryptdSpawnPath`` set to a path (with trailing slash) to search for mongocryptd (defaults to empty string and uses default system paths). +- ``mongocryptdSpawnArgs`` set to an array of string arguments to pass to ``mongocryptd`` when spawning (defaults to ``[ "--idleShutdownTimeoutSecs=60" ]``). +- ``cryptSharedLibPath`` - Set a filepath string referring to a ``crypt_shared`` + library file. Unset by default. + + - If not set (the default), ``libmongocrypt`` will attempt to load + ``crypt_shared`` using the host system's default dynamic-library-search + system. + - If set, the given path should identify the ``crypt_shared`` dynamic library + file itself, not the directory that contains it. + - If the given path is a relative path and the first path component is + ``$ORIGIN``, the ``$ORIGIN`` component will be replaced with the absolute + path to the directory containing the ``libmongocrypt`` library in use by the + application. + + .. note:: + + No other ``RPATH`` / ``RUNPATH``-style substitutions are available. + + - If the given path is a relative path, the path will be resolved relative to + the working directory of the operating system process. + - If this option is set and ``libmongocrypt`` fails to load ``crypt_shared`` from the + given filepath, ``libmongocrypt`` will fail to initialize and will not + attempt to search for ``crypt_shared`` in any other locations. + +- ``cryptSharedLibRequired`` - If set to ``true``, and ``libmongocrypt`` fails + to load a ``crypt_shared`` library, initialization of auto-encryption will + fail immediately and will not attempt to spawn ``mongocryptd``. + + If set to ``false`` (the default), ``cryptSharedLibPath`` is not set, *and* + ``libmongocrypt`` fails to load ``crypt_shared``, then ``libmongocrypt`` will + proceed without ``crypt_shared`` and fall back to using ``mongocryptd``. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + + | MongoDB Manual documentation for ``crypt_shared``: `Automatic Encryption Shared Library `_ + + | MongoDB Manual documentation for ``mongocryptd``: `Install and Configure mongocryptd `_ + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client.txt new file mode 100644 index 00000000..2d5aea2e --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client.txt @@ -0,0 +1,36 @@ +.. _mongoc_auto_encryption_opts_set_keyvault_client: + +================================================= +mongoc_auto_encryption_opts_set_keyvault_client() +================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_keyvault_client ( + mongoc_auto_encryption_opts_t *opts, mongoc_client_t *client); + +Set an optional separate :ref:`mongoc_client_t` to use during key lookup for automatic +encryption and decryption. Only applies to automatic encryption on a single-threaded +:ref:`mongoc_client_t`. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_auto_encryption_opts_t`. +- ``client``: A :ref:`mongoc_client_t` to use for key queries. This client should *not* have + automatic encryption enabled, as it will only execute ``find`` commands against the key vault + collection to retrieve keys for automatic encryption and decryption. This ``client`` MUST outlive + any :ref:`mongoc_client_t` which has been enabled to use it through :ref:`mongoc_client_enable_auto_encryption`. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`mongoc_auto_encryption_opts_set_keyvault_client_pool` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client_pool.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client_pool.txt new file mode 100644 index 00000000..681f296e --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client_pool.txt @@ -0,0 +1,36 @@ +.. _mongoc_auto_encryption_opts_set_keyvault_client_pool: + +====================================================== +mongoc_auto_encryption_opts_set_keyvault_client_pool() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_keyvault_client_pool ( + mongoc_auto_encryption_opts_t *opts, mongoc_client_pool_t *pool); + +Set an optional separate :ref:`mongoc_client_pool_t` to use during key lookup for automatic +encryption and decryption. Only applies to automatic encryption on a :ref:`mongoc_client_pool_t`. +It is invalid to set this for automatic encryption on a single-threaded :ref:`mongoc_client_t`. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_auto_encryption_opts_t`. +- ``pool``: A :ref:`mongoc_client_pool_t` to use for key queries. This client pool should *not* have + automatic encryption enabled, as it will only execute ``find`` commands against the key vault collection + to retrieve keys for automatic encryption and decryption. This ``pool`` MUST outlive any :ref:`mongoc_client_pool_t` + which has been enabled to use it through :ref:`mongoc_client_pool_enable_auto_encryption`. + +.. seealso:: + + | :ref:`mongoc_client_pool_enable_auto_encryption` + + | :ref:`mongoc_auto_encryption_opts_set_keyvault_client` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_namespace.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_namespace.txt new file mode 100644 index 00000000..f71f8e77 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_namespace.txt @@ -0,0 +1,30 @@ +.. _mongoc_auto_encryption_opts_set_keyvault_namespace: + +==================================================== +mongoc_auto_encryption_opts_set_keyvault_namespace() +==================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_keyvault_namespace ( + mongoc_auto_encryption_opts_t *opts, const char *db, const char *coll); + +Set the database and collection name of the key vault. The key vault is the specially designated collection containing encrypted data keys for :ref:`in-use-encryption`. + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``db``: A ``const char *`` representing the database name of the key vault collection. +- ``coll``: A ``const char *`` representing the collection name of the key vault collection. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_credential_provider_callback.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_credential_provider_callback.txt new file mode 100644 index 00000000..aa5cbdd4 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_credential_provider_callback.txt @@ -0,0 +1,31 @@ +.. _mongoc_auto_encryption_opts_set_kms_credential_provider_callback: + +================================================================== +mongoc_auto_encryption_opts_set_kms_credential_provider_callback() +================================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_kms_credential_provider_callback( + mongoc_auto_encryption_opts_t *opts, + mongoc_kms_credentials_provider_callback_fn fn, + void *userdata); + +Set the user-provided callback to provide KMS credentials on-demand when they +are needed. + +Parameters +---------- + +- ``opts`` - The options object to update. +- ``fn`` - The provider callback to set on the options object. May be ``NULL`` + to clear the callback. Refer to: + :ref:`mongoc_kms_credentials_provider_callback_fn ` +- ``userdata`` - An arbitrary pointer that will be passed along to the + callback function when it is called by libmongoc. + +.. seealso:: :ref:`mongoc_client_encryption_opts_set_kms_credential_provider_callback` diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_providers.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_providers.txt new file mode 100644 index 00000000..9bfcc709 --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_providers.txt @@ -0,0 +1,95 @@ +.. _mongoc_auto_encryption_opts_set_kms_providers: + +=============================================== +mongoc_auto_encryption_opts_set_kms_providers() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_kms_providers ( + mongoc_auto_encryption_opts_t *opts, const bson_t *kms_providers); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``kms_providers``: A :ref:`bson_t` containing configuration for an external Key Management Service (KMS). + +``kms_providers`` is a BSON document containing configuration for each KMS provider. + +KMS providers are specified as a string of the form ```` or ``:``. +The supported KMS provider types are ``aws``, ``azure``, ``gcp``, ``local``, and ``kmip``. The optional name +enables configuring multiple KMS providers with the same KMS provider type (e.g. ``aws:name1`` and ``aws:name2`` +can refer to different AWS accounts). At least one KMS provider must be specified. + +The format for the KMS provider type ``aws`` is as follows: + +.. code-block:: javascript + + aws: { + accessKeyId: String, + secretAccessKey: String + } + +The format for the KMS provider type ``local`` is as follows: + +.. code-block:: javascript + + local: { + key: <96 byte BSON binary of subtype 0> or String /* The master key used to encrypt/decrypt data keys. May be passed as a base64 encoded string. */ + } + +The format for the KMS provider type ``azure`` is as follows: + +.. code-block:: javascript + + azure: { + tenantId: String, + clientId: String, + clientSecret: String, + identityPlatformEndpoint: Optional /* Defaults to login.microsoftonline.com */ + } + +The format for the KMS provider type ``gcp`` is as follows: + +.. code-block:: javascript + + gcp: { + email: String, + privateKey: byte[] or String, /* May be passed as a base64 encoded string. */ + endpoint: Optional /* Defaults to oauth2.googleapis.com */ + } + +The format for the KMS provider type ``kmip`` is as follows: + +.. code-block:: javascript + + kmip: { + endpoint: String + } + +KMS providers may include an optional name suffix separate with a colon. This enables configuring +multiple KMS providers with the same KMS provider type. Example: + +.. code-block:: javascript + + "aws:name1": { + accessKeyId: String, + secretAccessKey: String + }, + "aws:name2": { + accessKeyId: String, + secretAccessKey: String + } + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_schema_map.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_schema_map.txt new file mode 100644 index 00000000..b07ffc0f --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_schema_map.txt @@ -0,0 +1,66 @@ +.. _mongoc_auto_encryption_opts_set_schema_map: + +============================================ +mongoc_auto_encryption_opts_set_schema_map() +============================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_schema_map (mongoc_auto_encryption_opts_t *opts, + const bson_t *schema_map); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``schema_map``: A :ref:`bson_t` where keys are collection namespaces and values are JSON schemas. + +Supplying a schema map provides more security than relying on JSON Schemas obtained from the server. +It protects against a malicious server advertising a false JSON Schema, which could trick the client +into sending unencrypted data that should be encrypted. + +Schemas supplied in the schema map only apply to configuring automatic encryption for +:ref:`Client-Side Field Level Encryption `. Other validation rules in the JSON schema will not +be enforced by the driver and will result in an error. + +The following is an example of a schema map which configures automatic encryption for the collection +``db.coll``: + +.. code-block:: js + + { + "db.coll": { + "properties": { + "encrypted_string": { + "encrypt": { + "keyId": [ + { + "$binary": { + "base64": "AAAAAAAAAAAAAAAAAAAAAA==", + "subType": "04" + } + } + ], + "bsonType": "string", + "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" + } + } + }, + "bsonType": "object" + } + } + +The schema map does not apply to collections encrypted with: :ref:`Queryable Encryption `. +Use :ref:`mongoc_auto_encryption_opts_set_encrypted_fields_map` instead. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_tls_opts.txt b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_tls_opts.txt new file mode 100644 index 00000000..0088419d --- /dev/null +++ b/source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_tls_opts.txt @@ -0,0 +1,60 @@ +.. _mongoc_auto_encryption_opts_set_tls_opts: + +========================================== +mongoc_auto_encryption_opts_set_tls_opts() +========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_auto_encryption_opts_set_tls_opts ( + mongoc_auto_encryption_opts_t *opts, const bson_t *tls_opts); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_auto_encryption_opts_t` +- ``tls_opts``: A :ref:`bson_t` mapping a Key Management Service (KMS) provider to + a BSON document with TLS options. + +``tls_opts`` is a BSON document of the following form: + +.. code-block:: javascript + + : { + tlsCaFile: Optional + tlsCertificateKeyFile: Optional + tlsCertificateKeyFilePassword: Optional + } + +The KMS providers ``aws``, ``azure``, ``gcp``, and ``kmip`` are supported as keys in the +``tls_opts`` document. They may include an optional name suffix separated with a colon. +Example: ``aws:name2``. + +``tls_opts`` maps the KMS provider name to a BSON document for TLS options. + +The BSON document for TLS options may contain the following keys: + +- ``MONGOC_URI_TLSCERTIFICATEKEYFILE`` +- ``MONGOC_URI_TLSCERTIFICATEKEYFILEPASSWORD`` +- ``MONGOC_URI_TLSCAFILE`` + +.. literalinclude:: /libmongoc/includes/examples/client-side-encryption-doc-snippets.c + :language: c + :caption: Example use + :start-after: BEGIN:mongoc_auto_encryption_opts_set_tls_opts + :end-before: END:mongoc_auto_encryption_opts_set_tls_opts + :dedent: 6 + +See :ref:`mongoc_configuring_tls` for a description of the behavior of these options. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t.txt b/source/libmongoc/api/mongoc_bulk_operation_t.txt new file mode 100644 index 00000000..0230a343 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t.txt @@ -0,0 +1,84 @@ +.. _mongoc_bulk_operation_t: + +======================= +mongoc_bulk_operation_t +======================= + +Bulk Write Operations + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_bulk_operation_t mongoc_bulk_operation_t; + +The opaque type ``mongoc_bulk_operation_t`` provides an abstraction for submitting multiple +write operations as a single batch. + +After adding all of the write operations to the ``mongoc_bulk_operation_t``, call +:ref:`mongoc_bulk_operation_execute` to execute the operation. + +.. warning:: + + It is only valid to call :ref:`mongoc_bulk_operation_execute` once. The ``mongoc_bulk_operation_t`` + must be destroyed afterwards. + +.. seealso:: + + | :ref:`Bulk Write Operations ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete_one + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_destroy + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_execute + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_hint + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_write_concern + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert_with_opts + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_many_with_opts + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one_with_opts + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one_with_opts + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_bypass_document_validation + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_client_session + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_comment + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_hint + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_let + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_many_with_opts + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one + /libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one_with_opts + +- :ref:`mongoc_bulk_operation_delete` +- :ref:`mongoc_bulk_operation_delete_one` +- :ref:`mongoc_bulk_operation_destroy` +- :ref:`mongoc_bulk_operation_execute` +- :ref:`mongoc_bulk_operation_get_hint` +- :ref:`mongoc_bulk_operation_get_write_concern` +- :ref:`mongoc_bulk_operation_insert` +- :ref:`mongoc_bulk_operation_insert_with_opts` +- :ref:`mongoc_bulk_operation_remove` +- :ref:`mongoc_bulk_operation_remove_many_with_opts` +- :ref:`mongoc_bulk_operation_remove_one` +- :ref:`mongoc_bulk_operation_remove_one_with_opts` +- :ref:`mongoc_bulk_operation_replace_one` +- :ref:`mongoc_bulk_operation_replace_one_with_opts` +- :ref:`mongoc_bulk_operation_set_bypass_document_validation` +- :ref:`mongoc_bulk_operation_set_client_session` +- :ref:`mongoc_bulk_operation_set_comment` +- :ref:`mongoc_bulk_operation_set_hint` +- :ref:`mongoc_bulk_operation_set_let` +- :ref:`mongoc_bulk_operation_update` +- :ref:`mongoc_bulk_operation_update_many_with_opts` +- :ref:`mongoc_bulk_operation_update_one` +- :ref:`mongoc_bulk_operation_update_one_with_opts` diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete.txt new file mode 100644 index 00000000..2c86452e --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete.txt @@ -0,0 +1,43 @@ +.. _mongoc_bulk_operation_delete: + +============================== +mongoc_bulk_operation_delete() +============================== + +.. warning:: + .. deprecated:: 0.96.0 + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_bulk_operation_remove` in new code. + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_delete (mongoc_bulk_operation_t *bulk, + const bson_t *selector) + BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_remove); + +Deletes documents as part of a bulk operation. This only queues the operation. To execute +it, call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t`. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + + | :ref:`mongoc_bulk_operation_remove_one_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete_one.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete_one.txt new file mode 100644 index 00000000..2f374833 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete_one.txt @@ -0,0 +1,42 @@ +.. _mongoc_bulk_operation_delete_one: + +================================== +mongoc_bulk_operation_delete_one() +================================== + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_bulk_operation_remove_one` in new code. + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_delete_one (mongoc_bulk_operation_t *bulk, + const bson_t *selector) + BSON_GNUC_DEPRECATED_FOR (mongoc_bulk_operation_remove_one); + +Delete a single document as part of a bulk operation. This only queues the operation. +To execute it, call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t`. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_one_with_opts` + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_destroy.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_destroy.txt new file mode 100644 index 00000000..bd3f5566 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_destroy.txt @@ -0,0 +1,21 @@ +.. _mongoc_bulk_operation_destroy: + +=============================== +mongoc_bulk_operation_destroy() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_destroy (mongoc_bulk_operation_t *bulk); + +Destroys a :ref:`mongoc_bulk_operation_t` and frees the structure. Does nothing if ``bulk`` is NULL. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_execute.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_execute.txt new file mode 100644 index 00000000..f6358c0e --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_execute.txt @@ -0,0 +1,56 @@ +.. _mongoc_bulk_operation_execute: + +=============================== +mongoc_bulk_operation_execute() +=============================== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_bulk_operation_execute (mongoc_bulk_operation_t *bulk, + bson_t *reply, + bson_error_t *error); + +This function executes all operations queued into the bulk operation. Unless ``ordered: false`` +was specified in the ``opts`` passed to :ref:`mongoc_collection_create_bulk_operation_with_opts`, +then forward progress will be stopped upon the first error. + +It is only valid to call :ref:`mongoc_bulk_operation_execute` once. The ``mongoc_bulk_operation_t`` +must be destroyed afterwards. + +.. warning:: + + ``reply`` is always initialized, even upon failure. Callers *must* call :ref:`bson_destroy` to + release this potential allocation. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`mongoc_errors` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +On success, returns the server id used. On failure, returns 0 and sets ``error``. + +A write concern timeout or write concern error is considered a failure. + +The ``reply`` document counts operations and collects error information. See +:ref:`Bulk Write Operations ` for examples. + +.. seealso:: + + | :ref:`Bulk Write Operations ` + + | :ref:`mongoc_bulk_operation_get_hint`, which gets the id of the server used even if the operation failed. + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_hint.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_hint.txt new file mode 100644 index 00000000..f7f32bf8 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_hint.txt @@ -0,0 +1,32 @@ +.. _mongoc_bulk_operation_get_hint: + +================================ +mongoc_bulk_operation_get_hint() +================================ + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_bulk_operation_get_hint (const mongoc_bulk_operation_t *bulk); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. + +Description +----------- + +Retrieves the opaque id of the server used for the operation. + +(The function name includes the old term "hint" for the sake of backward compatibility, +but we now call this number a "server id".) + +This number is zero until the driver actually uses a server in :ref:`mongoc_bulk_operation_execute`. +The server id is the same number as the return value of a successful :ref:`mongoc_bulk_operation_execute`, +so ``mongoc_bulk_operation_get_hint`` is useful mainly in case :ref:`mongoc_bulk_operation_execute` +fails and returns zero. + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_write_concern.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_write_concern.txt new file mode 100644 index 00000000..4273058c --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_write_concern.txt @@ -0,0 +1,29 @@ +.. _mongoc_bulk_operation_get_write_concern: + +========================================= +mongoc_bulk_operation_get_write_concern() +========================================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_write_concern_t * + mongoc_bulk_operation_get_write_concern (const mongoc_bulk_operation_t *bulk); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. + +Description +----------- + +Fetches the write concern to be used for ``bulk``. + +Returns +------- + +A :ref:`mongoc_write_concern_t` that should not be modified or freed. + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert.txt new file mode 100644 index 00000000..e0aa8109 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert.txt @@ -0,0 +1,35 @@ +.. _mongoc_bulk_operation_insert: + +============================== +mongoc_bulk_operation_insert() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_insert (mongoc_bulk_operation_t *bulk, + const bson_t *document); + +Queue an insert of a single document into a bulk operation. The insert is not performed +until :ref:`mongoc_bulk_operation_execute` is called. + +This function is superseded by :ref:`mongoc_bulk_operation_insert_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``document``: A :ref:`bson_t`. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert_with_opts.txt new file mode 100644 index 00000000..ab570be7 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert_with_opts.txt @@ -0,0 +1,39 @@ +.. _mongoc_bulk_operation_insert_with_opts: + +======================================== +mongoc_bulk_operation_insert_with_opts() +======================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_insert_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *document, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +Queue an insert of a single document into a bulk operation. The insert is not performed until +:ref:`mongoc_bulk_operation_execute` is called. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``document``: A :ref:`bson_t`. +- ``error``: An optional location for a :ref:`bson_error_t ` or ``NULL``. + +.. include:: /libmongoc/includes/bulk-insert-opts.txt + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument validation +errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if passed invalid arguments. diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove.txt new file mode 100644 index 00000000..3433d72f --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove.txt @@ -0,0 +1,40 @@ +.. _mongoc_bulk_operation_remove: + +============================== +mongoc_bulk_operation_remove() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_remove (mongoc_bulk_operation_t *bulk, + const bson_t *selector); + +Remove documents as part of a bulk operation. This only queues the operation. To execute +it, call :ref:`mongoc_bulk_operation_execute`. + +This function is superseded by :ref:`mongoc_bulk_operation_remove_one_with_opts` and +:ref:`mongoc_bulk_operation_remove_many_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t`. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_one` + + | :ref:`mongoc_bulk_operation_remove_one_with_opts` + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_many_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_many_with_opts.txt new file mode 100644 index 00000000..ebad8fa0 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_many_with_opts.txt @@ -0,0 +1,46 @@ +.. _mongoc_bulk_operation_remove_many_with_opts: + +============================================= +mongoc_bulk_operation_remove_many_with_opts() +============================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_remove_many_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +Delete documents as part of a bulk operation. This only queues the operation. To execute +it, call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/bulk-remove-many-opts.txt + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument +validation errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if passed invalid arguments. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove` + + | :ref:`mongoc_bulk_operation_remove_one_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one.txt new file mode 100644 index 00000000..5d6f1567 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one.txt @@ -0,0 +1,37 @@ +.. _mongoc_bulk_operation_remove_one: + +================================== +mongoc_bulk_operation_remove_one() +================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_remove_one (mongoc_bulk_operation_t *bulk, + const bson_t *selector); + +Remove a single document as part of a bulk operation. This only queues the operation. +To execute it, call :ref:`mongoc_bulk_operation_execute`. + +This function is superseded by :ref:`mongoc_bulk_operation_remove_one_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_one_with_opts` + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one_with_opts.txt new file mode 100644 index 00000000..fb7fe50b --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one_with_opts.txt @@ -0,0 +1,46 @@ +.. _mongoc_bulk_operation_remove_one_with_opts: + +============================================ +mongoc_bulk_operation_remove_one_with_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_remove_one_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +Remove a single document as part of a bulk operation. This only queues the operation. To +execute it, call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/bulk-remove-one-opts.txt + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument +validation errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if passed invalid arguments. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_one` + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one.txt new file mode 100644 index 00000000..e7c2d21d --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one.txt @@ -0,0 +1,43 @@ +.. _mongoc_bulk_operation_replace_one: + +=================================== +mongoc_bulk_operation_replace_one() +=================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_replace_one (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + bool upsert); + +Replace a single document as part of a bulk operation. This only queues the operation. +To execute it, call :ref:`mongoc_bulk_operation_execute`. + +This function is superseded by :ref:`mongoc_bulk_operation_replace_one_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``document``: A :ref:`bson_t` containing the replacement document. +- ``upsert``: ``true`` if this should be an ``upsert``. + +.. warning:: + + ``document`` may not contain fields with keys containing ``.`` or ``$``. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_replace_one_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one_with_opts.txt new file mode 100644 index 00000000..f3871fd0 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one_with_opts.txt @@ -0,0 +1,52 @@ +.. _mongoc_bulk_operation_replace_one_with_opts: + +============================================= +mongoc_bulk_operation_replace_one_with_opts() +============================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_replace_one_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +Replace a single document as part of a bulk operation. This only queues the operation. +To execute it, call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``document``: A :ref:`bson_t` containing the replacement document. +- ``error``: A :ref:`bson_error_t` any errors that may have occurred. + +.. include:: /libmongoc/includes/bulk-replace-one-opts.txt + +.. warning:: + + ``document`` may not contain fields with keys containing ``.`` or ``$``. + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument +validation errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if passed invalid arguments. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_remove_many_with_opts` + + | :ref:`mongoc_bulk_operation_insert` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_bypass_document_validation.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_bypass_document_validation.txt new file mode 100644 index 00000000..a7bbcf7a --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_bypass_document_validation.txt @@ -0,0 +1,30 @@ +.. _mongoc_bulk_operation_set_bypass_document_validation: + +====================================================== +mongoc_bulk_operation_set_bypass_document_validation() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_set_bypass_document_validation ( + mongoc_bulk_operation_t *bulk, bool bypass); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``bypass``: A boolean. + +Description +----------- + +Will bypass document validation for all operations part of this :ref:`bulk `. + +.. seealso:: + + | :ref:`bulk_operation_bypassing_document_validation` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_client_session.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_client_session.txt new file mode 100644 index 00000000..71256dfa --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_client_session.txt @@ -0,0 +1,31 @@ +.. _mongoc_bulk_operation_set_client_session: + +========================================== +mongoc_bulk_operation_set_client_session() +========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_set_client_session ( + mongoc_bulk_operation_t *bulk, + mongoc_client_session_t *client_session); + +Sets an explicit client session to use for the bulk operation. + +It is an error to use a session for unacknowledged writes. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``client_session``: A :ref:`mongoc_client_session_t`. Must be derived from the same + :ref:`mongoc_client_t` as ``bulk``. + +.. seealso:: + + | :ref:`mongoc_client_start_session` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_comment.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_comment.txt new file mode 100644 index 00000000..ae50c02f --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_comment.txt @@ -0,0 +1,29 @@ +.. _mongoc_bulk_operation_set_comment: + +=================================== +mongoc_bulk_operation_set_comment() +=================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_set_comment ( + mongoc_bulk_operation_t *bulk, const bson_value_t *comment); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``comment``: A :ref:`bson_value_t` specifying the comment to associate with this bulk write. + +Description +----------- + +Assigns a comment to attach to all commands executed as part of this :ref:`bulk `. +The comment will appear in log messages, profiler output, and currentOp output. Comments for write commands +are only supported by MongoDB 4.4+. + +It is prohibited to call this function after adding operations to the :ref:`bulk `. diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_hint.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_hint.txt new file mode 100644 index 00000000..06e66756 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_hint.txt @@ -0,0 +1,34 @@ +.. _mongoc_bulk_operation_set_hint: + +================================ +mongoc_bulk_operation_set_hint() +================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_set_hint (const mongoc_bulk_operation_t *bulk, + uint32_t server_id); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``server_id``: An opaque id identifying the server to use. + +Description +----------- + +Specifies which server to use for the operation. This function has an effect only if called +before :ref:`mongoc_bulk_operation_execute`. + +(The function name includes the old term "hint" for the sake of backward compatibility, but +we now call this number a "server id".) + +Use ``mongoc_bulk_operation_set_hint`` only for building a language driver that wraps the C +Driver. When writing applications in C, leave the server id unset and allow the driver to choose +a suitable server for the bulk operation. + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_let.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_let.txt new file mode 100644 index 00000000..fc16c7ab --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_let.txt @@ -0,0 +1,29 @@ +.. _mongoc_bulk_operation_set_let: + +=============================== +mongoc_bulk_operation_set_let() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_set_let ( + mongoc_bulk_operation_t *bulk, const bson_t *let); + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``let``: A BSON document consisting of any number of parameter names, each followed + by definitions of constants in the MQL Aggregate Expression language. + +Description +----------- + +Defines constants that can be accessed by all update, replace, and delete operations executed +as part of this :ref:`bulk `. + +It is prohibited to call this function after adding operations to the :ref:`bulk `. diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update.txt new file mode 100644 index 00000000..4ab2a6a9 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update.txt @@ -0,0 +1,45 @@ +.. _mongoc_bulk_operation_update: + +============================== +mongoc_bulk_operation_update() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_update (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + bool upsert); + +This function queues an update as part of a bulk operation. This does not execute the operation. +To execute the entirety of the bulk operation call :ref:`mongoc_bulk_operation_execute`. + +``document`` MUST only contain fields whose key starts with ``$``. See the update document +specification for more details. + +This function is superseded by :ref:`mongoc_bulk_operation_update_one_with_opts` and +:ref:`mongoc_bulk_operation_update_many_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which documents to remove. +- ``document``: A :ref:`bson_t` containing the update document. +- ``upsert``: ``true`` if an ``upsert`` should be performed. + +Errors +------ + +Errors are propagated via :ref:`mongoc_bulk_operation_execute`. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_update_one_with_opts` + + | :ref:`mongoc_bulk_operation_update_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_many_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_many_with_opts.txt new file mode 100644 index 00000000..b0e2dcc0 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_many_with_opts.txt @@ -0,0 +1,51 @@ +.. _mongoc_bulk_operation_update_many_with_opts: + +============================================= +mongoc_bulk_operation_update_many_with_opts() +============================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_update_many_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +This function queues an update as part of a bulk operation. This does not execute the +operation. To execute the entirety of the bulk operation call :ref:`mongoc_bulk_operation_execute`. + +.. warning:: + + ``document`` MUST only contain fields whose key starts with ``$``. See the update document + specification for more details. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which documents to remove. +- ``document``: A :ref:`bson_t` containing the update document. +- ``error``: A :ref:`bson_error_t` any errors that may have occurred. + +.. include:: /libmongoc/includes/bulk-update-many-opts.txt + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument validation +errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if there is a server or network error or if passed invalid arguments. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_update_one_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one.txt new file mode 100644 index 00000000..710c7c40 --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one.txt @@ -0,0 +1,42 @@ +.. _mongoc_bulk_operation_update_one: + +================================== +mongoc_bulk_operation_update_one() +================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_bulk_operation_update_one (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + bool upsert); + +This function queues an update as part of a bulk operation. It will only modify a single +document on the MongoDB server. This function does not execute the operation. To execute +the entirety of the bulk operation call :ref:`mongoc_bulk_operation_execute`. + +This function is superseded by :ref:`mongoc_bulk_operation_update_one_with_opts`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``document``: A :ref:`bson_t` containing the update document. +- ``upsert``: ``true`` if an ``upsert`` should be performed. + +.. warning:: + + ``document`` *must only* contain fields whose key starts with ``$``. See the update + document specification for more details. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_update` + + | :ref:`mongoc_bulk_operation_update_one_with_opts` + diff --git a/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one_with_opts.txt b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one_with_opts.txt new file mode 100644 index 00000000..42fd88ad --- /dev/null +++ b/source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one_with_opts.txt @@ -0,0 +1,52 @@ +.. _mongoc_bulk_operation_update_one_with_opts: + +============================================ +mongoc_bulk_operation_update_one_with_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_bulk_operation_update_one_with_opts (mongoc_bulk_operation_t *bulk, + const bson_t *selector, + const bson_t *document, + const bson_t *opts, + bson_error_t *error); /* OUT */ + +This function queues an update as part of a bulk operation. It will only modify a single +document on the MongoDB server. This function does not execute the operation. To execute +the entirety of the bulk operation call :ref:`mongoc_bulk_operation_execute`. + +Parameters +---------- + +- ``bulk``: A :ref:`mongoc_bulk_operation_t`. +- ``selector``: A :ref:`bson_t` that selects which document to remove. +- ``document``: A :ref:`bson_t` containing the update document. +- ``error``: A :ref:`bson_error_t` any errors that may have occurred. + +.. include:: /libmongoc/includes/bulk-update-one-opts.txt + +.. warning:: + + ``document`` *must only* contain fields whose key starts with ``$``. See the update + document specification for more details. + +Errors +------ + +Operation errors are propagated via :ref:`mongoc_bulk_operation_execute`, while argument +validation errors are reported by the ``error`` argument. + +Returns +------- + +Returns true on success, and false if there is a server or network error or if passed invalid arguments. + +.. seealso:: + + | :ref:`mongoc_bulk_operation_update_many_with_opts` + diff --git a/source/libmongoc/api/mongoc_change_stream_t.txt b/source/libmongoc/api/mongoc_change_stream_t.txt new file mode 100644 index 00000000..d6394d14 --- /dev/null +++ b/source/libmongoc/api/mongoc_change_stream_t.txt @@ -0,0 +1,78 @@ +.. _mongoc_change_stream_t: + +====================== +mongoc_change_stream_t +====================== + +Synopsis +-------- + +.. code-block:: c + + #include + + typedef struct _mongoc_change_stream_t mongoc_change_stream_t; + +:ref:`mongoc_change_stream_t` is a handle to a change stream. A collection +change stream can be obtained using :ref:`mongoc_collection_watch`. + +It is recommended to use a :ref:`mongoc_change_stream_t` and its functions instead of a +raw aggregation with a ``$changeStream`` stage. For more information see the `MongoDB Manual Entry on Change Streams +`__. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-collection-watch.c + :language: c + :caption: example-collection-watch.c + +Starting and Resuming +````````````````````` + +All ``watch`` functions accept several options to indicate where a change stream should start returning +changes from: ``resumeAfter``, ``startAfter``, and ``startAtOperationTime``. + +All changes returned by :ref:`mongoc_change_stream_next` include a resume token in the ``_id`` field. +MongoDB 4.2 also includes an additional resume token in each "aggregate" and "getMore" command response, +which points to the end of that response's batch. The current token is automatically cached by libmongoc. +In the event of an error, libmongoc attempts to recreate the change stream starting where it left off +by passing the cached resume token. libmongoc only attempts to resume once, but client applications can +access the cached resume token with :ref:`mongoc_change_stream_get_resume_token` and use it for their own +resume logic by passing it as either the ``resumeAfter`` or ``startAfter`` option. + +Additionally, change streams can start returning changes at an operation time by using the ``startAtOperationTime`` +field. This can be the timestamp returned in the ``operationTime`` field of a command reply. + +``resumeAfter``, ``startAfter``, and ``startAtOperationTime`` are mutually exclusive options. Setting more +than one will result in a server error. + +The following example implements custom resuming logic, persisting the resume token in a file. + +.. literalinclude:: /libmongoc/includes/examples/example-resume.c + :language: c + :caption: example-resume.c + +The following example shows using ``startAtOperationTime`` to synchronize a change stream with another operation. + +.. literalinclude:: /libmongoc/includes/examples/example-start-at-optime.c + :language: c + :caption: example-start-at-optime.c + + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_next + /libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_get_resume_token + /libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_error_document + /libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_destroy + +- :ref:`mongoc_change_stream_next` +- :ref:`mongoc_change_stream_get_resume_token` +- :ref:`mongoc_change_stream_error_document` +- :ref:`mongoc_change_stream_destroy` \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_destroy.txt b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_destroy.txt new file mode 100644 index 00000000..f732bee2 --- /dev/null +++ b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_destroy.txt @@ -0,0 +1,20 @@ +.. _mongoc_change_stream_destroy: + +============================== +mongoc_change_stream_destroy() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_change_stream_destroy (mongoc_change_stream_t *stream); + +Destroys a change stream and associated data. + +Parameters +---------- + +- ``stream``: An allocated :ref:`mongoc_change_stream_t`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_error_document.txt b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_error_document.txt new file mode 100644 index 00000000..57da5ef7 --- /dev/null +++ b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_error_document.txt @@ -0,0 +1,32 @@ +.. _mongoc_change_stream_error_document: + +===================================== +mongoc_change_stream_error_document() +===================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_change_stream_error_document (mongoc_change_stream_t *stream, + bson_error_t *err, + const bson_t **reply); + +Checks if an error has occurred when creating or iterating over a change stream. + +Similar to :ref:`mongoc_cursor_error_document` if the error has occurred +client-side then the ``reply`` will be set to an empty BSON document. If the +error occurred server-side, ``reply`` is set to the server's reply document. + +Parameters +---------- + +- ``stream``: A :ref:`mongoc_change_stream_t`. +- ``err``: An optional location for a :ref:`bson_error_t` or ``NULL``. +- ``reply``: A location for a :ref:`bson_t`. + +Returns +------- +A boolean indicating if there was an error. diff --git a/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_get_resume_token.txt b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_get_resume_token.txt new file mode 100644 index 00000000..7f22e437 --- /dev/null +++ b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_get_resume_token.txt @@ -0,0 +1,39 @@ +.. _mongoc_change_stream_get_resume_token: + +======================================= +mongoc_change_stream_get_resume_token() +======================================= + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_change_stream_get_resume_token (mongoc_change_stream_t *stream); + +This function returns the cached resume token, which may be passed as either the +``resumeAfter`` or ``startAfter`` option of a ``watch`` function to start a new +change stream from the same point. + +Parameters +---------- + +- ``stream``: A :ref:`mongoc_change_stream_t`. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +Returns ``NULL`` if no resume token is available. This is possible if the change +stream has not been iterated and neither ``resumeAfter`` nor ``startAfter`` +options were specified in the ``watch`` function. + +Lifecycle +--------- + +The returned :ref:`bson_t` is valid for the lifetime of ``stream`` and +its data may be updated if :ref:`mongoc_change_stream_next` is called after +this function. The value may be copied to extend its lifetime or preserve the +current resume token. diff --git a/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_next.txt b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_next.txt new file mode 100644 index 00000000..d6e5f8b2 --- /dev/null +++ b/source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_next.txt @@ -0,0 +1,42 @@ +.. _mongoc_change_stream_next: + +=========================== +mongoc_change_stream_next() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_change_stream_next (mongoc_change_stream_t *stream, + const bson_t **bson); + +This function iterates the underlying cursor, setting ``bson`` to the next +document. This will block for a maximum of ``maxAwaitTimeMS`` milliseconds as +specified in the options when created, or the default timeout if omitted. Data +may be returned before the timeout. If no data is returned this function returns +``false``. + +Parameters +---------- + +- ``stream``: A :ref:`mongoc_change_stream_t`. +- ``bson``: The location for the resulting document. + +Returns +------- + +This function returns true if a valid bson document was read from the stream. +Otherwise, false if there was an error or no document was available. + +Errors can be determined with the :ref:`mongoc_change_stream_error_document` +function. + +Lifecycle +--------- + +Similar to :ref:`mongoc_cursor_next` the lifetime of ``bson`` is until the +next call to :ref:`mongoc_change_stream_next`, so it needs to be copied to +extend the lifetime. diff --git a/source/libmongoc/api/mongoc_client_encryption_t.txt b/source/libmongoc/api/mongoc_client_encryption_t.txt new file mode 100644 index 00000000..e9e876ff --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t.txt @@ -0,0 +1,88 @@ +.. _mongoc_client_encryption_t: + +========================== +mongoc_client_encryption_t +========================== + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_t mongoc_client_encryption_t; + + +``mongoc_client_encryption_t`` provides utility functions for :ref:`in-use-encryption`. + +Thread Safety +------------- + +:ref:`mongoc_client_encryption_t` is NOT thread-safe and should only be used in the same +thread as the :ref:`mongoc_client_t` that is configured via :ref:`mongoc_client_encryption_opts_set_keyvault_client`. + +Lifecycle +--------- + +The key vault client, configured via :ref:`mongoc_client_encryption_opts_set_keyvault_client`, +must outlive the :ref:`mongoc_client_encryption_t`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_datakey + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_encrypted_collection + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_delete_key + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_crypt_shared_version + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_keys + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_add_key_alt_name + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_remove_key_alt_name + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key_by_alt_name + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_expression + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_decrypt + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_t + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_t + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_t + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_t + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_t + +- :ref:`mongoc_client_encryption_new` +- :ref:`mongoc_client_encryption_destroy` +- :ref:`mongoc_client_encryption_create_datakey` +- :ref:`mongoc_client_encryption_create_encrypted_collection` +- :ref:`mongoc_client_encryption_rewrap_many_datakey` +- :ref:`mongoc_client_encryption_delete_key` +- :ref:`mongoc_client_encryption_get_crypt_shared_version` +- :ref:`mongoc_client_encryption_get_key` +- :ref:`mongoc_client_encryption_get_keys` +- :ref:`mongoc_client_encryption_add_key_alt_name` +- :ref:`mongoc_client_encryption_remove_key_alt_name` +- :ref:`mongoc_client_encryption_get_key_by_alt_name` +- :ref:`mongoc_client_encryption_encrypt` +- :ref:`mongoc_client_encryption_encrypt_expression` +- :ref:`mongoc_client_encryption_decrypt` +- :ref:`mongoc_client_encryption_datakey_opts_t` +- :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t` +- :ref:`mongoc_client_encryption_encrypt_opts_t` +- :ref:`mongoc_client_encryption_encrypt_range_opts_t` +- :ref:`mongoc_client_encryption_opts_t` + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`mongoc_client_pool_enable_auto_encryption` + + | :ref:`in-use-encryption` for libmongoc + + | The MongoDB Manual for `Client-Side Field Level Encryption `_ + + | The MongoDB Manual for `Queryable Encryption `_ diff --git a/source/libmongoc/api/mongoc_client_encryption_t/.DS_Store b/source/libmongoc/api/mongoc_client_encryption_t/.DS_Store new file mode 100644 index 00000000..ca429368 Binary files /dev/null and b/source/libmongoc/api/mongoc_client_encryption_t/.DS_Store differ diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_add_key_alt_name.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_add_key_alt_name.txt new file mode 100644 index 00000000..fb18670a --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_add_key_alt_name.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_encryption_add_key_alt_name: + +=========================================== +mongoc_client_encryption_add_key_alt_name() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_add_key_alt_name ( + mongoc_client_encryption_t *client_encryption, + const bson_value_t *keyid, + const char *keyaltname, + bson_t *key_doc, + bson_error_t *error); + +Add ``keyaltname`` to the set of alternate names in the key document with UUID ``keyid``. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``keyid``: A UUID (BSON binary subtype 0x04) key ID of the key to add the key alternate name to. +- ``keyaltname``: The key alternate name to add. +- ``key_doc``: Optional. An uninitialized :ref:`bson_t` set to the value of the key document before + addition of the alternate name, or an empty document if the key does not exist. Must be freed by + :ref:`bson_destroy`. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_datakey.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_datakey.txt new file mode 100644 index 00000000..0b0944a5 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_datakey.txt @@ -0,0 +1,50 @@ +.. _mongoc_client_encryption_create_datakey: + +========================================= +mongoc_client_encryption_create_datakey() +========================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_create_datakey ( + mongoc_client_encryption_t *client_encryption, + const char *kms_provider, + const mongoc_client_encryption_datakey_opts_t *opts, + bson_value_t *keyid, + bson_error_t *error); + +Creates a new key document in the key vault collection and sets ``keyid`` to the UUID +of the newly created key if ``keyid`` is not NULL. The new key can be used to configure +automatic encryption (see :ref:`mongoc_client_enable_auto_encryption` and +:ref:`mongoc_client_pool_enable_auto_encryption`) or for explicit encryption (see +:ref:`mongoc_client_encryption_encrypt`). + +The created key document is inserted into the key vault collection (identified via +:ref:`mongoc_client_encryption_opts_set_keyvault_namespace`) with majority write concern. + +``keyid`` is always initialized (even on error). Caller must call :ref:`bson_value_destroy` +on ``keyid`` to free. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``kms_provider``: A string identifying the Key Management Service (KMS) provider used to encrypt + the datakey (e.g. "aws" or "local"). +- ``opts``: A :ref:`mongoc_client_encryption_datakey_opts_t` +- ``keyid``: Optional. An uninitialized :ref:`bson_value_t` set to the UUID (BSON binary subtype 0x04) + of the newly created key. Must be freed by :ref:`bson_value_destroy`. +- ``error``: Optional. A :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_datakey_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_encrypted_collection.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_encrypted_collection.txt new file mode 100644 index 00000000..4cc23f55 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_encrypted_collection.txt @@ -0,0 +1,91 @@ +.. _mongoc_client_encryption_create_encrypted_collection: + +====================================================== +mongoc_client_encryption_create_encrypted_collection() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_collection_t* + mongoc_client_encryption_create_encrypted_collection ( + mongoc_client_encryption_t *enc, + mongoc_database_t *database, + const char *name, + const bson_t *in_options, + bson_t *out_options, + const char *kms_provider, + const bson_t *opt_masterKey, + bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT; + +Create a new collection with :ref:`Queryable Encryption ` +enabled. Requires a valid :ref:`mongoc_client_encryption_t` object to +operate. + +.. seealso:: + + This function is a convenience API wrapping + :ref:`mongoc_database_create_collection`. + + +Parameters +---------- + +- ``enc``: The :ref:`mongoc_client_encryption_t` to be used to configure + encryption for the new collection. +- ``database``: The :ref:`mongoc_database_t` in which the new collection will + be created. +- ``name``: The name of the new collection. +- ``in_options``: The options for the new collection. (See below). +- ``out_options``: An optional output option for the final create-collection + options. Should point to storage for a :ref:`bson_t`. The pointed-to object + must be destroyed by the caller. If ``NULL``, has no effect. +- ``kms_provider``: The name of the KMS provider to use for generating new data + encryption keys for encrypted fields within the collection. +- ``opt_masterKey``: If provided, used as the masterkey option when data + encryption keys need to be created. (See: + :ref:`mongoc_client_encryption_datakey_opts_set_masterkey`) +- ``error``: Optional output parameter pointing to storage for a + :ref:`bson_error_t`. If an error occurs, will be initialized with error + information. + +Returns +------- + +If successful, this function returns a new :ref:`mongoc_collection_t` object. +Upon failure, returns ``NULL`` and initializes ``*error`` with an error +indicating the reason for failure. The returned collection object must be freed +by the caller. + +Creation Options +---------------- + +The ``in_options`` parameter behaves similarly to the ``opts`` parameter for +:ref:`mongoc_database_create_collection`, which accepts the options for the +``create`` MongoDB command +(`Documented here `__). +The ``in_options`` document accepted here is different in one important way: + +The ``$.encryptedFields.fields`` array is *required* by this function, and, +unlike the schema documented for the ``create`` command, accepts a value of +``null`` for the ``keyId`` parameter on each array element. + +This function has the following as-if effect: + +1. A new set of options ``O`` will be created based on ``in_options``. +2. For each element ``F`` in the ``$.encryptedFields.fields`` array of ``O``: + + 1. If ``F`` contains a ``"keyId": null`` element, a new data encryption key + ``K_f`` will be created as-if by calling the + :ref:`mongoc_client_encryption_create_datakey`, using the relevant + arguments that were given to + ``mongoc_client_encryption_create_encrypted_collection``. + 2. The ID of ``K_f`` will be used to replace the ``"keyId": null`` element + within ``F``. + +3. A collection will be created using the options ``O``. +4. If ``out_options`` is not ``NULL``, ``O`` will be written to + ``out_options``. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_destroy.txt new file mode 100644 index 00000000..cf31632b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_destroy.txt @@ -0,0 +1,21 @@ +.. _mongoc_client_encryption_datakey_opts_destroy: + +=============================================== +mongoc_client_encryption_datakey_opts_destroy() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_datakey_opts_destroy (mongoc_client_encryption_datakey_opts_t *opts); + +Frees resources of a :ref:`mongoc_client_encryption_datakey_opts_t` created with +:ref:`mongoc_client_encryption_datakey_opts_new`. Does nothing if ``NULL`` is passed. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_datakey_opts_t`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_new.txt new file mode 100644 index 00000000..5b99270f --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_new.txt @@ -0,0 +1,19 @@ +.. _mongoc_client_encryption_datakey_opts_new: + +=========================================== +mongoc_client_encryption_datakey_opts_new() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_datakey_opts_t * + mongoc_client_encryption_datakey_opts_new (void) BSON_GNUC_WARN_UNUSED_RESULT; + +Returns +------- + +A new :ref:`mongoc_client_encryption_datakey_opts_t` that must be freed with +:ref:`mongoc_client_encryption_datakey_opts_destroy`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keyaltnames.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keyaltnames.txt new file mode 100644 index 00000000..0f4a1d34 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keyaltnames.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_encryption_datakey_opts_set_keyaltnames: + +======================================================= +mongoc_client_encryption_datakey_opts_set_keyaltnames() +======================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_datakey_opts_set_keyaltnames ( + mongoc_client_encryption_datakey_opts_t *opts, + char **keyaltnames, + uint32_t keyaltnames_count); + +Sets a list of alternate name strings that can be used to identify a data key. Key +alternate names must be unique. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_datakey_opts_t` +- ``keyaltnames``: An array of strings. +- ``keyaltnames_count``: The number of strings in ``keyaltnames``. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_opts_set_keyaltname` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keymaterial.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keymaterial.txt new file mode 100644 index 00000000..c92c14e5 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keymaterial.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_encryption_datakey_opts_set_keymaterial: + +======================================================= +mongoc_client_encryption_datakey_opts_set_keymaterial() +======================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_datakey_opts_set_keymaterial ( + mongoc_client_encryption_datakey_opts_t *opts, + const uint8_t *data, + uint32_t len); + +Sets the custom key material to be used by the data key for encryption and decryption. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_datakey_opts_t` +- ``data``: A pointer to the bytes constituting the custom key material. +- ``len``: The length of the bytes constituting the custom key material. + +Description +----------- + +Key material is used to encrypt and decrypt data. If custom key material is not provided, +the key material for the new data key is generated from a cryptographically secure random +device. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_masterkey.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_masterkey.txt new file mode 100644 index 00000000..abc5b0b3 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_masterkey.txt @@ -0,0 +1,73 @@ +.. _mongoc_client_encryption_datakey_opts_set_masterkey: + +===================================================== +mongoc_client_encryption_datakey_opts_set_masterkey() +===================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_datakey_opts_set_masterkey ( + mongoc_client_encryption_datakey_opts_t *opts, const bson_t *masterkey); + +Identifies the masterkey for the Key Management Service (KMS) provider used to encrypt +a new data key. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_datakey_opts_t` +- ``masterkey``: A :ref:`bson_t` document describing the KMS provider specific masterkey. + +Description +----------- + +Setting the masterkey is required when creating a data key with the KMS provider types: +``aws``, ``azure``, ``gcp``, and ``kmip``. + +Setting the masterkey is prohibited with the KMS provider type ``local``. + +The format of ``masterkey`` for the KMS provider type ``aws`` is as follows: + +.. code-block:: javascript + + { + region: String, + key: String, /* The Amazon Resource Name (ARN) to the AWS customer master key (CMK). */ + endpoint: Optional /* An alternate host identifier to send KMS requests to. May include port number. Defaults to "kms..amazonaws.com" */ + } + +The format of ``masterkey`` for the KMS provider type ``azure`` is as follows: + +.. code-block:: javascript + + { + keyVaultEndpoint: String, /* Host with optional port. Example: "example.vault.azure.net". */ + keyName: String, + keyVersion: Optional /* A specific version of the named key, defaults to using the key's primary version. */ + } + +The format of ``masterkey`` for the KMS provider type ``gcp`` is as follows: + +.. code-block:: javascript + + { + projectId: String, + location: String, + keyRing: String, + keyName: String, + keyVersion: Optional, /* A specific version of the named key, defaults to using the key's primary version. */ + endpoint: Optional /* Host with optional port. Defaults to "cloudkms.googleapis.com". */ + } + +The format of ``masterkey`` for the KMS provider type ``kmip`` is as follows: + +.. code-block:: javascript + + { + keyId: Optional, + endpoint: Optional /* Host with optional port. */ + } diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_t.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_t.txt new file mode 100644 index 00000000..7c43a885 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_t.txt @@ -0,0 +1,38 @@ +.. _mongoc_client_encryption_datakey_opts_t: + +======================================= +mongoc_client_encryption_datakey_opts_t +======================================= + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_datakey_opts_t mongoc_client_encryption_datakey_opts_t; + +Used to set options for :ref:`mongoc_client_encryption_create_datakey`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_masterkey + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keyaltnames + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keymaterial + +- :ref:`mongoc_client_encryption_datakey_opts_new` +- :ref:`mongoc_client_encryption_datakey_opts_destroy` +- :ref:`mongoc_client_encryption_datakey_opts_set_masterkey` +- :ref:`mongoc_client_encryption_datakey_opts_set_keyaltnames` +- :ref:`mongoc_client_encryption_datakey_opts_set_keymaterial` + + +.. seealso:: + + | :ref:`mongoc_client_encryption_create_datakey` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_decrypt.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_decrypt.txt new file mode 100644 index 00000000..0c57d684 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_decrypt.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_encryption_decrypt: + +================================== +mongoc_client_encryption_decrypt() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_decrypt (mongoc_client_encryption_t *client_encryption, + const bson_value_t *ciphertext, + bson_value_t *value, + bson_error_t *error); + +Performs explicit decryption. + +``value`` is always initialized (even on failure). Caller must call :ref:`bson_value_destroy` to free. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t` +- ``ciphertext``: The ciphertext (a BSON binary with subtype 6) to decrypt. +- ``value``: A :ref:`bson_value_t` for the resulting decrypted value. +- ``error``: A :ref:`bson_error_t` set on failure. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`mongoc_client_encryption_encrypt` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_delete_key.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_delete_key.txt new file mode 100644 index 00000000..ee695e26 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_delete_key.txt @@ -0,0 +1,37 @@ +.. _mongoc_client_encryption_delete_key: + +===================================== +mongoc_client_encryption_delete_key() +===================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_delete_key ( + mongoc_client_encryption_t *client_encryption, + const bson_value_t *keyid, + bson_t *reply, + bson_error_t *error); + +Delete a key document in the key vault collection that has the given ``keyid``. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``keyid``: The UUID (BSON binary subtype 0x04) of the key to delete. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` + | :ref:`mongoc_client_encryption_create_datakey` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_destroy.txt new file mode 100644 index 00000000..5fca07d3 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_destroy.txt @@ -0,0 +1,22 @@ +.. _mongoc_client_encryption_destroy: + +================================== +mongoc_client_encryption_destroy() +================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_destroy ( + mongoc_client_encryption_t *client_encryption); + +Release all resources associated with ``client_encryption`` and free the structure. Does nothing +if ``client_encryption`` is NULL. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt.txt new file mode 100644 index 00000000..64619095 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt.txt @@ -0,0 +1,64 @@ +.. _mongoc_client_encryption_encrypt: + +================================== +mongoc_client_encryption_encrypt() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_encrypt ( + mongoc_client_encryption_t *client_encryption, + const bson_value_t *value, + mongoc_client_encryption_encrypt_opts_t *opts, + bson_value_t *ciphertext, + bson_error_t *error); + +Performs explicit encryption. + +``ciphertext`` is always initialized (even on failure). Caller must call +:ref:`bson_value_destroy` to free. + +To insert or query with an "Indexed" or "RangePreview" encrypted payload, use a +:ref:`mongoc_client_t` configured with +:ref:`mongoc_auto_encryption_opts_t`. The +:ref:`mongoc_auto_encryption_opts_t` may be configured to bypass query +analysis with :ref:`mongoc_auto_encryption_opts_set_bypass_query_analysis`. +The :ref:`mongoc_auto_encryption_opts_t` must not be configured to bypass +automatic encryption with +:ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. **Note** that +the ``"RangePreview"`` payload type {+is-experimental+}. The {+range-is-experimental+} + +To insert with a ``RangePreview`` payload +:ref:`mongoc_client_encryption_encrypt_range_opts_t` must be set in ``opts``. + +To query with a ``RangePreview`` payload, use :ref:`mongoc_client_encryption_encrypt_expression`. + +**NOTE** that the {+range-is-experimental+} + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t` +- ``value``: The value to encrypt. +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t`. +- ``ciphertext``: A :ref:`bson_value_t` for the resulting ciphertext (a BSON binary with subtype 6). +- ``error``: A :ref:`bson_error_t` set on failure. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_opts_t` + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`mongoc_client_encryption_decrypt` + + | :ref:`mongoc_client_encryption_encrypt_expression` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_expression.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_expression.txt new file mode 100644 index 00000000..e9121576 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_expression.txt @@ -0,0 +1,76 @@ +.. _mongoc_client_encryption_encrypt_expression: + +============================================= +mongoc_client_encryption_encrypt_expression() +============================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_encrypt_expression ( + mongoc_client_encryption_t *client_encryption, + const bson_t *expr, + mongoc_client_encryption_encrypt_opts_t *opts, + bson_t *expr_out, + bson_error_t *error); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + + +Encrypts a Match Expression or Aggregate Expression to query a range index. + +To query with a ``RangePreview`` encrypted payload, use a +:ref:`mongoc_client_t` configured with +:ref:`mongoc_auto_encryption_opts_t`. The +:ref:`mongoc_auto_encryption_opts_t` may be configured to bypass query +analysis with :ref:`mongoc_auto_encryption_opts_set_bypass_query_analysis`. +The :ref:`mongoc_auto_encryption_opts_t` must not be configured to bypass +automatic encryption with +:ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. + +To query with a ``RangePreview`` payload, ``expr`` must be one of the following forms: + +1. A Match Expression of the following form: + + .. code-block:: javascript + + // $gt may also be $gte. $lt may also be $lte. + // Can include one of $gt/$gte/$lt/$lte. It is not required to include both. + {"$and": [{"": {"$gt": ""}}, {"": {"$lt": "" }}]} + +2. An Aggregation Expression of this form: + + .. code-block:: javascript + + // $gt may also be $gte. $lt may also be $lte + // Can include one of $gt/$gte/$lt/$lte. It is not required to include both. + {"$and": [{"$gt": ["", ""]}, {"$lt": ["", ""]}] + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t` +- ``expr``: The expression to encrypt. +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t`. +- ``expr_out``: A :ref:`bson_t` for the resulting encrypted expression. ``expr_out`` is always + initialized (even on failure). Caller must call :ref:`bson_destroy` to free. +- ``error``: A :ref:`bson_error_t` set on failure. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_opts_t` + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`mongoc_client_encryption_decrypt` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_destroy.txt new file mode 100644 index 00000000..8e467d7d --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_destroy.txt @@ -0,0 +1,21 @@ +.. _mongoc_client_encryption_encrypt_opts_destroy: + +=============================================== +mongoc_client_encryption_encrypt_opts_destroy() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_destroy (mongoc_client_encryption_encrypt_opts_t *opts); + +Frees resources of a :ref:`mongoc_client_encryption_encrypt_opts_t` created with +:ref:`mongoc_client_encryption_encrypt_opts_new`. Does nothing if ``NULL`` is passed. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_new.txt new file mode 100644 index 00000000..993b3823 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_new.txt @@ -0,0 +1,19 @@ +.. _mongoc_client_encryption_encrypt_opts_new: + +=========================================== +mongoc_client_encryption_encrypt_opts_new() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_encrypt_opts_t * + mongoc_client_encryption_encrypt_opts_new (void) BSON_GNUC_WARN_UNUSED_RESULT; + +Returns +------- + +A new :ref:`mongoc_client_encryption_encrypt_opts_t` that must be freed with +:ref:`mongoc_client_encryption_encrypt_opts_destroy`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_algorithm.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_algorithm.txt new file mode 100644 index 00000000..363c83f7 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_algorithm.txt @@ -0,0 +1,45 @@ +.. _mongoc_client_encryption_encrypt_opts_set_algorithm: + +===================================================== +mongoc_client_encryption_encrypt_opts_set_algorithm() +===================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_set_algorithm ( + mongoc_client_encryption_encrypt_opts_t *opts, const char *algorithm); + + #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM "AEAD_AES_256_CBC_HMAC_SHA_512-Random" + #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" + // (Experimental: See below) + #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed" + // (Experimental: See below) + #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed" + // (Experimental: See below) + #define MONGOC_ENCRYPT_ALGORITHM_RANGEPREVIEW "RangePreview" + +Identifies the algorithm to use for encryption. Valid values of ``algorithm`` are: + +- ``"AEAD_AES_256_CBC_HMAC_SHA_512-Random"`` for randomized encryption. Specific to the :ref:`csfle` feature. + +- ``"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"`` for deterministic (queryable) encryption. Specific to the :ref:`csfle` feature. + +- ``"Indexed"`` for indexed encryption. Specific to the :ref:`queryable-encryption` feature. + +- ``"Unindexed"`` for unindexed encryption. Specific to the :ref:`queryable-encryption` feature. + +- ``"RangePreview"`` for range encryption. Specific to the :ref:`queryable-encryption` feature. + +.. note:: + + The {+range-is-experimental+} {+opt-is-experimental+} + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``algorithm``: A ``char *`` identifying the algorithm. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_contention_factor.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_contention_factor.txt new file mode 100644 index 00000000..26bb9838 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_contention_factor.txt @@ -0,0 +1,26 @@ +.. _mongoc_client_encryption_encrypt_opts_set_contention_factor: + +============================================================= +mongoc_client_encryption_encrypt_opts_set_contention_factor() +============================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_set_contention_factor ( + mongoc_client_encryption_encrypt_opts_t *opts, int64_t contention_factor); + +Sets a contention factor for explicit encryption. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` +is "Indexed" or "RangePreview". It is an error to set the contention factor when algorithm is not +"Indexed" or "RangePreview". **Note** that the {+range-is-experimental+} If contention factor is +not supplied, it defaults to a value of 0. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``contention_factor``: A non-negative contention factor. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyaltname.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyaltname.txt new file mode 100644 index 00000000..8438865c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyaltname.txt @@ -0,0 +1,30 @@ +.. _mongoc_client_encryption_encrypt_opts_set_keyaltname: + +====================================================== +mongoc_client_encryption_encrypt_opts_set_keyaltname() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_set_keyaltname ( + mongoc_client_encryption_encrypt_opts_t *opts, const char *keyaltname); + +Identifies the data key to use for encryption. This option is mutually exclusive with +:ref:`mongoc_client_encryption_encrypt_opts_set_keyid`. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``keyaltname``: A string identifying a data key by alternate name. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_opts_set_keyid` + + | :ref:`mongoc_client_encryption_datakey_opts_set_keyaltnames` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyid.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyid.txt new file mode 100644 index 00000000..a3bbbad4 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyid.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_encryption_encrypt_opts_set_keyid: + +================================================= +mongoc_client_encryption_encrypt_opts_set_keyid() +================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_set_keyid ( + mongoc_client_encryption_encrypt_opts_t *opts, const bson_value_t *keyid); + +Identifies the data key to use for encryption. This option is mutually exclusive with +:ref:`mongoc_client_encryption_encrypt_opts_set_keyaltname`. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``keyid``: The UUID (BSON binary subtype 0x04) corresponding to the ``_id`` of the data key. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_opts_set_keyaltname` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_query_type.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_query_type.txt new file mode 100644 index 00000000..baaf58bf --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_query_type.txt @@ -0,0 +1,30 @@ +.. _mongoc_client_encryption_encrypt_opts_set_query_type: + +====================================================== +mongoc_client_encryption_encrypt_opts_set_query_type() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + #define MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY "equality" + #define MONGOC_ENCRYPT_QUERY_TYPE_RANGEPREVIEW "rangePreview" + + MONGOC_EXPORT (void) + mongoc_client_encryption_encrypt_opts_set_query_type ( + mongoc_client_encryption_encrypt_opts_t *opts, const char* query_type); + +Sets a query type for explicit encryption. Currently, the supported values +for ``query_type`` are ``"equality"`` and ``"rangePreview"``. **NOTE** that the {+range-is-experimental+} + +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is +"Indexed" or "RangePreview". It is an error to set the query type when algorithm is not "Indexed" +or "RangePreview". + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``query_type``: A query type to use for explicit encryption. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts.txt new file mode 100644 index 00000000..e5faaccd --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts.txt @@ -0,0 +1,33 @@ +.. _mongoc_client_encryption_encrypt_opts_set_range_opts: + +====================================================== +mongoc_client_encryption_encrypt_opts_set_range_opts() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_opts_set_range_opts ( + mongoc_client_encryption_encrypt_opts_t *opts, + const mongoc_client_encryption_encrypt_range_opts_t *range_opts); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Sets the ``range_opts`` for explicit encryption. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is "RangePreview". +It is an error to set ``range_opts`` when algorithm is not "RangePreview". + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_encrypt_opts_t` +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t` + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_new` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_t.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_t.txt new file mode 100644 index 00000000..5cf91d0b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_t.txt @@ -0,0 +1,45 @@ +.. _mongoc_client_encryption_encrypt_opts_t: + +======================================= +mongoc_client_encryption_encrypt_opts_t +======================================= + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_encrypt_opts_t mongoc_client_encryption_encrypt_opts_t; + + +Used to set options for :ref:`mongoc_client_encryption_encrypt`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyid + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyaltname + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_algorithm + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_contention_factor + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_query_type + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts + +- :ref:`mongoc_client_encryption_encrypt_opts_new` +- :ref:`mongoc_client_encryption_encrypt_opts_destroy` +- :ref:`mongoc_client_encryption_encrypt_opts_set_keyid` +- :ref:`mongoc_client_encryption_encrypt_opts_set_keyaltname` +- :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` +- :ref:`mongoc_client_encryption_encrypt_opts_set_contention_factor` +- :ref:`mongoc_client_encryption_encrypt_opts_set_query_type` +- :ref:`mongoc_client_encryption_encrypt_opts_set_range_opts` + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_destroy.txt new file mode 100644 index 00000000..e0c6138f --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_destroy.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_encryption_encrypt_range_opts_destroy: + +===================================================== +mongoc_client_encryption_encrypt_range_opts_destroy() +===================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_range_opts_destroy (mongoc_client_encryption_encrypt_range_opts_t *range_opts); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Frees resources of a :ref:`mongoc_client_encryption_encrypt_range_opts_t` created with +:ref:`mongoc_client_encryption_encrypt_range_opts_new`. Does nothing if ``NULL`` is passed. + +Parameters +---------- + +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t`. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_new.txt new file mode 100644 index 00000000..02760dec --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_new.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_encryption_encrypt_range_opts_new: + +================================================= +mongoc_client_encryption_encrypt_range_opts_new() +================================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_encrypt_range_opts_t * + mongoc_client_encryption_encrypt_range_opts_new (void); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Returns +------- + +A new :ref:`mongoc_client_encryption_encrypt_range_opts_t` that must be freed with +:ref:`mongoc_client_encryption_encrypt_range_opts_destroy`. + + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` + | :ref:`mongoc_client_encryption_encrypt_range_opts_destroy` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_max.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_max.txt new file mode 100644 index 00000000..fc83a546 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_max.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_encryption_encrypt_range_opts_set_max: + +===================================================== +mongoc_client_encryption_encrypt_range_opts_set_max() +===================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_range_opts_set_max ( + mongoc_client_encryption_encrypt_range_opts_t *range_opts, + const bson_value_t *max); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Sets the maximum value of the range for explicit encryption. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is "RangePreview". +It is an error to set maximum when algorithm is not "RangePreview". + +The maximum must match the value set in the encryptedFields of the destination collection. +It is an error to set a different value. + +For double and decimal128 fields, max/max/precision must all be set, or all be unset. + +Parameters +---------- + +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t` +- ``max``: The maximum bson value of the range. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_precision` + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_min` + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_min.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_min.txt new file mode 100644 index 00000000..d0d8a9fa --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_min.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_encryption_encrypt_range_opts_set_min: + +===================================================== +mongoc_client_encryption_encrypt_range_opts_set_min() +===================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_range_opts_set_min ( + mongoc_client_encryption_encrypt_range_opts_t *range_opts, + const bson_value_t *min); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Sets the minimum value of the range for explicit encryption. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is "RangePreview". +It is an error to set minimum when algorithm is not "RangePreview". + +The minimum must match the value set in the encryptedFields of the destination collection. +It is an error to set a different value. + +For double and decimal128 fields, min/max/precision must all be set, or all be unset. + +Parameters +---------- + +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t` +- ``min``: The minimum bson value of the range. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_precision` + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_max` + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_precision.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_precision.txt new file mode 100644 index 00000000..ef495907 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_precision.txt @@ -0,0 +1,43 @@ +.. _mongoc_client_encryption_encrypt_range_opts_set_precision: + +=========================================================== +mongoc_client_encryption_encrypt_range_opts_set_precision() +=========================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_range_opts_set_precision ( + mongoc_client_encryption_encrypt_range_opts_t *range_opts, int32_t precision); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Sets precision for explicit encryption. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is "RangePreview". +It is an error to set precision when algorithm is not "RangePreview". + +Precision can only be set with double or decimal128 fields. +It is an error to set precision if the type of the encryptedFields in the destination collection is not +double or decimal128. + +For double and decimal128 fields, min/max/precision must all be set, or all be unset. + +Precision must match the value set in the encryptedFields of the destination collection. +It is an error to set a different value. + +Parameters +---------- + +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t` +- ``precision``: A non-negative precision. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_min` + | :ref:`mongoc_client_encryption_encrypt_range_opts_set_max` + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_sparsity.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_sparsity.txt new file mode 100644 index 00000000..dd81c231 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_sparsity.txt @@ -0,0 +1,35 @@ +.. _mongoc_client_encryption_encrypt_range_opts_set_sparsity: + +========================================================== +mongoc_client_encryption_encrypt_range_opts_set_sparsity() +========================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_encrypt_range_opts_set_sparsity ( + mongoc_client_encryption_encrypt_range_opts_t *range_opts, int64_t sparsity); + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +Sets sparsity for explicit encryption. Sparsity is required for explicit encryption of range indexes. +Only applies when the algorithm set by :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` is "RangePreview". +It is an error to set sparsity when algorithm is not "RangePreview". + +Sparsity must match the value set in the encryptedFields of the destination collection. +It is an error to set a different value. + +Parameters +---------- + +- ``range_opts``: A :ref:`mongoc_client_encryption_encrypt_range_opts_t` +- ``sparsity``: A non-negative sparsity. + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt_range_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_t.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_t.txt new file mode 100644 index 00000000..216a7aaa --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_t.txt @@ -0,0 +1,52 @@ +.. _mongoc_client_encryption_encrypt_range_opts_t: + +============================================= +mongoc_client_encryption_encrypt_range_opts_t +============================================= + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_encrypt_range_opts_t mongoc_client_encryption_encrypt_range_opts_t; + +.. important:: + + The {+range-is-experimental+} {+api-is-experimental+} + +RangeOpts specifies index options for a Queryable Encryption field supporting "rangePreview" queries. +Used to set options for :ref:`mongoc_client_encryption_encrypt`. + +The options min, max, sparsity, and range must match the values set in the encryptedFields of the +destination collection. + +For double and decimal128 fields, min/max/precision must all be set, or all be unset. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_sparsity + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_min + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_max + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_precision + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts + +- :ref:`mongoc_client_encryption_encrypt_range_opts_new` +- :ref:`mongoc_client_encryption_encrypt_range_opts_destroy` +- :ref:`mongoc_client_encryption_encrypt_range_opts_set_sparsity` +- :ref:`mongoc_client_encryption_encrypt_range_opts_set_min` +- :ref:`mongoc_client_encryption_encrypt_range_opts_set_max` +- :ref:`mongoc_client_encryption_encrypt_range_opts_set_precision` +- :ref:`mongoc_client_encryption_encrypt_opts_set_range_opts` + +.. seealso:: + + | :ref:`mongoc_client_encryption_encrypt` + | :ref:`mongoc_client_encryption_encrypt_opts_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_crypt_shared_version.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_crypt_shared_version.txt new file mode 100644 index 00000000..b5c3e516 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_crypt_shared_version.txt @@ -0,0 +1,38 @@ +.. _mongoc_client_encryption_get_crypt_shared_version: + +=================================================== +mongoc_client_encryption_get_crypt_shared_version() +=================================================== + +Synopsis +-------- + +.. code-block:: c + + const char* + mongoc_client_encryption_get_crypt_shared_version (mongoc_client_encryption_t const *enc) + BSON_GNUC_WARN_UNUSED_RESULT; + +Obtain the version string of the `crypt_shared +`__ that +is loaded for the given explicit encryption object. If no `crypt_shared +`__ library +is loaded, the returned pointer will be ``NULL``. + +Parameters +---------- + +- ``enc``: A live :ref:`mongoc_client_encryption_t` + +Returns +------- + +A pointer to a null-terminated character array string designating the version of +`crypt_shared `__ +that was loaded for ``enc``. If no `crypt_shared `__ +library is loaded, the returned pointer will be ``NULL``. The pointed-to array must not be +modified or freed. The returned pointer is only valid for the lifetime of ``enc``. + +.. seealso:: + + | :ref:`mongoc_client_get_crypt_shared_version` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key.txt new file mode 100644 index 00000000..a4a7d4e9 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key.txt @@ -0,0 +1,36 @@ +.. _mongoc_client_encryption_get_key: + +================================== +mongoc_client_encryption_get_key() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_get_key (mongoc_client_encryption_t *client_encryption, + const bson_value_t *keyid, + bson_t *key_doc, + bson_error_t *error); + +Get a key document in the key vault collection that has the given ``keyid``. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``keyid``: The UUID (BSON binary subtype 0x04) of the key to get. +- ``key_doc``: Optional. An uninitialized :ref:`bson_t` set to the resulting key document, + or an empty document value if the key does not exist. Must be freed by :ref:`bson_destroy`. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key_by_alt_name.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key_by_alt_name.txt new file mode 100644 index 00000000..589de773 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key_by_alt_name.txt @@ -0,0 +1,37 @@ +.. _mongoc_client_encryption_get_key_by_alt_name: + +============================================== +mongoc_client_encryption_get_key_by_alt_name() +============================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_get_key_by_alt_name ( + mongoc_client_encryption_t *client_encryption, + const char *keyaltname, + bson_value_t *key_doc, + bson_error_t *error); + +Get a key document in the key vault collection that has the given ``keyaltname``. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``keyaltname``: The key alternate name of the key to get. +- ``key_doc``: Optional. An uninitialized :ref:`bson_t` set to the resulting key document, or + an empty document if the key does not exist. Must be freed by :ref:`bson_value_destroy`. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_keys.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_keys.txt new file mode 100644 index 00000000..a17e0679 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_keys.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_encryption_get_keys: + +=================================== +mongoc_client_encryption_get_keys() +=================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_client_encryption_get_keys (mongoc_client_encryption_t *client_encryption, + bson_error_t *error); + +Get all the key documents in the key vault collection. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns the result of the internal find command if successful. Returns ``NULL`` and sets +``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_new.txt new file mode 100644 index 00000000..6910a465 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_new.txt @@ -0,0 +1,35 @@ +.. _mongoc_client_encryption_new: + +============================== +mongoc_client_encryption_new() +============================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_t * + mongoc_client_encryption_new (mongoc_client_encryption_opts_t *opts, + bson_error_t *error) BSON_GNUC_WARN_UNUSED_RESULT; + +Create a new :ref:`mongoc_client_encryption_t`. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_opts_t`. +- ``error``: A :ref:`bson_error_t`. + +Returns +------- + +A new :ref:`mongoc_client_encryption_t` that must be freed with :ref:`mongoc_client_encryption_destroy` +if successful. Returns ``NULL`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` + + | :ref:`mongoc_client_encryption_opts_t` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_destroy.txt new file mode 100644 index 00000000..ec267ae0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_destroy.txt @@ -0,0 +1,21 @@ +.. _mongoc_client_encryption_opts_destroy: + +======================================= +mongoc_client_encryption_opts_destroy() +======================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_destroy (mongoc_client_encryption_opts_t *opts); + +Frees resources of a :ref:`mongoc_client_encryption_opts_t` created with :ref:`mongoc_client_encryption_opts_new`. +Does nothing if ``NULL`` is passed. + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_opts_t`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_new.txt new file mode 100644 index 00000000..5d4f4e8b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_new.txt @@ -0,0 +1,18 @@ +.. _mongoc_client_encryption_opts_new: + +=================================== +mongoc_client_encryption_opts_new() +=================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_opts_t * + mongoc_client_encryption_opts_new (void) BSON_GNUC_WARN_UNUSED_RESULT; + +Returns +------- + +A new :ref:`mongoc_client_encryption_opts_t` that must be freed with :ref:`mongoc_client_encryption_opts_destroy`. \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_client.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_client.txt new file mode 100644 index 00000000..21d0821b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_client.txt @@ -0,0 +1,33 @@ +.. _mongoc_client_encryption_opts_set_keyvault_client: + +=================================================== +mongoc_client_encryption_opts_set_keyvault_client() +=================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_set_keyvault_client ( + mongoc_client_encryption_opts_t *opts, + mongoc_client_t *keyvault_client); + +Set the :ref:`mongoc_client_t` to use during key creation and key lookup for encryption +and decryption. This may be either a single-threaded or multi-threaded client (i.e. a +client obtained from a :ref:`mongoc_client_pool_t`). + +Parameters +---------- + +- ``opts``: A :ref:`mongoc_client_encryption_opts_t`. +- ``client``: A :ref:`mongoc_client_t` to use for key lookup and creation. This ``client`` + MUST outlive any :ref:`mongoc_client_encryption_t` configured to use it with :ref:`mongoc_client_encryption_new`. + +.. seealso:: + + | :ref:`mongoc_client_encryption_new` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_namespace.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_namespace.txt new file mode 100644 index 00000000..3bae6115 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_namespace.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_encryption_opts_set_keyvault_namespace: + +====================================================== +mongoc_client_encryption_opts_set_keyvault_namespace() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_set_keyvault_namespace ( + mongoc_client_encryption_opts_t *opts, const char *db, const char *coll); + +Set the database and collection name of the key vault. The key vault is the specially +designated collection containing encrypted data keys for :ref:`in-use-encryption`. + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_client_encryption_opts_t` +- ``db``: The database name of the key vault collection. +- ``coll``: The collection name of the key vault collection. + +.. seealso:: + + | :ref:`mongoc_client_encryption_new` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_credential_provider_callback.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_credential_provider_callback.txt new file mode 100644 index 00000000..71dedac5 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_credential_provider_callback.txt @@ -0,0 +1,64 @@ +.. _mongoc_client_encryption_opts_set_kms_credential_provider_callback: + +==================================================================== +mongoc_client_encryption_opts_set_kms_credential_provider_callback() +==================================================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_set_kms_credential_provider_callback ( + mongoc_client_encryption_opts_t *opts, + mongoc_kms_credentials_provider_callback_fn fn, + void *userdata); + +Set the user-provided callback to provide KMS credentials on-demand when they +are needed. + +Parameters +---------- + +- ``opts`` - The options object to update. +- ``fn`` - The provider callback to set on the options object. May be ``NULL`` + to clear the callback. Refer to: + :ref:`mongoc_kms_credentials_provider_callback_fn ` +- ``userdata`` - An arbitrary pointer that will be passed along to the + callback function when it is called by libmongoc. + +.. seealso:: :ref:`mongoc_auto_encryption_opts_set_kms_credential_provider_callback` + +.. _related_mongoc_kms: + +Related +------- + +.. code-block:: c + + typedef + bool (*mongoc_kms_credentials_provider_callback_fn) (void *userdata, + const bson_t *params, + bson_t *out, + bson_error_t *error); + +The type of a callback function for providing KMS providers data on-demand. + +Parameters +~~~~~~~~~~ + +- ``userdata`` - The same userdata pointer provided to the ``userdata`` + parameter when the callback was set. +- ``params`` - Parameters for the requested KMS credentials. Currently + empty. +- ``out`` - The output :ref:`bson_t` in which to write the new + KMS providers. When passed to the callback, this already points to an + empty BSON document which must be populated. +- ``error`` - An output parameter for indicating any errors that might + occur while generating the KMS credentials. + +Return Value +~~~~~~~~~~~~ + +Must return ``true`` on success, ``false`` on failure. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_providers.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_providers.txt new file mode 100644 index 00000000..8efe1594 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_providers.txt @@ -0,0 +1,96 @@ +.. _mongoc_client_encryption_opts_set_kms_providers: + +================================================= +mongoc_client_encryption_opts_set_kms_providers() +================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_set_kms_providers ( + mongoc_client_encryption_opts_t *opts, const bson_t *kms_providers); + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_client_encryption_opts_t` +- ``kms_providers``: A :ref:`bson_t` containing configuration for an external + Key Management Service (KMS). + +``kms_providers`` is a BSON document containing configuration for each KMS provider. + +KMS providers are specified as a string of the form ```` or +``:``. The supported KMS provider types are ``aws``, +``azure``, ``gcp``, ``local``, and ``kmip``. The optional name enables configuring multiple KMS +providers with the same KMS provider type (e.g. ``aws:name1`` and ``aws:name2`` can refer to +different AWS accounts). At least one KMS provider must be specified. + +The format for the KMS provider type ``aws`` is as follows: + +.. code-block:: javascript + + aws: { + accessKeyId: String, + secretAccessKey: String + } + +The format for the KMS provider type ``local`` is as follows: + +.. code-block:: javascript + + local: { + key: <96 byte BSON binary of subtype 0> or String /* The master key used to encrypt/decrypt data keys. May be passed as a base64 encoded string. */ + } + +The format for the KMS provider type ``azure`` is as follows: + +.. code-block:: javascript + + azure: { + tenantId: String, + clientId: String, + clientSecret: String, + identityPlatformEndpoint: Optional /* Defaults to login.microsoftonline.com */ + } + +The format for the KMS provider type ``gcp`` is as follows: + +.. code-block:: javascript + + gcp: { + email: String, + privateKey: byte[] or String, /* May be passed as a base64 encoded string. */ + endpoint: Optional /* Defaults to oauth2.googleapis.com */ + } + +The format for the KMS provider type ``kmip`` is as follows: + +.. code-block:: javascript + + kmip: { + endpoint: String + } + +KMS providers may include an optional name suffix separate with a colon. This enables configuring +multiple KMS providers with the same KMS provider type. Example: + +.. code-block:: javascript + + "aws:name1": { + accessKeyId: String, + secretAccessKey: String + }, + "aws:name2": { + accessKeyId: String, + secretAccessKey: String + } + +.. seealso:: + + | :ref:`mongoc_client_encryption_new` + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_tls_opts.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_tls_opts.txt new file mode 100644 index 00000000..72e58bbd --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_tls_opts.txt @@ -0,0 +1,60 @@ +.. _mongoc_client_encryption_opts_set_tls_opts: + +============================================ +mongoc_client_encryption_opts_set_tls_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_opts_set_tls_opts ( + mongoc_client_encryption_opts_t *opts, const bson_t *tls_opts); + + +Parameters +---------- + +- ``opts``: The :ref:`mongoc_client_encryption_opts_t` +- ``tls_opts``: A :ref:`bson_t` mapping a Key Management Service (KMS) provider to a + BSON document with TLS options. + +``tls_opts`` is a BSON document of the following form: + +.. code-block:: javascript + + : { + tlsCaFile: Optional + tlsCertificateKeyFile: Optional + tlsCertificateKeyFilePassword: Optional + } + +KMS providers are specified as a string of the form ```` or +``:``. The supported KMS provider types are ``aws``, +``azure``, ``gcp``, ``local``, and ``kmip``. The optional name enables configuring multiple +KMS providers with the same KMS provider type (e.g. ``aws:name1`` and ``aws:name2`` can +refer to different AWS accounts). + +``tls_opts`` maps the KMS provider to a BSON document for TLS options. + +The BSON document for TLS options may contain the following keys: + +- ``MONGOC_URI_TLSCERTIFICATEKEYFILE`` +- ``MONGOC_URI_TLSCERTIFICATEKEYFILEPASSWORD`` +- ``MONGOC_URI_TLSCAFILE`` + +.. literalinclude:: /libmongoc/includes/examples/client-side-encryption-doc-snippets.c + :language: c + :caption: Example use + :start-after: BEGIN:mongoc_client_encryption_opts_set_tls_opts + :end-before: END:mongoc_client_encryption_opts_set_tls_opts + :dedent: 6 + +See :ref:`mongoc_configuring_tls` for a description of the behavior of these options. + +.. seealso:: + + | :ref:`in-use-encryption` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_t.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_t.txt new file mode 100644 index 00000000..ed085ffc --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_t.txt @@ -0,0 +1,42 @@ +.. _mongoc_client_encryption_opts_t: + +=============================== +mongoc_client_encryption_opts_t +=============================== + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_opts_t mongoc_client_encryption_opts_t; + +Used to set options for :ref:`mongoc_client_encryption_new`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_client + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_namespace + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_credential_provider_callback + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_providers + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_tls_opts + +- :ref:`mongoc_client_encryption_opts_new` +- :ref:`mongoc_client_encryption_opts_destroy` +- :ref:`mongoc_client_encryption_opts_set_keyvault_client` +- :ref:`mongoc_client_encryption_opts_set_keyvault_namespace` +- :ref:`mongoc_client_encryption_opts_set_kms_credential_provider_callback` +- :ref:`mongoc_client_encryption_opts_set_kms_providers` +- :ref:`mongoc_client_encryption_opts_set_tls_opts` + +.. seealso:: + + | :ref:`mongoc_client_encryption_new` + diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_remove_key_alt_name.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_remove_key_alt_name.txt new file mode 100644 index 00000000..eb7ef37b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_remove_key_alt_name.txt @@ -0,0 +1,42 @@ +.. _mongoc_client_encryption_remove_key_alt_name: + +============================================== +mongoc_client_encryption_remove_key_alt_name() +============================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_remove_key_alt_name ( + mongoc_client_encryption_t *client_encryption, + const bson_value_t *keyid, + const char *keyaltname, + bson_t *key_doc, + bson_error_t *error); + +Remove ``keyaltname`` from the set of keyAltNames in the key document with UUID ``keyid``. + +Also removes the ``keyAltNames`` field from the key document if it would otherwise be empty. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``keyid``: The UUID (BSON binary subtype 0x04) of the key to remove the key alternate name from. +- ``keyaltname``: The key alternate name to remove. +- ``key_doc``: Optional. An uninitialized :ref:`bson_t` set to the value of the key document before + removal of the key alternate name, or an empty document the key does not exist. Must be freed by + :ref:`bson_value_destroy`. +- ``error``: Optional. :ref:`bson_error_t`. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey.txt new file mode 100644 index 00000000..e57210a2 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey.txt @@ -0,0 +1,52 @@ +.. _mongoc_client_encryption_rewrap_many_datakey: + +============================================== +mongoc_client_encryption_rewrap_many_datakey() +============================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_encryption_rewrap_many_datakey ( + mongoc_client_encryption_t *client_encryption, + const bson_t *filter, + const char *provider, + const bson_t *master_key, + mongoc_client_encryption_rewrap_many_datakey_result_t *result, + bson_error_t *error); + +Rewraps zero or more data keys in the key vault collection that match the +provided ``filter``. + +A ``NULL`` argument for ``filter`` is equivalent to being given an empty +document (match all). + +If ``provider`` is ``NULL``, rewraps matching data keys with their current KMS +provider and master key. + +If ``provider`` is not ``NULL``, rewraps matching data keys with the new KMS +provider as described by ``master_key``. The ``master_key`` document must +conform to the `Client Side Encryption specification +`__. + +Parameters +---------- + +- ``client_encryption``: A :ref:`mongoc_client_encryption_t`. +- ``filter``: The filter to use when finding data keys to rewrap in the key vault collection. +- ``provider``: The new KMS provider to use to encrypt the data keys, or ``NULL`` to use the current KMS provider(s). +- ``master_key``: The master key fields corresponding to the new KMS provider when ``provider`` is not ``NULL``. +- ``result``: An optional :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t`. +- ``error``: A :ref:`bson_error_t` set on failure. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_destroy.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_destroy.txt new file mode 100644 index 00000000..1a8366f8 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_destroy.txt @@ -0,0 +1,23 @@ +.. _mongoc_client_encryption_rewrap_many_datakey_result_destroy: + +============================================================= +mongoc_client_encryption_rewrap_many_datakey_result_destroy() +============================================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_encryption_rewrap_many_datakey_result_destroy ( + mongoc_client_encryption_rewrap_many_datakey_result_t *result); + +Frees resources of a :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t` created +with :ref:`mongoc_client_encryption_rewrap_many_datakey_result_new`. Does nothing if +``NULL`` is passed. + +Parameters +---------- + +- ``result``: A :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t`. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result.txt new file mode 100644 index 00000000..5838d249 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result.txt @@ -0,0 +1,34 @@ +.. _mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result: + +=========================================================================== +mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result() +=========================================================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result ( + mongoc_client_encryption_rewrap_many_datakey_result_t *result) + BSON_GNUC_WARN_UNUSED_RESULT; + +Get the bulk write result set by a successful call to :ref:`mongoc_client_encryption_rewrap_many_datakey`. + +Returns ``NULL`` if no bulk write operation was executed or if the bulk write operation was unacknowledged. + +Parameters +---------- + +- ``result``: A :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t`. + +Returns +------- + +A :ref:`bson_t` that must not be modified or freed if ``result`` is not ``NULL``. Otherwise, returns +``NULL``. + +.. seealso:: + + | :ref:`mongoc_client_encryption_rewrap_many_datakey` diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_new.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_new.txt new file mode 100644 index 00000000..95bb79d7 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_new.txt @@ -0,0 +1,20 @@ +.. _mongoc_client_encryption_rewrap_many_datakey_result_new: + +========================================================= +mongoc_client_encryption_rewrap_many_datakey_result_new() +========================================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_encryption_rewrap_many_datakey_result_t * + mongoc_client_encryption_rewrap_many_datakey_result_new (void) + BSON_GNUC_WARN_UNUSED_RESULT; + +Returns +------- + +A new :ref:`mongoc_client_encryption_rewrap_many_datakey_result_t` that must be freed +with :ref:`mongoc_client_encryption_rewrap_many_datakey_result_destroy`. diff --git a/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_t.txt b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_t.txt new file mode 100644 index 00000000..c02b3710 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_t.txt @@ -0,0 +1,35 @@ +.. _mongoc_client_encryption_rewrap_many_datakey_result_t: + +===================================================== +mongoc_client_encryption_rewrap_many_datakey_result_t +===================================================== + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_encryption_rewrap_many_datakey_result_t + mongoc_client_encryption_rewrap_many_datakey_result_t; + + +Used to access the result of :ref:`mongoc_client_encryption_rewrap_many_datakey`. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_new + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_destroy + /libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result + +- :ref:`mongoc_client_encryption_rewrap_many_datakey_result_new` +- :ref:`mongoc_client_encryption_rewrap_many_datakey_result_destroy` +- :ref:`mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result` + +.. seealso:: + + | :ref:`mongoc_client_encryption_rewrap_many_datakey` diff --git a/source/libmongoc/api/mongoc_client_pool_t.txt b/source/libmongoc/api/mongoc_client_pool_t.txt new file mode 100644 index 00000000..0a2286cc --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t.txt @@ -0,0 +1,64 @@ +.. _mongoc_client_pool_t: + +==================== +mongoc_client_pool_t +==================== + +A connection pool for multi-threaded programs. See :ref:`mongoc_connection_pooling`. + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_pool_t mongoc_client_pool_t + +``mongoc_client_pool_t`` is the basis for multi-threading in the MongoDB C driver. Since +:ref:`mongoc_client_t` structures are not thread-safe, this structure is used to retrieve +a new :ref:`mongoc_client_t` for a given thread. This structure *is thread-safe*, except for +its destructor method, :ref:`mongoc_client_pool_destroy`, which *is not thread-safe* and must +only be called from one thread. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-pool.c + :language: c + :caption: example-pool.c + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_destroy + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_enable_auto_encryption + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_max_size + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_min_size + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new_with_error + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_pop + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_push + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_apm_callbacks + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_appname + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_error_api + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_server_api + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_ssl_opts + /libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_try_pop + +- :ref:`mongoc_client_pool_destroy` +- :ref:`mongoc_client_pool_enable_auto_encryption` +- :ref:`mongoc_client_pool_max_size` +- :ref:`mongoc_client_pool_min_size` +- :ref:`mongoc_client_pool_new` +- :ref:`mongoc_client_pool_new_with_error` +- :ref:`mongoc_client_pool_pop` +- :ref:`mongoc_client_pool_push` +- :ref:`mongoc_client_pool_set_apm_callbacks` +- :ref:`mongoc_client_pool_set_appname` +- :ref:`mongoc_client_pool_set_error_api` +- :ref:`mongoc_client_pool_set_server_api` +- :ref:`mongoc_client_pool_set_ssl_opts` +- :ref:`mongoc_client_pool_try_pop` diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_destroy.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_destroy.txt new file mode 100644 index 00000000..9486af17 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_destroy.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_pool_destroy: + +============================ +mongoc_client_pool_destroy() +============================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_pool_destroy (mongoc_client_pool_t *pool); + +Release all resources associated with ``pool``, including freeing the structure. + +All :ref:`mongoc_client_t` objects obtained from :ref:`mongoc_client_pool_pop` from ``pool`` +must be pushed back onto the pool with :ref:`mongoc_client_pool_push` prior to calling +:ref:`mongoc_client_pool_destroy`. + +This method is NOT thread safe, and must only be called by one thread. It should be called +once the application is shutting down, and after all other threads that use clients have been +joined. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_enable_auto_encryption.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_enable_auto_encryption.txt new file mode 100644 index 00000000..7206d0b2 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_enable_auto_encryption.txt @@ -0,0 +1,55 @@ +.. _mongoc_client_pool_enable_auto_encryption: + +=========================================== +mongoc_client_pool_enable_auto_encryption() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_pool_enable_auto_encryption (mongoc_client_pool_t *pool, + mongoc_auto_encryption_opts_t* opts, + bson_error_t* error); + +Enable automatic client side encryption on a :ref:`mongoc_client_pool_t`. Requires libmongoc +to be built with support for In-Use Encryption. See :ref:`in-use-encryption` for instructions +to enable In-Use Encryption in libmongoc. + +Automatic encryption is an enterprise-only feature that only applies to operations on a collection. +Automatic encryption is not supported for operations on a database or view, and operations that are +not bypassed will result in error. To bypass automatic encryption for all operations, bypass automatic +encryption with :ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption` in ``opts``. + +Automatic encryption requires the authenticated user to have the `listCollections privilege action +`__. + +Enabling automatic encryption reduces the maximum message size and may have a negative performance +impact. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: A required :ref:`mongoc_auto_encryption_opts_t`. +- ``error``: A :ref:`bson_error_t` which is set on error. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise. + +.. seealso:: + + | :ref:`mongoc_auto_encryption_opts_t` + + | :ref:`mongoc_client_enable_auto_encryption` + + | :ref:`in-use-encryption` for libmongoc + + | The MongoDB Manual for `Client-Side Field Level Encryption `__ + + | The MongoDB Manual for `Queryable Encryption `__ + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_max_size.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_max_size.txt new file mode 100644 index 00000000..5576986a --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_max_size.txt @@ -0,0 +1,24 @@ +.. _mongoc_client_pool_max_size: + +============================= +mongoc_client_pool_max_size() +============================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_pool_max_size (mongoc_client_pool_t *pool, + uint32_t max_pool_size); + +This function sets the maximum number of pooled connections available from a :ref:`mongoc_client_pool_t`. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``max_pool_size``: The maximum number of connections which shall be available from the pool. + +.. include:: /libmongoc/includes/mongoc_client_pool_thread_safe.txt diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_min_size.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_min_size.txt new file mode 100644 index 00000000..dc400b53 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_min_size.txt @@ -0,0 +1,37 @@ +.. _mongoc_client_pool_min_size: + +============================= +mongoc_client_pool_min_size() +============================= + +.. warning:: + + This function is deprecated because its behavior does not match what developers expect from + a "minimum pool size", and its actual behavior is likely to hurt performance. + + Applications should not call this function, they should instead accept the default behavior, + which is to keep all idle clients that are pushed into the pool. + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_pool_min_size (mongoc_client_pool_t *pool, + uint32_t min_pool_size) + BSON_GNUC_DEPRECATED; + +This function sets the *maximum* number of idle clients to be kept in the pool. Any idle clients +in excess of the maximum are destroyed. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``min_pool_size``: The number of idle clients to keep in the pool. + +.. include:: /libmongoc/includes/mongoc_client_pool_thread_safe.txt + +Subsequent calls to :ref:`mongoc_client_pool_push` respect the new minimum size, and close the least +recently used :ref:`mongoc_client_t` if the minimum size is exceeded. diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new.txt new file mode 100644 index 00000000..c9b688ed --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_pool_new: + +======================== +mongoc_client_pool_new() +======================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_pool_t * + mongoc_client_pool_new (const mongoc_uri_t *uri) BSON_GNUC_WARN_UNUSED_RESULT; + +This function creates a new :ref:`mongoc_client_pool_t` using the :ref:`mongoc_uri_t` provided. + +Parameters +---------- + +- ``uri``: A :ref:`mongoc_uri_t`. + +Returns +------- + +A newly allocated :ref:`mongoc_client_pool_t` that should be freed with :ref:`mongoc_client_pool_destroy` +when no longer in use. On error, ``NULL`` is returned and an error may be logged. + +.. seealso:: + + | :ref:`mongoc_client_pool_new_with_error` + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new_with_error.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new_with_error.txt new file mode 100644 index 00000000..71b56092 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new_with_error.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_pool_new_with_error: + +=================================== +mongoc_client_pool_new_with_error() +=================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_pool_t * + mongoc_client_pool_new_with_error (const mongoc_uri_t *uri, + bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT; + +This function creates a new :ref:`mongoc_client_pool_t` using the :ref:`mongoc_uri_t` provided. + +Parameters +---------- + +- ``uri``: A :ref:`mongoc_uri_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Returns +------- + +A newly allocated :ref:`mongoc_client_pool_t` that should be freed with :ref:`mongoc_client_pool_destroy` +when no longer in use. On error, ``NULL`` is returned and ``error`` will be populated with the error +description. + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_pop.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_pop.txt new file mode 100644 index 00000000..49240484 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_pop.txt @@ -0,0 +1,35 @@ +.. _mongoc_client_pool_pop: + +======================== +mongoc_client_pool_pop() +======================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_pool_pop (mongoc_client_pool_t *pool) + BSON_GNUC_WARN_UNUSED_RESULT; + +Retrieve a :ref:`mongoc_client_t` from the client pool, or create one. The total number +of clients that can be created from this pool is limited by the URI option "maxPoolSize", +default 100. If this number of clients has been created and all are in use, ``mongoc_client_pool_pop`` +blocks until another thread returns a client with :ref:`mongoc_client_pool_push`. If the +"waitQueueTimeoutMS" URI option was specified with a positive value, then ``mongoc_client_pool_pop`` +will return ``NULL`` when the timeout expires. + +The returned :ref:`mongoc_client_t` must be returned to the pool with :ref:`mongoc_client_pool_push`. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. + +Returns +------- + +A :ref:`mongoc_client_t`. + +.. include:: /libmongoc/includes/mongoc_client_pool_thread_safe.txt diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_push.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_push.txt new file mode 100644 index 00000000..9a55169b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_push.txt @@ -0,0 +1,23 @@ +.. _mongoc_client_pool_push: + +========================= +mongoc_client_pool_push() +========================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_pool_push (mongoc_client_pool_t *pool, mongoc_client_t *client); + +This function returns a :ref:`mongoc_client_t` back to the client pool. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``client``: A :ref:`mongoc_client_t`. + +.. include:: /libmongoc/includes/mongoc_client_pool_thread_safe.txt diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_apm_callbacks.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_apm_callbacks.txt new file mode 100644 index 00000000..66e2fb54 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_apm_callbacks.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_pool_set_apm_callbacks: + +====================================== +mongoc_client_pool_set_apm_callbacks() +====================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_pool_set_apm_callbacks (mongoc_client_pool_t *pool, + mongoc_apm_callbacks_t *callbacks, + void *context); + +Register a set of callbacks to receive Application Performance Monitoring events. + +The ``callbacks`` are copied by the pool and may be destroyed at any time after. If a +``context`` is passed, it is the application's responsibility to ensure ``context`` remains +valid for the lifetime of the pool. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``context``: Optional pointer to include with each event notification. + +Returns +------- + +Returns true on success. If any arguments are invalid, returns false and logs an error. + +.. include:: /libmongoc/includes/mongoc_client_pool_call_once.txt + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_appname.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_appname.txt new file mode 100644 index 00000000..d3b499a2 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_appname.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_pool_set_appname: + +================================ +mongoc_client_pool_set_appname() +================================ + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_pool_set_appname (mongoc_client_pool_t *pool, const char *appname) + +This function is identical to :ref:`mongoc_client_set_appname` except for client pools. + +Also note that :ref:`mongoc_client_set_appname` cannot be called on a client retrieved +from a client pool. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``appname``: The application name, of length at most ``MONGOC_HANDSHAKE_APPNAME_MAX``. + +Returns +------- + +Returns true if appname was set. If appname is too long, returns false and logs an error. + +.. include:: /libmongoc/includes/mongoc_client_pool_call_once.txt diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_error_api.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_error_api.txt new file mode 100644 index 00000000..a460a08a --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_error_api.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_pool_set_error_api: + +================================== +mongoc_client_pool_set_error_api() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_pool_set_error_api (mongoc_client_pool_t *client, + int32_t version); + +Configure how the C Driver reports errors. See :ref:`Setting the Error API version +`. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``version``: The version of the error API, either ``MONGOC_ERROR_API_VERSION_LEGACY`` + or ``MONGOC_ERROR_API_VERSION_2``. + +Returns +------- + +Returns true if the error API version was set, or logs an error message and returns false if +``version`` is invalid. + +.. include:: /libmongoc/includes/mongoc_client_pool_call_once.txt diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_server_api.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_server_api.txt new file mode 100644 index 00000000..a2cad4ed --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_server_api.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_pool_set_server_api: + +=================================== +mongoc_client_pool_set_server_api() +=================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_pool_set_server_api (mongoc_client_pool_t *pool, + const mongoc_server_api_t *api, + bson_error_t *error); + +Set the API version to use for clients created through ``pool``. Once the API version is +set on a pool, it may not be changed to a new value. Attempting to do so will cause this +method to fail and set ``error``. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``api``: A :ref:`mongoc_server_api_t`. +- ``error``: A :ref:`bson_error_t`. + +Returns +------- + +True if the version was successfully set, false if not. On failure, ``error`` will be set. diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_ssl_opts.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_ssl_opts.txt new file mode 100644 index 00000000..31a458bd --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_ssl_opts.txt @@ -0,0 +1,44 @@ +.. _mongoc_client_pool_set_ssl_opts: + +================================= +mongoc_client_pool_set_ssl_opts() +================================= + +Synopsis +-------- + +.. code-block:: c + + #ifdef MONGOC_ENABLE_SSL + void + mongoc_client_pool_set_ssl_opts (mongoc_client_pool_t *pool, + const mongoc_ssl_opt_t *opts); + #endif + +This function is identical to :ref:`mongoc_client_set_ssl_opts` except for +client pools. It ensures that all clients retrieved from +:ref:`mongoc_client_pool_pop` or :ref:`mongoc_client_pool_try_pop` +are configured with the same SSL settings. + +The ``mongoc_ssl_opt_t`` struct is copied by the pool along with the strings +it points to (``pem_file``, ``pem_pwd``, ``ca_file``, ``ca_dir``, and +``crl_file``) so they don't have to remain valid after the call to +``mongoc_client_pool_set_ssl_opts``. + +A call to ``mongoc_client_pool_set_ssl_opts`` overrides all TLS options set +through the connection string with which the ``mongoc_client_pool_t`` was +constructed. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. +- ``opts``: A :ref:`mongoc_ssl_opt_t`. + +.. include:: /libmongoc/includes/mongoc_client_pool_call_once.txt + +Availability +------------ + +This feature requires that the MongoDB C driver was compiled with ``-DENABLE_SSL``. + diff --git a/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_try_pop.txt b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_try_pop.txt new file mode 100644 index 00000000..448d5307 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_try_pop.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_pool_try_pop: + +============================ +mongoc_client_pool_try_pop() +============================ + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_pool_try_pop (mongoc_client_pool_t *pool) + BSON_GNUC_WARN_UNUSED_RESULT; + +This function is identical to :ref:`mongoc_client_pool_pop` except it will return +``NULL`` instead of blocking for a client to become available. + +Parameters +---------- + +- ``pool``: A :ref:`mongoc_client_pool_t`. + +Returns +------- + +A :ref:`mongoc_client_t` if one is immediately available, otherwise ``NULL``. + +.. include:: /libmongoc/includes/mongoc_client_pool_thread_safe.txt diff --git a/source/libmongoc/api/mongoc_client_session_t.txt b/source/libmongoc/api/mongoc_client_session_t.txt new file mode 100644 index 00000000..986e3120 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t.txt @@ -0,0 +1,70 @@ +.. _mongoc_client_session_t: + +======================= +mongoc_client_session_t +======================= + +Use a session for a sequence of operations, optionally with causal consistency. See +`the MongoDB Manual Entry for Causal Consistency `__. + +Synopsis +-------- + +.. include:: /libmongoc/includes/session-lifecycle.txt + +Fork Safety +----------- +A :ref:`mongoc_client_session_t` is only usable in the parent process after a fork. +The child process must call :ref:`mongoc_client_reset` on the ``client`` field. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-session.c + :language: c + :caption: example-session.c + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_start_transaction + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_in_transaction + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_transaction_state + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_commit_transaction + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_abort_transaction + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_cluster_time + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_operation_time + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_append + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_client + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_cluster_time + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_dirty + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_operation_time + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_opts + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_lsid + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_server_id + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_destroy + /libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction_cb_t + +- :ref:`mongoc_client_session_start_transaction` +- :ref:`mongoc_client_session_in_transaction` +- :ref:`mongoc_client_session_get_transaction_state` +- :ref:`mongoc_client_session_commit_transaction` +- :ref:`mongoc_client_session_abort_transaction` +- :ref:`mongoc_client_session_advance_cluster_time` +- :ref:`mongoc_client_session_advance_operation_time` +- :ref:`mongoc_client_session_with_transaction` +- :ref:`mongoc_client_session_append` +- :ref:`mongoc_client_session_get_client` +- :ref:`mongoc_client_session_get_cluster_time` +- :ref:`mongoc_client_session_get_dirty` +- :ref:`mongoc_client_session_get_operation_time` +- :ref:`mongoc_client_session_get_opts` +- :ref:`mongoc_client_session_get_lsid` +- :ref:`mongoc_client_session_get_server_id` +- :ref:`mongoc_client_session_destroy` +- :ref:`mongoc_client_session_with_transaction_cb_t` \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_abort_transaction.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_abort_transaction.txt new file mode 100644 index 00000000..5ccb04c0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_abort_transaction.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_session_abort_transaction: + +========================================= +mongoc_client_session_abort_transaction() +========================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_abort_transaction (mongoc_client_session_t *session, + bson_error_t *error); + + +Abort a multi-document transaction. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Return +------ + +Returns true if the transaction was aborted. Returns ``false`` and sets ``error`` if there +are invalid arguments, such as a session with no transaction in progress. Network or server +errors are ignored. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_cluster_time.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_cluster_time.txt new file mode 100644 index 00000000..454f13bf --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_cluster_time.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_session_advance_cluster_time: + +============================================ +mongoc_client_session_advance_cluster_time() +============================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_session_advance_cluster_time (mongoc_client_session_t *session, + const bson_t *cluster_time); + +Advance the cluster time for a session. Has an effect only if the new cluster time is +greater than the session's current cluster time. + +Use :ref:`mongoc_client_session_advance_operation_time` and :ref:`mongoc_client_session_advance_cluster_time` +to copy the operationTime and clusterTime from another session, ensuring subsequent operations in this +session are causally consistent with the last operation in the other session + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``cluster_time``: The session's new cluster time, as a :ref:`bson_t` like ``{"cluster time": }``. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_operation_time.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_operation_time.txt new file mode 100644 index 00000000..8ddffa35 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_operation_time.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_session_advance_operation_time: + +============================================== +mongoc_client_session_advance_operation_time() +============================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_session_advance_operation_time (mongoc_client_session_t *session, + uint32_t timestamp, + uint32_t increment); + +Advance the session's operation time, expressed as a BSON Timestamp with timestamp and increment +components. Has an effect only if the new operation time is greater than the session's current +operation time. + +Use :ref:`mongoc_client_session_advance_operation_time` and :ref:`mongoc_client_session_advance_cluster_time` +to copy the operationTime and clusterTime from another session, ensuring subsequent operations in this session +are causally consistent with the last operation in the other session. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``timestamp``: The new operationTime's timestamp component. +- ``increment``: The new operationTime's increment component. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_append.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_append.txt new file mode 100644 index 00000000..f36abaee --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_append.txt @@ -0,0 +1,41 @@ +.. _mongoc_client_session_append: + +============================== +mongoc_client_session_append() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_append (const mongoc_client_session_t *client_session, + bson_t *opts, + bson_error_t *error); + +Parameters +---------- + +- ``client_session``: A pointer to a :ref:`mongoc_client_session_t`. +- ``opts``: A pointer to a :ref:`bson_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +This function appends a logical session id to command options. Use it to configure a session +for any function that takes an options document, such as :ref:`mongoc_client_write_command_with_opts`. + +It is an error to use a session for unacknowledged writes. + +Returns +------- + +Returns true on success. If any arguments are invalid, returns false and fills out ``error``. + +Example +------- + +See the example code for :ref:`mongoc_client_session_t`. + diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_commit_transaction.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_commit_transaction.txt new file mode 100644 index 00000000..ea67fce9 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_commit_transaction.txt @@ -0,0 +1,36 @@ +.. _mongoc_client_session_commit_transaction: + +========================================== +mongoc_client_session_commit_transaction() +========================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_commit_transaction (mongoc_client_session_t *session, + bson_t *reply, + bson_error_t *error); + + +Commit a multi-document transaction. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Return +------ + +Returns true if the transaction was committed. Returns ``false`` and sets ``error`` if +there are invalid arguments, such as a session with no transaction in progress, or if there +is a server or network error. + +If a ``reply`` is supplied, it is always initialized and must be freed with :ref:`bson_destroy`. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_destroy.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_destroy.txt new file mode 100644 index 00000000..cdd2fb2b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_destroy.txt @@ -0,0 +1,26 @@ +.. _mongoc_client_session_destroy: + +=============================== +mongoc_client_session_destroy() +=============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_session_destroy (mongoc_client_session_t *session); + +End a session, returning its session id to the pool, and free all client resources associated +with the session. If a multi-document transaction is in progress, abort it. Does nothing if +``session`` is NULL. + +See the example code for :ref:`mongoc_client_session_t`. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_client.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_client.txt new file mode 100644 index 00000000..149f622c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_client.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_session_get_client: + +================================== +mongoc_client_session_get_client() +================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_session_get_client (const mongoc_client_session_t *session); + +Returns the :ref:`mongoc_client_t` from which this session was created. See :ref:`mongoc_client_start_session`. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Returns +------- + +A :ref:`mongoc_client_t` that should not be freed. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_cluster_time.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_cluster_time.txt new file mode 100644 index 00000000..a1f5086e --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_cluster_time.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_session_get_cluster_time: + +======================================== +mongoc_client_session_get_cluster_time() +======================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_client_session_get_cluster_time (const mongoc_client_session_t *session); + +Get the session's clusterTime as a BSON document. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Returns +------- + +If the session has not been used for any operation and :ref:`mongoc_client_session_advance_cluster_time` +has not been called, a :ref:`bson_t` that is valid only for the lifetime of ``session``. Otherwise, +``NULL``. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_dirty.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_dirty.txt new file mode 100644 index 00000000..d45883c5 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_dirty.txt @@ -0,0 +1,33 @@ +.. _mongoc_client_session_get_dirty: + +================================= +mongoc_client_session_get_dirty() +================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_get_dirty (const mongoc_client_session_t *session); + +Indicates whether ``session`` has been marked "dirty" as defined in the `driver sessions specification +`__. + +Parameters +---------- + +- ``session``: A const :ref:`mongoc_client_session_t`. + +Description +----------- + +This function is intended for use by drivers that wrap libmongoc. It is not useful in client applications. + +Returns +------- + +A boolean indicating whether the session has been marked "dirty". + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_lsid.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_lsid.txt new file mode 100644 index 00000000..4596bc4b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_lsid.txt @@ -0,0 +1,28 @@ +.. _mongoc_client_session_get_lsid: + +================================ +mongoc_client_session_get_lsid() +================================ + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_client_session_get_lsid (mongoc_client_session_t *session); + +Get the server-side "logical session ID" associated with this :ref:`mongoc_client_session_t` +as a BSON document. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Returns +------- + +A :ref:`bson_t` that is valid only for the lifetime of ``session``. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_operation_time.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_operation_time.txt new file mode 100644 index 00000000..f20fdf6f --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_operation_time.txt @@ -0,0 +1,28 @@ +.. _mongoc_client_session_get_operation_time: + +========================================== +mongoc_client_session_get_operation_time() +========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_session_get_operation_time (const mongoc_client_session_t *session, + uint32_t *timestamp, + uint32_t *increment); + +Get the session's operationTime, expressed as a BSON Timestamp with timestamp and increment +components. If the session has not been used for any operations, the timestamp and increment +are 0. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``timestamp``: A pointer to a ``uint32_t`` to receive the timestamp component. +- ``increment``: A pointer to a ``uint32_t`` to receive the increment component. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_opts.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_opts.txt new file mode 100644 index 00000000..67256de7 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_opts.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_session_get_opts: + +================================ +mongoc_client_session_get_opts() +================================ + +Synopsis +-------- + +.. code-block:: c + + const mongoc_session_opt_t * + mongoc_client_session_get_opts (const mongoc_client_session_t *session); + +Get a reference to the :ref:`mongoc_session_opt_t` with which this session was configured. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Returns +------- + +A :ref:`mongoc_session_opt_t` that is valid only for the lifetime of ``session``. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_server_id.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_server_id.txt new file mode 100644 index 00000000..6625bbd9 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_server_id.txt @@ -0,0 +1,28 @@ +.. _mongoc_client_session_get_server_id: + +===================================== +mongoc_client_session_get_server_id() +===================================== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_client_session_get_server_id (const mongoc_client_session_t *session); + +Get the "server ID" of the ``mongos`` this :ref:`mongoc_client_session_t` is pinned to. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Returns +------- + +A server ID or ``0`` if this :ref:`mongoc_client_session_t` is not pinned. + +.. include:: /libmongoc/includes/seealso/session.txt + diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_transaction_state.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_transaction_state.txt new file mode 100644 index 00000000..abc40bd4 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_transaction_state.txt @@ -0,0 +1,25 @@ +.. _mongoc_client_session_get_transaction_state: + +============================================= +mongoc_client_session_get_transaction_state() +============================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_transaction_state_t + mongoc_client_session_get_transaction_state (const mongoc_client_session_t *session); + +Returns the current transaction state for this session. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Return +------ + +Returns a :ref:`mongoc_transaction_state_t` that represents the current transaction state. diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_in_transaction.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_in_transaction.txt new file mode 100644 index 00000000..3f8786a3 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_in_transaction.txt @@ -0,0 +1,25 @@ +.. _mongoc_client_session_in_transaction: + +====================================== +mongoc_client_session_in_transaction() +====================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_in_transaction (const mongoc_client_session_t *session); + +Check whether a multi-document transaction is in progress for this session. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. + +Return +------ + +Returns true if a transaction was started and has not been committed or aborted, otherwise ``false``. diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_start_transaction.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_start_transaction.txt new file mode 100644 index 00000000..e5f91222 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_start_transaction.txt @@ -0,0 +1,52 @@ +.. _mongoc_client_session_start_transaction: + +========================================= +mongoc_client_session_start_transaction() +========================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_start_transaction (mongoc_client_session_t *session, + const mongoc_transaction_opt_t *opts, + bson_error_t *error); + + +Start a multi-document transaction for all following operations in this session. Any options +provided in ``opts`` override options passed to :ref:`mongoc_session_opts_set_default_transaction_opts`, +and options inherited from the :ref:`mongoc_client_t`. The ``opts`` argument is copied and can be +freed after calling this function. + +The transaction must be completed with :ref:`mongoc_client_session_commit_transaction` or +:ref:`mongoc_client_session_abort_transaction`. An in-progress transaction is automatically aborted by +:ref:`mongoc_client_session_destroy`. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``opts``: A :ref:`mongoc_transaction_opt_t` or ``NULL``. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Return +------ + +Returns true if the transaction was started. Returns ``false`` and sets ``error`` if there are invalid +arguments, such as a session with a transaction already in progress. + +.. _mongoc_client_session_start_transaction_example: + +Example +------- + +The following example demonstrates how to use :ref:`error labels ` to reliably execute a +multi-document transaction despite network errors and other transient failures. + +.. literalinclude:: /libmongoc/includes/examples/example-transaction.c + :language: c + :caption: example-transaction.c + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction.txt new file mode 100644 index 00000000..086185f6 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction.txt @@ -0,0 +1,59 @@ +.. _mongoc_client_session_with_transaction: + +======================================== +mongoc_client_session_with_transaction() +======================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_session_with_transaction (mongoc_client_session_t *session, + mongoc_client_session_with_transaction_cb_t cb, + const mongoc_transaction_opt_t *opts, + void *ctx, + bson_t *reply, + bson_error_t *error); + +This method will start a new transaction on ``session``, run ``cb``, and then commit +the transaction. If it cannot commit the transaction, the entire sequence may be retried, +and ``cb`` may be run multiple times. ``ctx`` will be passed to ``cb`` each time it is +called. + +This method has an internal time limit of 120 seconds, and will retry until that time limit +is reached. This timeout is not configurable. + +``cb`` should not attempt to start new transactions, but should simply run operations meant +to be contained within a transaction. The ``cb`` does not need to commit transactions; this +is handled by the :ref:`mongoc_client_session_with_transaction`. If ``cb`` does commit or abort +a transaction, however, this method will return without taking further action. + +The parameter ``reply`` is initialized even upon failure to simplify memory management. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``cb``: A :ref:`mongoc_client_session_with_transaction_cb_t` callback, which will run inside + of a new transaction on the session. See example below. +- ``opts``: An optional :ref:`mongoc_transaction_opt_t`. +- ``ctx``: A ``void*``. This user-provided data will be passed to ``cb``. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Return +------ + +Returns ``true`` if the transaction was completed successfully. Otherwise, returns ``false`` in +case of failure. In cases of failure ``error`` will also be set, except if the passed-in ``cb`` +fails without setting ``error``. If a non-NULL ``reply`` is passed in, ``reply`` will be set to +the value of the last server response, except if the passed-in ``cb`` fails without setting a ``reply``. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-with-transaction-cb.c + :language: c + :caption: Use with_transaction() to run a callback within a transaction diff --git a/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction_cb_t.txt b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction_cb_t.txt new file mode 100644 index 00000000..33b78c37 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction_cb_t.txt @@ -0,0 +1,41 @@ +.. _mongoc_client_session_with_transaction_cb_t: + +=========================================== +mongoc_client_session_with_transaction_cb_t +=========================================== + +Synopsis +-------- + +.. code-block:: c + + typedef bool (*mongoc_client_session_with_transaction_cb_t) ( + mongoc_client_session_t *session, + void *ctx, + bson_t **reply, + bson_error_t *error); + +Provide this callback to :ref:`mongoc_client_session_with_transaction`. The callback +should run a sequence of operations meant to be contained within a transaction. The +callback should not attempt to start or commit transactions. + +Parameters +---------- + +- ``session``: A :ref:`mongoc_client_session_t`. +- ``ctx``: A ``void*`` set to the the user-provided ``ctx`` passed to :ref:`mongoc_client_session_with_transaction`. +- ``reply``: An optional location for a :ref:`bson_t` or ``NULL``. The callback should set this if it runs any + operations against the server and receives replies. +- ``error``: A :ref:`bson_error_t`. The callback should set this if it receives any errors while running operations + against the server. + +Return +------ + +Returns ``true`` for success and ``false`` on failure. If ``cb`` returns ``false`` then it should also +set ``error``. + +.. seealso:: + + | :ref:`mongoc_client_session_with_transaction` + diff --git a/source/libmongoc/api/mongoc_client_t.txt b/source/libmongoc/api/mongoc_client_t.txt new file mode 100644 index 00000000..307e5966 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t.txt @@ -0,0 +1,143 @@ +.. _mongoc_client_t: + +=============== +mongoc_client_t +=============== + +A single-threaded MongoDB connection. See :ref:`mongoc_connection_pooling`. + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_client_t mongoc_client_t; + + typedef mongoc_stream_t *(*mongoc_stream_initiator_t) ( + const mongoc_uri_t *uri, + const mongoc_host_list_t *host, + void *user_data, + bson_error_t *error); + +``mongoc_client_t`` is an opaque type that provides access to a MongoDB server, +replica set, or sharded cluster. It maintains management of underlying sockets +and routing to individual nodes based on :ref:`mongoc_read_prefs_t` or :ref:`mongoc_write_concern_t`. + +Streams +------- + +The underlying transport for a given client can be customized, wrapped or replaced by any +implementation that fulfills :ref:`mongoc_stream_t`. A custom transport can be set with +:ref:`mongoc_client_set_stream_initiator`. + +Thread Safety +------------- + +``mongoc_client_t`` is *NOT* thread-safe and should only be used from one thread at a time. +When used in multi-threaded scenarios, it is recommended that you use the thread-safe +:ref:`mongoc_client_pool_t` to retrieve a ``mongoc_client_t`` for your thread. + +Fork Safety +----------- +A :ref:`mongoc_client_t` is only usable in the parent process after a fork. The child process +must call :ref:`mongoc_client_reset`. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-client.c + :language: c + :caption: example-client.c + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_client_t/mongoc_client_command + /libmongoc/api/mongoc_client_t/mongoc_client_command_simple + /libmongoc/api/mongoc_client_t/mongoc_client_command_simple_with_server_id + /libmongoc/api/mongoc_client_t/mongoc_client_command_with_opts + /libmongoc/api/mongoc_client_t/mongoc_client_destroy + /libmongoc/api/mongoc_client_t/mongoc_client_enable_auto_encryption + /libmongoc/api/mongoc_client_t/mongoc_client_find_databases_with_opts + /libmongoc/api/mongoc_client_t/mongoc_client_get_collection + /libmongoc/api/mongoc_client_t/mongoc_client_get_crypt_shared_version + /libmongoc/api/mongoc_client_t/mongoc_client_get_database + /libmongoc/api/mongoc_client_t/mongoc_client_get_database_names + /libmongoc/api/mongoc_client_t/mongoc_client_get_database_names_with_opts + /libmongoc/api/mongoc_client_t/mongoc_client_get_default_database + /libmongoc/api/mongoc_client_t/mongoc_client_get_gridfs + /libmongoc/api/mongoc_client_t/mongoc_client_get_handshake_description + /libmongoc/api/mongoc_client_t/mongoc_client_get_read_concern + /libmongoc/api/mongoc_client_t/mongoc_client_get_read_prefs + /libmongoc/api/mongoc_client_t/mongoc_client_get_server_description + /libmongoc/api/mongoc_client_t/mongoc_client_get_server_descriptions + /libmongoc/api/mongoc_client_t/mongoc_client_get_server_status + /libmongoc/api/mongoc_client_t/mongoc_client_get_uri + /libmongoc/api/mongoc_client_t/mongoc_client_get_write_concern + /libmongoc/api/mongoc_client_t/mongoc_client_new + /libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri + /libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri_with_error + /libmongoc/api/mongoc_client_t/mongoc_client_read_command_with_opts + /libmongoc/api/mongoc_client_t/mongoc_client_read_write_command_with_opts + /libmongoc/api/mongoc_client_t/mongoc_client_reset + /libmongoc/api/mongoc_client_t/mongoc_client_select_server + /libmongoc/api/mongoc_client_t/mongoc_client_set_apm_callbacks + /libmongoc/api/mongoc_client_t/mongoc_client_set_appname + /libmongoc/api/mongoc_client_t/mongoc_client_set_error_api + /libmongoc/api/mongoc_client_t/mongoc_client_set_read_concern + /libmongoc/api/mongoc_client_t/mongoc_client_set_read_prefs + /libmongoc/api/mongoc_client_t/mongoc_client_set_server_api + /libmongoc/api/mongoc_client_t/mongoc_client_set_ssl_opts + /libmongoc/api/mongoc_client_t/mongoc_client_set_stream_initiator + /libmongoc/api/mongoc_client_t/mongoc_client_set_write_concern + /libmongoc/api/mongoc_client_t/mongoc_client_start_session + /libmongoc/api/mongoc_client_t/mongoc_client_watch + /libmongoc/api/mongoc_client_t/mongoc_client_write_command_with_opts + /libmongoc/api/mongoc_client_t/mongoc_handshake_data_append + +- :ref:`mongoc_client_command` +- :ref:`mongoc_client_command_simple` +- :ref:`mongoc_client_command_simple_with_server_id` +- :ref:`mongoc_client_command_with_opts` +- :ref:`mongoc_client_destroy` +- :ref:`mongoc_client_enable_auto_encryption` +- :ref:`mongoc_client_find_databases_with_opts` +- :ref:`mongoc_client_get_collection` +- :ref:`mongoc_client_get_crypt_shared_version` +- :ref:`mongoc_client_get_database` +- :ref:`mongoc_client_get_database_names` +- :ref:`mongoc_client_get_database_names_with_opts` +- :ref:`mongoc_client_get_default_database` +- :ref:`mongoc_client_get_gridfs` +- :ref:`mongoc_client_get_handshake_description` +- :ref:`mongoc_client_get_read_concern` +- :ref:`mongoc_client_get_read_prefs` +- :ref:`mongoc_client_get_server_description` +- :ref:`mongoc_client_get_server_descriptions` +- :ref:`mongoc_client_get_server_status` +- :ref:`mongoc_client_get_uri` +- :ref:`mongoc_client_get_write_concern` +- :ref:`mongoc_client_new` +- :ref:`mongoc_client_new_from_uri` +- :ref:`mongoc_client_new_from_uri_with_error` +- :ref:`mongoc_client_read_command_with_opts` +- :ref:`mongoc_client_read_write_command_with_opts` +- :ref:`mongoc_client_reset` +- :ref:`mongoc_client_select_server` +- :ref:`mongoc_client_set_apm_callbacks` +- :ref:`mongoc_client_set_appname` +- :ref:`mongoc_client_set_error_api` +- :ref:`mongoc_client_set_read_concern` +- :ref:`mongoc_client_set_read_prefs` +- :ref:`mongoc_client_set_server_api` +- :ref:`mongoc_client_set_ssl_opts` +- :ref:`mongoc_client_set_stream_initiator` +- :ref:`mongoc_client_set_write_concern` +- :ref:`mongoc_client_start_session` +- :ref:`mongoc_client_watch` +- :ref:`mongoc_client_write_command_with_opts` +- :ref:`mongoc_handshake_data_append` diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_command.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_command.txt new file mode 100644 index 00000000..5704cca3 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_command.txt @@ -0,0 +1,59 @@ +.. _mongoc_client_command: + +======================= +mongoc_client_command() +======================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_client_command (mongoc_client_t *client, + const char *db_name, + mongoc_query_flags_t flags, + uint32_t skip, + uint32_t limit, + uint32_t batch_size, + const bson_t *query, + const bson_t *fields, + const mongoc_read_prefs_t *read_prefs) + BSON_GNUC_WARN_UNUSED_RESULT; + +This function is superseded by :ref:`mongoc_client_command_with_opts`, :ref:`mongoc_client_read_command_with_opts`, +:ref:`mongoc_client_write_command_with_opts`, and :ref:`mongoc_client_read_write_command_with_opts`. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Description +----------- + +This function creates a cursor which will execute the command when :ref:`mongoc_cursor_next` is +called on it. The client's read preference, read concern, and write concern are not applied to the +command, and :ref:`mongoc_cursor_next` will not check the server response for a write concern error +or write concern timeout. + +If :ref:`mongoc_cursor_next` returns ``false``, then retrieve error details with :ref:`mongoc_cursor_error` +or :ref:`mongoc_cursor_error_document`. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``flags``: Unused. +- ``skip``: Unused. +- ``limit``: Unused. +- ``batch_size``: Unused. +- ``query``: A :ref:`bson_t` containing the command specification. +- ``fields``: Unused. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``. + +Returns +------- + +A :ref:`mongoc_cursor_t`. + +The cursor should be freed with :ref:`mongoc_cursor_destroy`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple.txt new file mode 100644 index 00000000..40c81148 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple.txt @@ -0,0 +1,52 @@ +.. _mongoc_client_command_simple: + +============================== +mongoc_client_command_simple() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_command_simple (mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + bson_t *reply, + bson_error_t *error); + +This is a simplified interface to :ref:`mongoc_client_command`. It returns the first document +from the result cursor into ``reply``. The client's read preference, read concern, and write +concern are not applied to the command. + +.. warning:: + + ``reply`` is always set, and should be released with :ref:`bson_destroy`. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +This function does not check the server response for a write concern error or write concern timeout. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple_with_server_id.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple_with_server_id.txt new file mode 100644 index 00000000..85866fba --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple_with_server_id.txt @@ -0,0 +1,45 @@ +.. _mongoc_client_command_simple_with_server_id: + +============================================= +mongoc_client_command_simple_with_server_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_command_simple_with_server_id ( + mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + uint32_t server_id, + bson_t *reply, + bson_error_t *error); + +This function executes a command on a specific server, using the database +and command specification provided. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. +- ``server_id``: An opaque id specifying which server to use. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or a ``NULL``. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. + +This function does not check the server response for a write concern error or write concern +timeout. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_command_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_with_opts.txt new file mode 100644 index 00000000..317e59bf --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_command_with_opts.txt @@ -0,0 +1,64 @@ +.. _mongoc_client_command_with_opts: + +================================= +mongoc_client_command_with_opts() +================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_command_with_opts ( + mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Execute a command on the server, interpreting ``opts`` according to the MongoDB server +version. To send a raw command to the server without any of this logic, use :ref:`mongoc_client_command_simple`. + + +.. include:: /libmongoc/includes/opts-sources.txt + +``reply`` is always initialized, and must be freed with :ref:`bson_destroy`. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/read-write-opts.txt + +Consult `the MongoDB Manual entry on Database Commands `__ +for each command's arguments. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +The reply is not parsed for a write concern timeout or write concern error. + +Example +------- + +See the example code for :ref:`mongoc_client_read_command_with_opts`. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_destroy.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_destroy.txt new file mode 100644 index 00000000..358dbaab --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_destroy.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_destroy: + +======================= +mongoc_client_destroy() +======================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_destroy (mongoc_client_t *client); + +Release all resources associated with ``client`` and free the structure. Does nothing +if ``client`` is NULL. + +Only call :ref:`mongoc_client_destroy` on a single-threaded client. Do not call on a +:ref:`mongoc_client_t` obtained from a :ref:`mongoc_client_pool_t`, which should instead +be pushed back with :ref:`mongoc_client_pool_push`. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +.. seealso:: + + | :ref:`mongoc_client_pool_push` to push a multi-threaded client back onto a pool. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_enable_auto_encryption.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_enable_auto_encryption.txt new file mode 100644 index 00000000..18e119e9 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_enable_auto_encryption.txt @@ -0,0 +1,56 @@ +.. _mongoc_client_enable_auto_encryption: + +====================================== +mongoc_client_enable_auto_encryption() +====================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_enable_auto_encryption (mongoc_client_t *client, + mongoc_auto_encryption_opts_t* opts, + bson_error_t* error); + +Enable automatic In-Use Encryption on a :ref:`mongoc_client_t`. Requires libmongoc to be +built with support for In-Use Encryption. See :ref:`in-use-encryption` for instructions to +enable In-Use Encryption in libmongoc. + +Automatic encryption is an enterprise only feature that only applies to operations on a collection. +Automatic encryption is not supported for operations on a database or view, and operations that are +not bypassed will result in error. To bypass automatic encryption for all operations, bypass automatic +encryption with :ref:`mongoc_auto_encryption_opts_set_bypass_auto_encryption` in ``opts``. + +Automatic encryption requires the authenticated user to have the `listCollections privilege action +`__. + +Enabling automatic encryption reduces the maximum message size and may have a negative performance impact. + +Only applies to a single-threaded :ref:`mongoc_client_t`. To use with client pools, see +:ref:`mongoc_client_pool_enable_auto_encryption`. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: A required :ref:`mongoc_auto_encryption_opts_t`. +- ``error``: A :ref:`bson_error_t` which is set on error. + +Returns +------- + +True on success. False on error. On error, ``error`` is set. + +.. seealso:: + + | :ref:`mongoc_auto_encryption_opts_t` + + | :ref:`mongoc_client_pool_enable_auto_encryption` + + | :ref:`in-use-encryption` for libmongoc + + | The MongoDB Manual for `Client-Side Field Level Encryption `__ + + | The MongoDB Manual for `Queryable Encryption `__ diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_find_databases_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_find_databases_with_opts.txt new file mode 100644 index 00000000..38b921e0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_find_databases_with_opts.txt @@ -0,0 +1,43 @@ +.. _mongoc_client_find_databases_with_opts: + +======================================== +mongoc_client_find_databases_with_opts() +======================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_client_find_databases_with_opts ( + mongoc_client_t *client, const bson_t *opts) BSON_GNUC_WARN_UNUSED_RESULT; + +Fetches a cursor containing documents, each corresponding to a database on this +MongoDB server. + +.. include:: /libmongoc/includes/retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: A :ref:`bson_t` containing additional options. + +.. include:: /libmongoc/includes/generic-opts.txt + +For a list of all options, see `the MongoDB Manual entry on the listDatabases command +`__. + +Errors +------ + +Use :ref:`mongoc_cursor_error` on the returned cursor to check for errors. + +Returns +------- + +A cursor where each result corresponds to the server's representation of a database. + +The cursor functions :ref:`mongoc_cursor_set_limit`, :ref:`mongoc_cursor_set_batch_size`, and +:ref:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_collection.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_collection.txt new file mode 100644 index 00000000..4313ceb0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_collection.txt @@ -0,0 +1,38 @@ +.. _mongoc_client_get_collection: + +============================== +mongoc_client_get_collection() +============================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_collection_t * + mongoc_client_get_collection (mongoc_client_t *client, + const char *db, + const char *collection) + BSON_GNUC_WARN_UNUSED_RESULT; + +Get a newly allocated :ref:`mongoc_collection_t` for the collection named ``collection`` +in the database named ``db``. + +.. tip:: + + Collections are automatically created on the MongoDB server upon insertion of the first + document. There is no need to create a collection manually. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db``: The name of the database containing the collection. +- ``collection``: The name of the collection. + +Returns +------- + +A newly allocated :ref:`mongoc_collection_t` that should be freed with :ref:`mongoc_collection_destroy` +when no longer in use. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_crypt_shared_version.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_crypt_shared_version.txt new file mode 100644 index 00000000..e0b6caa0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_crypt_shared_version.txt @@ -0,0 +1,39 @@ +.. _mongoc_client_get_crypt_shared_version: + +======================================== +mongoc_client_get_crypt_shared_version() +======================================== + +Synopsis +-------- + +.. code-block:: c + + const char * + mongoc_client_get_crypt_shared_version (const mongoc_client_t *client) + BSON_GNUC_WARN_UNUSED_RESULT; + +Obtain the version string of the :manual:`crypt_shared ` +that is loaded for auto-encryption on the given ``client``. If no :manual:`crypt_shared +` library is loaded, the returned pointer +will be ``NULL``. + +Parameters +---------- + +- ``client``: A live :ref:`mongoc_client_t` + +Returns +------- + +A pointer to a null-terminated character array string designating the version of +:manual:`crypt_shared ` that was +loaded for auto-encryption with ``client``. If no :manual:`crypt_shared +` library is loaded, or auto-encryption +is not loaded for the given ``client``, the returned pointer will be ``NULL``. The pointed-to +array must not be modified or freed. The returned pointer is only valid for the lifetime of +``client``. + +.. seealso:: + + | :ref:`mongoc_client_encryption_get_crypt_shared_version` diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database.txt new file mode 100644 index 00000000..1f17d886 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database.txt @@ -0,0 +1,34 @@ +.. _mongoc_client_get_database: + +============================ +mongoc_client_get_database() +============================ + +Synopsis +-------- + +.. code-block:: c + + mongoc_database_t * + mongoc_client_get_database (mongoc_client_t *client, + const char *name) BSON_GNUC_WARN_UNUSED_RESULT; + +Get a newly allocated :ref:`mongoc_database_t` for the database named ``name``. + +.. tip:: + + Databases are automatically created on the MongoDB server upon insertion of the first + document into a collection. There is no need to create a database manually. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``name``: The name of the database. + +Returns +------- + +A newly allocated :ref:`mongoc_database_t ` that should be freed with +:ref:`mongoc_database_destroy` when no longer in use. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names.txt new file mode 100644 index 00000000..e2fc6f95 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names.txt @@ -0,0 +1,47 @@ +.. _mongoc_client_get_database_names: + +================================== +mongoc_client_get_database_names() +================================== + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_client_get_database_names_with_opts` in new code. + +Synopsis +-------- + +.. code-block:: c + + char ** + mongoc_client_get_database_names (mongoc_client_t *client, bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT + BSON_GNUC_DEPRECATED_FOR (mongoc_client_get_database_names_with_opts); + +Description +----------- + +This function queries the MongoDB server for a list of known databases. + +.. include:: /libmongoc/includes/retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +A ``NULL`` terminated vector of ``NULL-byte`` terminated strings. The result should be freed +with :ref:`bson_strfreev`. + +``NULL`` is returned upon failure and ``error`` is set. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names_with_opts.txt new file mode 100644 index 00000000..cc0a65d4 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names_with_opts.txt @@ -0,0 +1,65 @@ +.. _mongoc_client_get_database_names_with_opts: + +============================================ +mongoc_client_get_database_names_with_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + char ** + mongoc_client_get_database_names_with_opts (mongoc_client_t *client, + const bson_t *opts, + bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT; + +This function queries the MongoDB server for a list of known databases. + +.. include:: /libmongoc/includes/retryable-read.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/generic-opts.txt + +For a list of all options, see `the MongoDB Manual entry on the listDatabases command +`__. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +A ``NULL`` terminated vector of ``NULL-byte`` terminated strings. The result should be freed +with :ref:`bson_strfreev`. + +``NULL`` is returned upon failure and ``error`` is set. + +Examples +-------- + +.. code-block:: c + + { + bson_error_t error; + char **strv; + unsigned i; + + if ((strv = mongoc_client_get_database_names_with_opts (client, NULL, &error))) { + for (i = 0; strv[i]; i++) + printf ("%s\n", strv[i]); + bson_strfreev (strv); + } else { + fprintf (stderr, "Command failed: %s\n", error.message); + } + } + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_default_database.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_default_database.txt new file mode 100644 index 00000000..4d82430c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_default_database.txt @@ -0,0 +1,53 @@ +.. _mongoc_client_get_default_database: + +==================================== +mongoc_client_get_default_database() +==================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_database_t * + mongoc_client_get_default_database (mongoc_client_t *client) + BSON_GNUC_WARN_UNUSED_RESULT; + +Get the database named in the MongoDB connection URI, or ``NULL`` if the URI specifies none. + +Useful when you want to choose which database to use based only on the URI in a configuration file. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +Returns +------- + +A newly allocated :ref:`mongoc_database_t ` that should be freed with +:ref:`mongoc_database_destroy`. + +Example +------- + +.. code-block:: c + :caption: Default Database Example + + /* default database is "db_name" */ + mongoc_client_t *client = mongoc_client_new ("mongodb://host/db_name"); + mongoc_database_t *db = mongoc_client_get_default_database (client); + + assert (!strcmp ("db_name", mongoc_database_get_name (db))); + + mongoc_database_destroy (db); + mongoc_client_destroy (client); + + /* no default database */ + client = mongoc_client_new ("mongodb://host/"); + db = mongoc_client_get_default_database (client); + + assert (!db); + + mongoc_client_destroy (client); + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_gridfs.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_gridfs.txt new file mode 100644 index 00000000..07512e3d --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_gridfs.txt @@ -0,0 +1,40 @@ +.. _mongoc_client_get_gridfs: + +========================== +mongoc_client_get_gridfs() +========================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_gridfs_t * + mongoc_client_get_gridfs (mongoc_client_t *client, + const char *db, + const char *prefix, + bson_error_t *error) BSON_GNUC_WARN_UNUSED_RESULT; + +The ``mongoc_client_get_gridfs()`` function shall create a new :ref:`mongoc_gridfs_t`. +The ``db`` parameter is the name of the database which the gridfs instance should exist in. +The ``prefix`` parameter corresponds to the gridfs collection namespacing; its default is +"fs", thus the default GridFS collection names are "fs.files" and "fs.chunks". + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db``: The database name. +- ``prefix``: Optional prefix for gridfs collection names or ``NULL``. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +On success, returns a :ref:`mongoc_gridfs_t` you must free with :ref:`mongoc_gridfs_destroy`. +Returns ``NULL`` upon failure and sets ``error``. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_handshake_description.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_handshake_description.txt new file mode 100644 index 00000000..e3665a28 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_handshake_description.txt @@ -0,0 +1,68 @@ +.. _mongoc_client_get_handshake_description: + +========================================= +mongoc_client_get_handshake_description() +========================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_server_description_t * + mongoc_client_get_handshake_description (mongoc_client_t *client, + uint32_t server_id, + bson_t *opts, + bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT; + +Returns a description constructed from the initial handshake response to a server. + +Description +----------- + +:ref:`mongoc_client_get_handshake_description` is distinct from :ref:`mongoc_client_get_server_description`. +:ref:`mongoc_client_get_server_description` returns a server description constructed from monitoring, +which may differ from the server description constructed from the connection handshake. + +:ref:`mongoc_client_get_handshake_description` will attempt to establish a connection to the server if +a connection was not already established. It will perform the MongoDB handshake and authentication if +required. + +Use this function only for building a language driver that wraps the C Driver. When writing applications +in C, higher-level functions automatically select a suitable server. + +Single-threaded client behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Single-threaded clients only have one active connection to each server. The one connection is used for +both monitoring and application operations. However, the server description returned by +:ref:`mongoc_client_get_handshake_description` may still differ from the server description returned by +:ref:`mongoc_client_get_server_description`. Notably, if connected to a load balanced cluster, the server +description returned by :ref:`mongoc_client_get_server_description` will describe the load balancer server +(:ref:`mongoc_server_description_type` will return "LoadBalancer"). And the server description returned by +:ref:`mongoc_client_get_handshake_description` will describe the backing server. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``server_id``: The ID of the server. This can be obtained from the server description of + :ref:`mongoc_client_select_server`. +- ``opts``: Unused. Pass ``NULL``. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Returns +------- + +A :ref:`mongoc_server_description_t` that must be freed with :ref:`mongoc_server_description_destroy`. +If a connection has not been successfully established to a server, returns ``NULL`` and ``error`` is +filled out. + + +See Also +-------- + +- :ref:`mongoc_client_select_server` To select a server from read preferences. +- :ref:`mongoc_client_get_server_description` To obtain the server description from monitoring for a server. +- :ref:`mongoc_server_description_type` To obtain the type of server from a server description. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_concern.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_concern.txt new file mode 100644 index 00000000..39d79656 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_concern.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_get_read_concern: + +================================ +mongoc_client_get_read_concern() +================================ + +Synopsis +-------- + +.. code-block:: c + + const mongoc_read_concern_t * + mongoc_client_get_read_concern (const mongoc_client_t *client); + +Retrieve the default read concern configured for the client instance. The result +should not be modified or freed. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +Returns +------- + +A :ref:`mongoc_read_concern_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_prefs.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_prefs.txt new file mode 100644 index 00000000..91ac64d1 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_prefs.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_get_read_prefs: + +============================== +mongoc_client_get_read_prefs() +============================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_read_prefs_t * + mongoc_client_get_read_prefs (const mongoc_client_t *client); + +Retrieves the default read preferences configured for the client instance. The result +should not be modified or freed. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +Returns +------- + +A :ref:`mongoc_read_prefs_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_description.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_description.txt new file mode 100644 index 00000000..2e4de958 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_description.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_get_server_description: + +====================================== +mongoc_client_get_server_description() +====================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_server_description_t * + mongoc_client_get_server_description ( + mongoc_client_t *client, uint32_t server_id) BSON_GNUC_WARN_UNUSED_RESULT; + +Get information about the server specified by ``server_id``. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``server_id``: An opaque id specifying the server. + +Returns +------- + +A :ref:`mongoc_server_description_t` that must be freed with :ref:`mongoc_server_description_destroy`. +If the server is no longer in the topology, returns NULL. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_descriptions.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_descriptions.txt new file mode 100644 index 00000000..cf02527c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_descriptions.txt @@ -0,0 +1,60 @@ +.. _mongoc_client_get_server_descriptions: + +======================================= +mongoc_client_get_server_descriptions() +======================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_server_description_t ** + mongoc_client_get_server_descriptions (const mongoc_client_t *client, + size_t *n) BSON_GNUC_WARN_UNUSED_RESULT; + +Fetches an array of :ref:`mongoc_server_description_t` structs for all known servers +in the topology. Returns no servers until the client connects. Returns a single server +if the client is directly connected, or all members of a replica set if the client's +MongoDB URI includes a "replicaSet" option, or all known mongos servers if the MongoDB +URI includes a list of them. + +.. code-block:: c + + void + show_servers (const mongoc_client_t *client) + { + bson_t *b = BCON_NEW ("ping", BCON_INT32 (1)); + bson_error_t error; + bool r; + mongoc_server_description_t **sds; + size_t i, n; + + /* ensure client has connected */ + r = mongoc_client_command_simple (client, "db", b, NULL, NULL, &error); + if (!r) { + MONGOC_ERROR ("could not connect: %s\n", error.message); + return; + } + + sds = mongoc_client_get_server_descriptions (client, &n); + + for (i = 0; i < n; ++i) { + printf ("%s\n", mongoc_server_description_host (sds[i])->host_and_port); + } + + mongoc_server_descriptions_destroy_all (sds, n); + bson_destroy (&b); + } + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``n``: Receives the length of the descriptions array. + +Returns +------- + +A newly allocated array that must be freed with :ref:`mongoc_server_descriptions_destroy_all`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_status.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_status.txt new file mode 100644 index 00000000..396c7173 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_status.txt @@ -0,0 +1,48 @@ +.. _mongoc_client_get_server_status: + +================================= +mongoc_client_get_server_status() +================================= + +.. warning:: + + This function is deprecated and should not be used in new code. + + Run the `serverStatus `__ + command directly with :ref:`mongoc_client_read_command_with_opts` instead. + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_get_server_status (mongoc_client_t *client, + mongoc_read_prefs_t *read_prefs, + bson_t *reply, + bson_error_t *error) BSON_GNUC_DEPRECATED; + +Queries the server for the current server status. The result is stored in ``reply``. + +``reply`` is always initialized, even in the case of failure. Always call :ref:`bson_destroy` +to release it. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t`. +- ``reply``: A maybe-NULL pointer to overwritable storage for a ``bson_t`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_uri.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_uri.txt new file mode 100644 index 00000000..b7ec30d4 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_uri.txt @@ -0,0 +1,26 @@ +.. _mongoc_client_get_uri: + +======================= +mongoc_client_get_uri() +======================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_uri_t * + mongoc_client_get_uri (const mongoc_client_t *client); + +Fetches the :ref:`mongoc_uri_t` used to create the client. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +Returns +------- + +A :ref:`mongoc_uri_t` that should not be modified or freed. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_get_write_concern.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_write_concern.txt new file mode 100644 index 00000000..30829249 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_get_write_concern.txt @@ -0,0 +1,27 @@ +.. _mongoc_client_get_write_concern: + +================================= +mongoc_client_get_write_concern() +================================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_write_concern_t * + mongoc_client_get_write_concern (const mongoc_client_t *client); + +Retrieve the default write concern configured for the client instance. The result +should not be modified or freed. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + +Returns +------- + +A :ref:`mongoc_write_concern_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_new.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_new.txt new file mode 100644 index 00000000..620b010f --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_new.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_new: + +=================== +mongoc_client_new() +=================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_new (const char *uri_string) BSON_GNUC_WARN_UNUSED_RESULT; + +Creates a new :ref:`mongoc_client_t` using the URI string provided. + +Parameters +---------- + +- ``uri_string``: A string containing the MongoDB connection URI. + +Returns +------- + +A newly allocated :ref:`mongoc_client_t` that should be freed with :ref:`mongoc_client_destroy` +when no longer in use. On error, ``NULL`` is returned and an error or warning will be logged. + +.. seealso:: + + | :ref:`mongoc_client_new_from_uri` + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri.txt new file mode 100644 index 00000000..bd3c5b14 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_new_from_uri: + +============================ +mongoc_client_new_from_uri() +============================ + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_new_from_uri (const mongoc_uri_t *uri) + BSON_GNUC_WARN_UNUSED_RESULT; + +Creates a new :ref:`mongoc_client_t` using the :ref:`mongoc_uri_t` provided. + +Parameters +---------- + +- ``uri``: A :ref:`mongoc_uri_t`. + +Returns +------- + +A newly allocated :ref:`mongoc_client_t` that should be freed with :ref:`mongoc_client_destroy` +when no longer in use. On error, ``NULL`` is returned and an error will be logged. + +.. seealso:: + + | :ref:`mongoc_client_new_from_uri_with_error` + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri_with_error.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri_with_error.txt new file mode 100644 index 00000000..61af3584 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri_with_error.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_new_from_uri_with_error: + +======================================= +mongoc_client_new_from_uri_with_error() +======================================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_t * + mongoc_client_new_from_uri_with_error (const mongoc_uri_t *uri, + bson_error_t *error) + BSON_GNUC_WARN_UNUSED_RESULT; + +Creates a new :ref:`mongoc_client_t` using the :ref:`mongoc_uri_t` provided. + +Parameters +---------- + +- ``uri``: A :ref:`mongoc_uri_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Returns +------- + +A newly allocated :ref:`mongoc_client_t` that should be freed with :ref:`mongoc_client_destroy` +when no longer in use. On error, ``NULL`` is returned and ``error`` will be populated with the +error description. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_read_command_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_read_command_with_opts.txt new file mode 100644 index 00000000..b87a6235 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_read_command_with_opts.txt @@ -0,0 +1,67 @@ +.. _mongoc_client_read_command_with_opts: + +====================================== +mongoc_client_read_command_with_opts() +====================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_read_command_with_opts (mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Execute a command on the server, applying logic that is specific to commands that read, and +taking the MongoDB server version into account. To send a raw command to the server without +any of this logic, use :ref:`mongoc_client_command_simple`. + +.. include:: /libmongoc/includes/read-cmd-opts-sources.txt + +``reply`` is always initialized, and must be freed with :ref:`bson_destroy`. + +.. include:: /libmongoc/includes/retryable-read.txt +.. include:: /libmongoc/includes/retryable-read-command.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``reply``: A maybe-NULL pointer to overwritable storage for a ``bson_t`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/read-opts.txt + +Consult `the MongoDB Manual entry on Database Commands `__ +for each command's arguments. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments or +a server or network error. + +.. _mongoc_client_read_command_with_opts_example: + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-command-with-opts.c + :language: c + :caption: example-command-with-opts.c + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_read_write_command_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_read_write_command_with_opts.txt new file mode 100644 index 00000000..79fe193f --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_read_write_command_with_opts.txt @@ -0,0 +1,66 @@ +.. _mongoc_client_read_write_command_with_opts: + +============================================ +mongoc_client_read_write_command_with_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_read_write_command_with_opts ( + mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs /* UNUSED */, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Execute a command on the server, applying logic for commands that both read and write, +and taking the MongoDB server version into account. To send a raw command to the server +without any of this logic, use :ref:`mongoc_client_command_simple`. + +.. include:: /libmongoc/includes/read-write-opts-sources.txt + +``reply`` is always initialized, and must be freed with :ref:`bson_destroy`. + +(The :ref:`mongoc_read_prefs_t` parameter was included by mistake when this function was +introduced in libmongoc 1.5. A command that writes must not obey a read preference.) + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``read_prefs``: Ignored. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/read-write-opts.txt + +Consult `the MongoDB Manual entry on Database Commands `__ +for each command's arguments. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. + +A write concern timeout or write concern error is considered a failure. + +Example +------- + +See the example code for :ref:`mongoc_client_read_command_with_opts`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_reset.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_reset.txt new file mode 100644 index 00000000..7f0c65c8 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_reset.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_reset: + +===================== +mongoc_client_reset() +===================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_reset (mongoc_client_t *client); + +Call this method in the child after forking to invalidate the :ref:`mongoc_client_t`. + +Description +----------- + +Calling :ref:`mongoc_client_reset` prevents resource cleanup in the child process from +interfering with the parent process. + +This method causes the client to clear its session pool without sending endSessions. It also +increments an internal generation counter on the given client. After this method is called, +cursors from previous generations will not issue a killCursors command when they are destroyed. +Client sessions from previous generations cannot be used and should be destroyed. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_select_server.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_select_server.txt new file mode 100644 index 00000000..4d7e68d7 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_select_server.txt @@ -0,0 +1,39 @@ +.. _mongoc_client_select_server: + +============================= +mongoc_client_select_server() +============================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_server_description_t * + mongoc_client_select_server (mongoc_client_t *client, + bool for_writes, + const mongoc_read_prefs_t *prefs, + bson_error_t *error) BSON_GNUC_WARN_UNUSED_RESULT; + +Choose a server for an operation, according to the logic described in the Server Selection +Spec. + +Use this function only for building a language driver that wraps the C Driver. When writing +applications in C, higher-level functions automatically select a suitable server. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``for_writes``: Whether to choose a server suitable for writes or reads. +- ``prefs``: An optional :ref:`mongoc_read_prefs_t`. If ``for_writes`` is true, ``prefs`` must + be NULL. Otherwise, use ``prefs`` to customize server selection, or pass NULL to use read preference + PRIMARY. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Returns +------- + +A :ref:`mongoc_server_description_t` that must be freed with :ref:`mongoc_server_description_destroy`. +If no suitable server is found, returns NULL and ``error`` is filled out. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_apm_callbacks.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_apm_callbacks.txt new file mode 100644 index 00000000..3e7504e0 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_apm_callbacks.txt @@ -0,0 +1,38 @@ +.. _mongoc_client_set_apm_callbacks: + +================================= +mongoc_client_set_apm_callbacks() +================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_set_apm_callbacks (mongoc_client_t *client, + mongoc_apm_callbacks_t *callbacks, + void *context); + +Register a set of callbacks to receive Application Performance Monitoring events. + +The ``callbacks`` are copied by the client and may be destroyed at any time after. If a +``context`` is passed, it is the application's responsibility to ensure ``context`` remains +valid for the lifetime of the client. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``callbacks``: Optional :ref:`mongoc_apm_callbacks_t`. Pass NULL to clear all callbacks. +- ``context``: Optional pointer to include with each event notification. + +Returns +------- + +Returns true on success. If any arguments are invalid, returns false and logs an error. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_appname.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_appname.txt new file mode 100644 index 00000000..12cf0276 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_appname.txt @@ -0,0 +1,37 @@ +.. _mongoc_client_set_appname: + +=========================== +mongoc_client_set_appname() +=========================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_set_appname (mongoc_client_t *client, const char *appname) + +Sets the application name for this client. This string, along with other internal +driver details, is sent to the server as part of the initial connection handshake +(`"hello" `__). + +``appname`` is copied, and doesn't have to remain valid after the call to ``mongoc_client_set_appname()``. + +This function will log an error and return false in the following cases: + +- ``appname`` is longer than ``MONGOC_HANDSHAKE_APPNAME_MAX`` +- ``client`` has already initiated a handshake +- ``client`` is from a :ref:`mongoc_client_pool_t` + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``appname``: The application name, of length at most ``MONGOC_HANDSHAKE_APPNAME_MAX``. + +Returns +------- + +true if the appname is set successfully. Otherwise, false. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_error_api.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_error_api.txt new file mode 100644 index 00000000..4b96570c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_error_api.txt @@ -0,0 +1,29 @@ +.. _mongoc_client_set_error_api: + +============================= +mongoc_client_set_error_api() +============================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_set_error_api (mongoc_client_t *client, int32_t version); + +Configure how the C Driver reports errors. See :ref:`Setting the Error API Version `. + +Do not use this function with pooled clients, see :ref:`mongoc_client_pool_set_error_api`. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``version``: The version of the error API, either ``MONGOC_ERROR_API_VERSION_LEGACY`` or + ``MONGOC_ERROR_API_VERSION_2``. + +Returns +------- + +Returns true on success. If any arguments are invalid, returns false and logs an error. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_concern.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_concern.txt new file mode 100644 index 00000000..3c60c777 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_concern.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_set_read_concern: + +================================ +mongoc_client_set_read_concern() +================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_set_read_concern (mongoc_client_t *client, + const mongoc_read_concern_t *read_concern); + +Sets the read concern for the client. This only affects future operations, collections, +and databases inheriting from ``client``. + +The default read concern is MONGOC_READ_CONCERN_LEVEL_LOCAL. This is the correct read +concern for the great majority of applications. + +It is a programming error to call this function on a client from a :ref:`mongoc_client_pool_t`. +For pooled clients, set the read concern with the :ref:`MongoDB URI ` +instead. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``read_concern``: A :ref:`mongoc_read_concern_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_prefs.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_prefs.txt new file mode 100644 index 00000000..7ce9bd8c --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_prefs.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_set_read_prefs: + +============================== +mongoc_client_set_read_prefs() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_set_read_prefs (mongoc_client_t *client, + const mongoc_read_prefs_t *read_prefs); + +Sets the default read preferences to use with future operations upon ``client``. + +The global default is to read from the replica set primary. + +It is a programming error to call this function on a client from a :ref:`mongoc_client_pool_t`. +For pooled clients, set the read preferences with the :ref:`MongoDB URI ` +instead. + +Please see the MongoDB website for a description of `Read Preferences `__. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_server_api.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_server_api.txt new file mode 100644 index 00000000..db5f7a98 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_server_api.txt @@ -0,0 +1,31 @@ +.. _mongoc_client_set_server_api: + +============================== +mongoc_client_set_server_api() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_set_server_api (mongoc_client_t *client, + const mongoc_server_api_t *api, + bson_error_t *error); + +Set the API version to use for ``client``. Once the API version is set on a client, +it may not be changed to a new value. Attempting to do so will cause this method to +fail and set ``error``. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``api``: A :ref:`mongoc_server_api_t`. +- ``error``: A :ref:`bson_error_t`. + +Returns +------- + +True if the version was successfully set, false if not. On failure, ``error`` will be set. diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_ssl_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_ssl_opts.txt new file mode 100644 index 00000000..39ba3a36 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_ssl_opts.txt @@ -0,0 +1,43 @@ +.. _mongoc_client_set_ssl_opts: + +============================ +mongoc_client_set_ssl_opts() +============================ + +Synopsis +-------- + +.. code-block:: c + + #ifdef MONGOC_ENABLE_SSL + void + mongoc_client_set_ssl_opts (mongoc_client_t *client, + const mongoc_ssl_opt_t *opts); + #endif + +Sets the TLS (SSL) options to use when connecting to TLS enabled MongoDB servers. + +The ``mongoc_ssl_opt_t`` struct is copied by the client along with the strings +it points to (``pem_file``, ``pem_pwd``, ``ca_file``, ``ca_dir``, and +``crl_file``) so they don't have to remain valid after the call to +``mongoc_client_set_ssl_opts``. + +A call to ``mongoc_client_set_ssl_opts`` overrides all TLS options set through +the connection string with which the ``mongoc_client_t`` was constructed. + +It is a programming error to call this function on a client from a +:ref:`mongoc_client_pool_t`. Instead, call +:ref:`mongoc_client_pool_set_ssl_opts` on the pool before popping any +clients. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: A :ref:`mongoc_ssl_opt_t`. + +Availability +------------ + +This feature requires that the MongoDB C driver was compiled with ``-DENABLE_SSL``. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_stream_initiator.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_stream_initiator.txt new file mode 100644 index 00000000..c7735564 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_stream_initiator.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_set_stream_initiator: + +==================================== +mongoc_client_set_stream_initiator() +==================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_set_stream_initiator (mongoc_client_t *client, + mongoc_stream_initiator_t initiator, + void *user_data); + +The :ref:`mongoc_client_set_stream_initiator` function shall associate a given :ref:`mongoc_client_t` +with a new stream initiator. This will completely replace the default transport (buffered TCP, +possibly with TLS). The ``initiator`` should fulfill the :ref:`mongoc_stream_t` contract. ``user_data`` +is passed through to the ``initiator`` callback and may be used for whatever run time customization +is necessary. + +If ``user_data`` is passed, it is the application's responsibility to ensure ``user_data`` remains +valid for the lifetime of the client. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``initiator``: A :ref:`mongoc_stream_initiator_t `. +- ``user_data``: User supplied pointer for callback function. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_set_write_concern.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_write_concern.txt new file mode 100644 index 00000000..9e057657 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_set_write_concern.txt @@ -0,0 +1,32 @@ +.. _mongoc_client_set_write_concern: + +================================= +mongoc_client_set_write_concern() +================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_client_set_write_concern (mongoc_client_t *client, + const mongoc_write_concern_t *write_concern); + +Sets the write concern for the client. This only affects future operations, collections, +and databases inheriting from ``client``. + +The default write concern is MONGOC_WRITE_CONCERN_W_DEFAULT: the driver blocks awaiting +basic acknowledgement of write operations from MongoDB. This is the correct write concern +for the great majority of applications. + +It is a programming error to call this function on a client from a :ref:`mongoc_client_pool_t`. +For pooled clients, set the write concern with the :ref:`MongoDB URI ` +instead. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``write_concern``: A :ref:`mongoc_write_concern_t`. + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_start_session.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_start_session.txt new file mode 100644 index 00000000..1ad25058 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_start_session.txt @@ -0,0 +1,41 @@ +.. _mongoc_client_start_session: + +============================= +mongoc_client_start_session() +============================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_client_session_t * + mongoc_client_start_session (mongoc_client_t *client, + mongoc_session_opt_t *opts, + bson_error_t *error) + +Create a session for a sequence of operations. + +.. include:: /libmongoc/includes/session-lifecycle.txt + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``opts``: An optional :ref:`mongoc_session_opt_t`. +- ``error``: A :ref:`bson_error_t`. + +Returns +------- + +If successful, this function returns a newly allocated :ref:`mongoc_client_session_t` +that should be freed with :ref:`mongoc_client_session_destroy` when no longer in use. +On error, returns NULL and sets ``error``. + +Errors +------ + +This function can fail if the driver is not built with crypto support, if ``opts`` is +misconfigured, or if the session is configured with options that the server does not support. + +.. include:: /libmongoc/includes/seealso/session.txt diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_watch.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_watch.txt new file mode 100644 index 00000000..1f9c7d2b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_watch.txt @@ -0,0 +1,53 @@ +.. _mongoc_client_watch: + +===================== +mongoc_client_watch() +===================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_change_stream_t* + mongoc_client_watch (mongoc_client_t *client, + const bson_t *pipeline, + const bson_t *opts) BSON_GNUC_WARN_UNUSED_RESULT; + +A helper function to create a change stream. It is preferred to call this +function over using a raw aggregation to create a change stream. + +This function uses the read preference and read concern of the client. If +the change stream needs to re-establish connection, the same read preference +will be used. This may happen if the change stream encounters a resumable error. + +.. warning:: + + A change stream is only supported with majority read concern. + +.. include:: /libmongoc/includes/retryable-read.txt + +Parameters +---------- + +- ``db``: A :ref:`mongoc_client_t` specifying the client which the change stream listens to. +- ``pipeline``: A :ref:`bson_t` representing an aggregation pipeline appended to the change stream. This may be an empty document. +- ``opts``: A :ref:`bson_t` containing change stream options. + +.. include:: /libmongoc/includes/change-stream-opts.txt + +Returns +------- + +A newly allocated :ref:`mongoc_change_stream_t` which must be freed with +:ref:`mongoc_change_stream_destroy` when no longer in use. The returned +:ref:`mongoc_change_stream_t` is never ``NULL``. If there is an error, it can +be retrieved with :ref:`mongoc_change_stream_error_document`, and subsequent +calls to :ref:`mongoc_change_stream_next` will return ``false``. + +.. seealso:: + + | :ref:`mongoc_database_watch` + + | :ref:`mongoc_collection_watch` + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_client_write_command_with_opts.txt b/source/libmongoc/api/mongoc_client_t/mongoc_client_write_command_with_opts.txt new file mode 100644 index 00000000..5e62027b --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_client_write_command_with_opts.txt @@ -0,0 +1,70 @@ +.. _mongoc_client_write_command_with_opts: + +======================================= +mongoc_client_write_command_with_opts() +======================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_client_write_command_with_opts (mongoc_client_t *client, + const char *db_name, + const bson_t *command, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Execute a command on the server, applying logic that is specific to commands that write, +and taking the MongoDB server version into account. To send a raw command to the server +without any of this logic, use :ref:`mongoc_client_command_simple`. + +.. include:: /libmongoc/includes/write-opts-sources.txt + +``reply`` is always initialized, and must be freed with :ref:`bson_destroy`. + +Parameters +---------- + +- ``client``: A :ref:`mongoc_client_t`. +- ``db_name``: The name of the database to run the command on. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/write-opts.txt + +Consult `the MongoDB Manual entry on Database Commands `__ +for each command's arguments. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +A write concern timeout or write concern error is considered a failure. + +Basic Write Operations +---------------------- + +Do not use this function to call the basic write commands "insert", "update", and "delete". Those commands +require special logic not implemented in ``mongoc_client_write_command_with_opts``. For basic write operations +use CRUD functions such as :ref:`mongoc_collection_insert_one` and the others described in :ref:`the CRUD tutorial +`, or use the :ref:`Bulk API `. + +Example +------- + +.. literalinclude:: /libmongoc/includes/examples/example-command-with-opts.c + :language: c + :caption: example-command-with-opts.c + diff --git a/source/libmongoc/api/mongoc_client_t/mongoc_handshake_data_append.txt b/source/libmongoc/api/mongoc_client_t/mongoc_handshake_data_append.txt new file mode 100644 index 00000000..b071fac9 --- /dev/null +++ b/source/libmongoc/api/mongoc_client_t/mongoc_handshake_data_append.txt @@ -0,0 +1,88 @@ +.. _mongoc_handshake_data_append: + +============================== +mongoc_handshake_data_append() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_handshake_data_append (const char *driver_name, + const char *driver_version, + const char *platform); + +Appends the given strings to the handshake data for the underlying C Driver. + +Description +----------- + +This function is intended for use by drivers which wrap the C Driver. +Calling this function will store the given strings as handshake data about +the system and driver by appending them to the handshake data for the +underlying C Driver. These values, along with other handshake data collected +during mongoc_init will be sent to the server as part of the initial +connection handshake in the "client" document. This function must not be +called more than once, or after server monitoring begins. For a single-threaded +:ref:`mongoc_client_t`, server monitoring begins on the first operation +requiring a server. For a :ref:`mongoc_client_pool_t`, server monitoring +begins on the first call to :ref:`mongoc_client_pool_pop`. + +The passed in strings are copied, and don't have to remain valid after the +call to :ref:`mongoc_handshake_data_append`. The driver may store truncated +versions of the passed in strings. + +.. note:: + + This function allocates memory, and therefore caution should be used when + using this in conjunction with :ref:`bson_mem_set_vtable`. If this function is + called before :ref:`bson_mem_set_vtable`, then :ref:`bson_mem_restore_vtable` must be + called before calling :ref:`mongoc_cleanup`. Failure to do so will result in + memory being freed by the wrong allocator. + +Parameters +---------- + +- ``driver_name``: An optional string storing the name of the wrapping driver +- ``driver_version``: An optional string storing the version of the wrapping driver. +- ``platform``: An optional string storing any information about the current platform, + for example configure options or compile flags. + +Returns +------- + +``true`` if the given fields are set successfully. Otherwise, it returns ``false`` and +logs an error. + +The default handshake data the driver sends with "hello" looks something +like: + +.. code-block:: c + + client: { + driver: { + name: "mongoc", + version: "1.5.0" + }, + os: {...}, + platform: "CC=gcc CFLAGS=-Wall -pedantic" + } + +If we call +:ref:`mongoc_handshake_data_append` ("phongo", "1.1.8", "CC=clang / ") +and it returns true, the driver sends handshake data like: + +.. code-block:: c + + client: { + driver: { + name: "mongoc / phongo", + version: "1.5.0 / 1.1.8" + }, + os: {...}, + platform: "CC=clang / gcc CFLAGS=-Wall -pedantic" + } + + diff --git a/source/libmongoc/api/mongoc_collection_t.txt b/source/libmongoc/api/mongoc_collection_t.txt new file mode 100644 index 00000000..6e638691 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t.txt @@ -0,0 +1,142 @@ +.. _mongoc_collection_t: + +=================== +mongoc_collection_t +=================== + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_collection_t mongoc_collection_t; + +``mongoc_collection_t`` provides access to a MongoDB collection. This handle is useful +for actions for most CRUD operations, I.e. insert, update, delete, find, etc. + +Read Preferences and Write Concerns +----------------------------------- + +Read preferences and write concerns are inherited from the parent client. They can be +overridden by ``set`` commands if so desired. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/api/mongoc_collection_t/mongoc_collection_aggregate + /libmongoc/api/mongoc_collection_t/mongoc_collection_command + /libmongoc/api/mongoc_collection_t/mongoc_collection_command_simple + /libmongoc/api/mongoc_collection_t/mongoc_collection_command_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_copy + /libmongoc/api/mongoc_collection_t/mongoc_collection_count_documents + /libmongoc/api/mongoc_collection_t/mongoc_collection_estimated_document_count + /libmongoc/api/mongoc_collection_t/mongoc_collection_count + /libmongoc/api/mongoc_collection_t/mongoc_collection_count_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation + /libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_create_index + /libmongoc/api/mongoc_collection_t/mongoc_collection_create_index_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_create_indexes_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_delete + /libmongoc/api/mongoc_collection_t/mongoc_collection_delete_many + /libmongoc/api/mongoc_collection_t/mongoc_collection_delete_one + /libmongoc/api/mongoc_collection_t/mongoc_collection_destroy + /libmongoc/api/mongoc_collection_t/mongoc_collection_drop + /libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index + /libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_drop_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_ensure_index + /libmongoc/api/mongoc_collection_t/mongoc_collection_find + /libmongoc/api/mongoc_collection_t/mongoc_collection_find_and_modify + /libmongoc/api/mongoc_collection_t/mongoc_collection_find_and_modify_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_find_indexes + /libmongoc/api/mongoc_collection_t/mongoc_collection_find_indexes_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_find_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_get_last_error + /libmongoc/api/mongoc_collection_t/mongoc_collection_get_name + /libmongoc/api/mongoc_collection_t/mongoc_collection_get_read_concern + /libmongoc/api/mongoc_collection_t/mongoc_collection_get_read_prefs + /libmongoc/api/mongoc_collection_t/mongoc_collection_get_write_concern + /libmongoc/api/mongoc_collection_t/mongoc_collection_insert + /libmongoc/api/mongoc_collection_t/mongoc_collection_insert_bulk + /libmongoc/api/mongoc_collection_t/mongoc_collection_insert_many + /libmongoc/api/mongoc_collection_t/mongoc_collection_insert_one + /libmongoc/api/mongoc_collection_t/mongoc_collection_keys_to_index_string + /libmongoc/api/mongoc_collection_t/mongoc_collection_read_command_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_read_write_command_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_remove + /libmongoc/api/mongoc_collection_t/mongoc_collection_rename + /libmongoc/api/mongoc_collection_t/mongoc_collection_rename_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_replace_one + /libmongoc/api/mongoc_collection_t/mongoc_collection_save + /libmongoc/api/mongoc_collection_t/mongoc_collection_set_read_concern + /libmongoc/api/mongoc_collection_t/mongoc_collection_set_read_prefs + /libmongoc/api/mongoc_collection_t/mongoc_collection_set_write_concern + /libmongoc/api/mongoc_collection_t/mongoc_collection_stats + /libmongoc/api/mongoc_collection_t/mongoc_collection_update + /libmongoc/api/mongoc_collection_t/mongoc_collection_update_one + /libmongoc/api/mongoc_collection_t/mongoc_collection_update_many + /libmongoc/api/mongoc_collection_t/mongoc_collection_validate + /libmongoc/api/mongoc_collection_t/mongoc_collection_write_command_with_opts + /libmongoc/api/mongoc_collection_t/mongoc_collection_watch + +- :ref:`mongoc_collection_aggregate` +- :ref:`mongoc_collection_command` +- :ref:`mongoc_collection_command_simple` +- :ref:`mongoc_collection_command_with_opts` +- :ref:`mongoc_collection_copy` +- :ref:`mongoc_collection_count_documents` +- :ref:`mongoc_collection_estimated_document_count` +- :ref:`mongoc_collection_count` +- :ref:`mongoc_collection_count_with_opts` +- :ref:`mongoc_collection_create_bulk_operation` +- :ref:`mongoc_collection_create_bulk_operation_with_opts` +- :ref:`mongoc_collection_create_index` +- :ref:`mongoc_collection_create_index_with_opts` +- :ref:`mongoc_collection_create_indexes_with_opts` +- :ref:`mongoc_collection_delete` +- :ref:`mongoc_collection_delete_many` +- :ref:`mongoc_collection_delete_one` +- :ref:`mongoc_collection_destroy` +- :ref:`mongoc_collection_drop` +- :ref:`mongoc_collection_drop_index` +- :ref:`mongoc_collection_drop_index_with_opts` +- :ref:`mongoc_collection_drop_with_opts` +- :ref:`mongoc_collection_ensure_index` +- :ref:`mongoc_collection_find` +- :ref:`mongoc_collection_find_and_modify` +- :ref:`mongoc_collection_find_and_modify_with_opts` +- :ref:`mongoc_collection_find_indexes` +- :ref:`mongoc_collection_find_indexes_with_opts` +- :ref:`mongoc_collection_find_with_opts` +- :ref:`mongoc_collection_get_last_error` +- :ref:`mongoc_collection_get_name` +- :ref:`mongoc_collection_get_read_concern` +- :ref:`mongoc_collection_get_read_prefs` +- :ref:`mongoc_collection_get_write_concern` +- :ref:`mongoc_collection_insert` +- :ref:`mongoc_collection_insert_bulk` +- :ref:`mongoc_collection_insert_many` +- :ref:`mongoc_collection_insert_one` +- :ref:`mongoc_collection_keys_to_index_string` +- :ref:`mongoc_collection_read_command_with_opts` +- :ref:`mongoc_collection_read_write_command_with_opts` +- :ref:`mongoc_collection_remove` +- :ref:`mongoc_collection_rename` +- :ref:`mongoc_collection_rename_with_opts` +- :ref:`mongoc_collection_replace_one` +- :ref:`mongoc_collection_save` +- :ref:`mongoc_collection_set_read_concern` +- :ref:`mongoc_collection_set_read_prefs` +- :ref:`mongoc_collection_set_write_concern` +- :ref:`mongoc_collection_stats` +- :ref:`mongoc_collection_update` +- :ref:`mongoc_collection_update_one` +- :ref:`mongoc_collection_update_many` +- :ref:`mongoc_collection_validate` +- :ref:`mongoc_collection_write_command_with_opts` +- :ref:`mongoc_collection_watch` \ No newline at end of file diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_aggregate.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_aggregate.txt new file mode 100644 index 00000000..be30cddb --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_aggregate.txt @@ -0,0 +1,147 @@ +.. _mongoc_collection_aggregate: + +============================= +mongoc_collection_aggregate() +============================= + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_collection_aggregate (mongoc_collection_t *collection, + mongoc_query_flags_t flags, + const bson_t *pipeline, + const bson_t *opts, + const mongoc_read_prefs_t *read_prefs) + BSON_GNUC_WARN_UNUSED_RESULT; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_query_flags_t`. Not all flag values apply. In particular, setting + ``MONGOC_QUERY_EXHAUST`` results in an error. +- ``pipeline``: A :ref:`bson_t`, either a BSON array or a BSON document containing an array field + named "pipeline". +- ``opts``: A :ref:`bson_t` containing options for the command, or ``NULL``. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t` or ``NULL``. + +.. include:: /libmongoc/includes/aggregate-opts.txt + +For a list of all options, see `the MongoDB Manual entry on the aggregate command +`__. + + +.. include:: /libmongoc/includes/retryable-read-aggregate.txt + +Description +----------- + +This function creates a cursor which sends the aggregate command on the underlying collection upon the first +call to :ref:`mongoc_cursor_next`. For more information on building aggregation pipelines, see +`the MongoDB Manual entry on the aggregate command `__. + +Read preferences, read and write concern, and collation can be overridden by various sources. The +highest-priority sources for these options are listed first in the following table. In a transaction, read +concern and write concern are prohibited in ``opts`` and the read preference must be primary or NULL. Write +concern is applied from ``opts``, or if ``opts`` has no write concern and the aggregation pipeline includes +"$out", the write concern is applied from ``collection``. The write concern is omitted for MongoDB before 3.4. + +.. list-table:: + :widths: 1 1 1 1 + :stub-columns: 1 + :header-rows: 1 + + * - Read Preferences + - Read Concern + - Write Concern + - Collation + + * - | ``read_prefs`` + - | ``opts`` + - | ``opts`` + - | ``opts`` + + * - Transaction + - Transaction + - Transaction + - + + * - | ``collection`` + - | ``collection`` + - | ``collection`` + - | + + +:ref:`See the example for transactions ` and for +:ref:`the "distinct" command with opts `. + +Returns +------- + +.. include:: /libmongoc/includes/returns-cursor.txt + +Example +------- + +.. code-block:: c + + #include + #include + + static mongoc_cursor_t * + pipeline_query (mongoc_collection_t *collection) + { + mongoc_cursor_t *cursor; + bson_t *pipeline; + + pipeline = BCON_NEW ("pipeline", + "[", + "{", + "$match", + "{", + "foo", + BCON_UTF8 ("A"), + "}", + "}", + "{", + "$match", + "{", + "bar", + BCON_BOOL (false), + "}", + "}", + "]"); + + cursor = mongoc_collection_aggregate ( + collection, MONGOC_QUERY_NONE, pipeline, NULL, NULL); + + bson_destroy (pipeline); + + return cursor; + } + +Other Parameters +---------------- + +When using ``$out``, the pipeline stage that writes, the write_concern field of the :ref:`mongoc_cursor_t` +will be set to the :ref:`mongoc_write_concern_t` parameter, if it is valid, and applied to the write command +when :ref:`mongoc_cursor_next` is called. Pass any other parameters to the ``aggregate`` command, besides +``pipeline``, as fields in ``opts``: + +.. code-block:: c + + mongoc_write_concern_t *write_concern = mongoc_write_concern_new (); + mongoc_write_concern_set_w (write_concern, 3); + + pipeline = + BCON_NEW ("pipeline", "[", "{", "$out", BCON_UTF8 ("collection2"), "}", "]"); + + opts = BCON_NEW ("bypassDocumentValidation", BCON_BOOL (true)); + mongoc_write_concern_append (write_concern, opts); + + cursor = mongoc_collection_aggregate ( + collection1, MONGOC_QUERY_NONE, pipeline, opts, NULL); + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command.txt new file mode 100644 index 00000000..0d21b702 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command.txt @@ -0,0 +1,44 @@ +.. _mongoc_collection_command: + +=========================== +mongoc_collection_command() +=========================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_collection_command (mongoc_collection_t *collection, + mongoc_query_flags_t flags, + uint32_t skip, + uint32_t limit, + uint32_t batch_size, + const bson_t *command, + const bson_t *fields, + const mongoc_read_prefs_t *read_prefs) + BSON_GNUC_WARN_UNUSED_RESULT; + +This function is superseded by :ref:`mongoc_collection_command_with_opts`, +:ref:`mongoc_collection_read_command_with_opts`, :ref:`mongoc_collection_write_command_with_opts`, +and :ref:`mongoc_collection_read_write_command_with_opts`. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_query_flags_t`. +- ``skip``: A uint32_t with the number of documents to skip or zero. +- ``limit``: A uint32_t with the max number of documents to return or zero. +- ``batch_size``: A uint32_t with the number of documents in each batch or zero. Default is 100. +- ``command``: A :ref:`bson_t` containing the command to execute. +- ``fields``: A :ref:`bson_t` containing the fields to return or ``NULL``. Not all commands support this option. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``. + +Returns +------- + +.. include:: /libmongoc/includes/returns-cursor.txt diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_simple.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_simple.txt new file mode 100644 index 00000000..ec521037 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_simple.txt @@ -0,0 +1,62 @@ +.. _mongoc_collection_command_simple: + +================================== +mongoc_collection_command_simple() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_command_simple (mongoc_collection_t *collection, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``command``: A :ref:`bson_t` containing the command to execute. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +This is a simplified version of :ref:`mongoc_collection_command` that returns the first result +document in ``reply``. The collection's read preference, read concern, and write concern are not +applied to the command. The parameter ``reply`` is initialized even upon failure to simplify memory +management. + +This function tries to unwrap an embedded error in the command when possible. The unwrapped error will +be propagated via the ``error`` parameter. Additionally, the result document is set in ``reply``. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +This function does not check the server response for a write concern error or write concern timeout. + +Example +------- + +The following is an example of executing the ``ping`` command. + +.. literalinclude:: /libmongoc/includes/examples/example-collection-command.c + :language: c + :start-after: BEGIN:mongoc_collection_command_simple + :end-before: END:mongoc_collection_command_simple diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_with_opts.txt new file mode 100644 index 00000000..7a5ebf27 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_with_opts.txt @@ -0,0 +1,62 @@ +.. _mongoc_collection_command_with_opts: + +===================================== +mongoc_collection_command_with_opts() +===================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_command_with_opts ( + mongoc_collection_t *collection, + const bson_t *command, + const mongoc_read_prefs_t *read_prefs, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Execute a command on the server, interpreting ``opts`` according to the MongoDB server version. +To send a raw command to the server without any of this logic, use :ref:`mongoc_client_command_simple`. + +.. include:: /libmongoc/includes/opts-sources.txt + +``reply`` is always initialized, and must be freed with :ref:`bson_destroy`. + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``command``: A :ref:`bson_t` containing the command specification. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`. +- ``opts``: A :ref:`bson_t` containing additional options. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/read-write-opts.txt + +Consult `the MongoDB Manual entry on Database Commands `__ +for each command's arguments. + +.. include:: /libmongoc/includes/not-retryable-read.txt + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +The reply is not parsed for a write concern timeout or write concern error. + +Example +------- + +See the example code for :ref:`mongoc_client_read_command_with_opts`. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_copy.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_copy.txt new file mode 100644 index 00000000..60040959 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_copy.txt @@ -0,0 +1,35 @@ +.. _mongoc_collection_copy: + +======================== +mongoc_collection_copy() +======================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_collection_t * + mongoc_collection_copy (mongoc_collection_t *collection) + BSON_GNUC_WARN_UNUSED_RESULT; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. + +Description +----------- + +Performs a deep copy of the ``collection`` struct and its configuration. Useful if you intend +to call :ref:`mongoc_collection_set_write_concern`, :ref:`mongoc_collection_set_read_prefs`, +or :ref:`mongoc_collection_set_read_concern`, and want to preserve an unaltered copy of the struct. + +This function does *not* copy the contents of the collection on the MongoDB server. + +Returns +------- + +A newly allocated :ref:`mongoc_collection_t` that should be freed with :ref:`mongoc_collection_destroy` +when no longer in use. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count.txt new file mode 100644 index 00000000..6caa5f43 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count.txt @@ -0,0 +1,97 @@ +.. _mongoc_collection_count: + +========================= +mongoc_collection_count() +========================= + +.. warning:: + + This function is deprecated and should not be used in new code. + Use :ref:`mongoc_collection_count_documents` or :ref:`mongoc_collection_estimated_document_count` + instead. + + :ref:`mongoc_collection_count_documents` has similar performance to calling :ref:`mongoc_collection_count` + with a non-NULL ``query``, and is guaranteed to retrieve an accurate collection count. See + :ref:`migrating from deprecated count functions ` for details. + + :ref:`mongoc_collection_estimated_document_count` has the same performance as calling + :ref:`mongoc_collection_count` with a NULL ``query``, but is not guaranteed to retrieve an accurate + collection count. + +.. include:: /libmongoc/includes/retryable-read.txt + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_collection_count (mongoc_collection_t *collection, + mongoc_query_flags_t flags, + const bson_t *query, + int64_t skip, + int64_t limit, + const mongoc_read_prefs_t *read_prefs, + bson_error_t *error) + BSON_GNUC_DEPRECATED_FOR (mongoc_collection_count_documents or + mongoc_collection_estimated_document_count); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_query_flags_t`. +- ``query``: A :ref:`bson_t` containing the query. +- ``skip``: A int64_t, zero to ignore. +- ``limit``: A int64_t, zero to ignore. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t` or ``NULL``. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +This function shall execute a count query on the underlying 'collection'. The bson 'query' is +not validated, simply passed along as appropriate to the server. As such, compatibility and +errors should be validated in the appropriate server documentation. + +For more information, see the `query reference `__ +at the MongoDB website. + +The :ref:`mongoc_read_concern_t` specified on the :ref:`mongoc_collection_t` will be used, if any. +If ``read_prefs`` is NULL, the collection's read preferences are used. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +-1 on failure, otherwise the number of documents counted. + +Example +------- + +.. code-block:: c + + #include + #include + #include + + static void + print_query_count (mongoc_collection_t *collection, bson_t *query) + { + bson_error_t error; + int64_t count; + + count = mongoc_collection_count ( + collection, MONGOC_QUERY_NONE, query, 0, 0, NULL, &error); + + if (count < 0) { + fprintf (stderr, "Count failed: %s\n", error.message); + } else { + printf ("%" PRId64 " documents counted.\n", count); + } + } + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_documents.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_documents.txt new file mode 100644 index 00000000..6b87c11a --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_documents.txt @@ -0,0 +1,111 @@ +.. _mongoc_collection_count_documents: + +=================================== +mongoc_collection_count_documents() +=================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_collection_count_documents (mongoc_collection_t *collection, + const bson_t *filter, + const bson_t *opts, + const mongoc_read_prefs_t *read_prefs, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``filter``: A :ref:`bson_t` containing the filter. +- ``opts``: A :ref:`bson_t`, ``NULL`` to ignore. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t` or ``NULL``. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/count-document-opts.txt + +Other options are included in the sent ``aggregate`` command. For a list of all options, +see `the MongoDB Manual entry on the aggregate command `__. + +Description +----------- + +This functions executes a count query on ``collection``. In contrast with :ref:`mongoc_collection_estimated_document_count`, +the count returned is guaranteed to be accurate. + +.. include:: /libmongoc/includes/retryable-read.txt + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +-1 on failure, otherwise the number of documents counted. + +Example +------- + +.. code-block:: c + + #include + #include + #include + + static void + print_count (mongoc_collection_t *collection, bson_t *filter) + { + bson_error_t error; + int64_t count; + bson_t* opts = BCON_NEW ("skip", BCON_INT64(5)); + + count = mongoc_collection_count_documents ( + collection, filter, opts, NULL, NULL, &error); + bson_destroy (opts); + + if (count < 0) { + fprintf (stderr, "Count failed: %s\n", error.message); + } else { + printf ("%" PRId64 " documents counted.\n", count); + } + } + +.. _migrating-from-deprecated-count: + +Migrating from deprecated count functions +----------------------------------------- + +When migrating to :ref:`mongoc_collection_count_documents` from the deprecated +:ref:`mongoc_collection_count` or :ref:`mongoc_collection_count_with_opts`, the following +query operators in the filter must be replaced: + +.. list-table:: + :widths: 1 2 + :stub-columns: 1 + :header-rows: 1 + + * - Operator + - Replacement + + * - | ``$where`` + - | :manual:`$expr ` + + * - ``$near`` + - :manual:`$geoWithin ` with :manual:`$center ` + + * - | ``$nearSphere`` + - | :manual:`$geoWithin ` with :manual:`$centerSphere ` + +$expr requires MongoDB 3.6+ + +.. seealso:: + + | :ref:`mongoc_collection_estimated_document_count` + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_with_opts.txt new file mode 100644 index 00000000..044137d3 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_with_opts.txt @@ -0,0 +1,150 @@ +.. _mongoc_collection_count_with_opts: + +=================================== +mongoc_collection_count_with_opts() +=================================== + +.. warning:: + + This function is deprecated and should not be used in new code. + Use :ref:`mongoc_collection_count_documents` or :ref:`mongoc_collection_estimated_document_count` instead. + + :ref:`mongoc_collection_count_documents` has similar performance to calling :ref:`mongoc_collection_count` + with a non-NULL ``query``, and is guaranteed to retrieve an accurate collection count. See + :ref:`migrating from deprecated count functions ` for details. + + :ref:`mongoc_collection_estimated_document_count` has the same performance as calling + :ref:`mongoc_collection_count` with a NULL ``query``, but is not guaranteed to retrieve an accurate + collection count. + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_collection_count_with_opts (mongoc_collection_t *collection, + mongoc_query_flags_t flags, + const bson_t *query, + int64_t skip, + int64_t limit, + const bson_t *opts, + const mongoc_read_prefs_t *read_prefs, + bson_error_t *error) + BSON_GNUC_DEPRECATED_FOR (mongoc_collection_count_documents or + mongoc_collection_estimated_document_count); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_query_flags_t`. +- ``query``: A :ref:`bson_t` containing the query. +- ``skip``: A int64_t, zero to ignore. +- ``limit``: A int64_t, zero to ignore. +- ``opts``: A :ref:`bson_t`, ``NULL`` to ignore. +- ``read_prefs``: An optional :ref:`mongoc_read_prefs_t`, otherwise uses the collection's read preference. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. include:: /libmongoc/includes/read-opts.txt + +Description +----------- + +This function shall execute a count query on the underlying 'collection'. The bson 'query' +is not validated, simply passed along as appropriate to the server. As such, compatibility +and errors should be validated in the appropriate server documentation. + +The :ref:`mongoc_read_concern_t` specified on the :ref:`mongoc_collection_t` will be used, if +any. If ``read_prefs`` is NULL, the collection's read preferences are used. + +In addition to the standard functionality available from mongoc_collection_count, this function +allows the user to add arbitrary extra keys to the count. This pass through enables features +such as hinting for counts. + +For more information, see the `query reference `__ +at the MongoDB website. + +.. include:: /libmongoc/includes/retryable-read.txt + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +-1 on failure, otherwise the number of documents counted. + +Examples +-------- + +.. code-block:: c + :caption: Basic Counting + + #include + #include + #include + + static void + print_query_count (mongoc_collection_t *collection, bson_t *query) + { + bson_error_t error; + int64_t count; + bson_t opts; + + bson_init (&opts); + BSON_APPEND_UTF8 (&opts, "hint", "_id_"); + + count = mongoc_collection_count_with_opts ( + collection, MONGOC_QUERY_NONE, query, 0, 0, &opts, NULL, &error); + + bson_destroy (&opts); + + if (count < 0) { + fprintf (stderr, "Count failed: %s\n", error.message); + } else { + printf ("%" PRId64 " documents counted.\n", count); + } + } + +.. code-block:: c + :caption: Counting with Collation + + #include + #include + #include + + static void + print_query_count (mongoc_collection_t *collection, bson_t *query) + { + bson_t *selector; + bson_t *opts; + bson_error_t error; + int64_t count; + + selector = BCON_NEW ("_id", "{", "$gt", BCON_UTF8 ("one"), "}"); + + /* "One" normally sorts before "one"; make "one" come first */ + opts = BCON_NEW ("collation", + "{", + "locale", + BCON_UTF8 ("en_US"), + "caseFirst", + BCON_UTF8 ("lower"), + "}"); + + count = mongoc_collection_count_with_opts ( + collection, MONGOC_QUERY_NONE, query, 0, 0, opts, NULL, &error); + + bson_destroy (selector); + bson_destroy (opts); + + if (count < 0) { + fprintf (stderr, "Count failed: %s\n", error.message); + } else { + printf ("%" PRId64 " documents counted.\n", count); + } + } + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation.txt new file mode 100644 index 00000000..59c106a3 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation.txt @@ -0,0 +1,71 @@ +.. _mongoc_collection_create_bulk_operation: + +========================================= +mongoc_collection_create_bulk_operation() +========================================= + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_collection_create_bulk_operation_with_opts` in new code. + +Synopsis +-------- + +.. code-block:: c + + mongoc_bulk_operation_t * + mongoc_collection_create_bulk_operation ( + mongoc_collection_t *collection, + bool ordered, + const mongoc_write_concern_t *write_concern) BSON_GNUC_WARN_UNUSED_RESULT + BSON_GNUC_DEPRECATED_FOR (mongoc_collection_create_bulk_operation_with_opts); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``ordered``: If the operations must be performed in order. +- ``write_concern``: An optional :ref:`mongoc_write_concern_t` or ``NULL``. + +Description +----------- + +This function shall begin a new bulk operation. After creating this you may call various +functions such as :ref:`mongoc_bulk_operation_update`, :ref:`mongoc_bulk_operation_insert` +and others. + +After calling :ref:`mongoc_bulk_operation_execute` the commands will be executed in as +large as batches as reasonable by the client. + +If ``ordered`` is true, then processing will stop at the first error. + +If ``ordered`` is not true, then the bulk operation will attempt to continue processing even +after the first failure. + +``write_concern`` contains the write concern for all operations in the bulk operation. If +``NULL``, the collection's write concern is used. The global default is acknowledged writes: +MONGOC_WRITE_CONCERN_W_DEFAULT. + +Errors +------ + +Errors are propagated when executing the bulk operation. + +Returns +------- + +A newly allocated :ref:`mongoc_bulk_operation_t` that should be freed with +:ref:`mongoc_bulk_operation_destroy` when no longer in use. + +.. warning:: + + Failure to handle the result of this function is a programming error. + +.. seealso:: + + | :ref:`Bulk Write Operations ` + + :ref:`mongoc_bulk_operation_t` + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation_with_opts.txt new file mode 100644 index 00000000..4f8de2a8 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation_with_opts.txt @@ -0,0 +1,56 @@ +.. _mongoc_collection_create_bulk_operation_with_opts: + +=================================================== +mongoc_collection_create_bulk_operation_with_opts() +=================================================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_bulk_operation_t * + mongoc_collection_create_bulk_operation_with_opts ( + mongoc_collection_t *collection, + const bson_t *opts) BSON_GNUC_WARN_UNUSED_RESULT; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/bulk-opts.txt + +Description +----------- + +This function shall begin a new bulk operation. After creating this you may call various +functions such as :ref:`mongoc_bulk_operation_update`, :ref:`mongoc_bulk_operation_insert` +and others. + +After calling :ref:`mongoc_bulk_operation_execute` the commands will be executed in as large +as batches as reasonable by the client. + +Errors +------ + +Errors are propagated when executing the bulk operation. + +Returns +------- + +A newly allocated :ref:`mongoc_bulk_operation_t` that should be freed with :ref:`mongoc_bulk_operation_destroy` +when no longer in use. + +.. warning:: + + Failure to handle the result of this function is a programming error. + +.. seealso:: + + | :ref:`Bulk Write Operations ` + + | :ref:`mongoc_bulk_operation_t` + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index.txt new file mode 100644 index 00000000..c6bdbd2a --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index.txt @@ -0,0 +1,29 @@ +.. _mongoc_collection_create_index: + +================================ +mongoc_collection_create_index() +================================ + +.. warning:: + + This function is deprecated and should not be used in new code. See + :ref:`mongoc_manage_collection_indexes`. + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_create_index (mongoc_collection_t *collection, + const bson_t *keys, + const mongoc_index_opt_t *opt, + bson_error_t *error) BSON_GNUC_DEPRECATED; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``keys``: A :ref:`bson_t`. +- ``opt``: A mongoc_index_opt_t. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index_with_opts.txt new file mode 100644 index 00000000..55de8eba --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index_with_opts.txt @@ -0,0 +1,64 @@ +.. _mongoc_collection_create_index_with_opts: + +========================================== +mongoc_collection_create_index_with_opts() +========================================== + +.. warning:: + + This function is deprecated and should not be used in new code. See :ref:`mongoc_manage_collection_indexes`. + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_create_index_with_opts (mongoc_collection_t *collection, + const bson_t *keys, + const mongoc_index_opt_t *index_opts, + const bson_t *command_opts, + bson_t *reply, + bson_error_t *error) + BSON_GNUC_DEPRECATED; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``keys``: A :ref:`bson_t`. +- ``index_opts``: A mongoc_index_opt_t. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/create-index-opts.txt + +Description +----------- + +This function will request the creation of a new index. + +This function will use the ``createIndexes`` command. +The server's reply is stored in ``reply``. + +If no write concern is provided in ``command_opts``, the collection's write concern is used. + +See :ref:`mongoc_index_opt_t` for options on creating indexes. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments +or a server or network error. + +``reply`` is always initialized and must be destroyed with :ref:`bson_destroy`. If the server +is running an obsolete version of MongoDB then ``reply`` may be empty, though it will still be +initialized. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_indexes_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_indexes_with_opts.txt new file mode 100644 index 00000000..447a8be4 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_indexes_with_opts.txt @@ -0,0 +1,78 @@ +.. _mongoc_collection_create_indexes_with_opts: + +============================================ +mongoc_collection_create_indexes_with_opts() +============================================ + +Synopsis +-------- + +.. code-block:: c + + typedef struct _mongoc_index_model_t mongoc_index_model_t; + + mongoc_index_model_t * + mongoc_index_model_new (const bson_t *keys, const bson_t *opts); + + void mongoc_index_model_destroy (mongoc_index_model_t *model); + + bool + mongoc_collection_create_indexes_with_opts (mongoc_collection_t *collection, + mongoc_index_model_t **models, + size_t n_models, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``models``: An array of ``mongoc_index_model_t *``. +- ``n_models``: The number of ``models``. +- ``opts``: Optional options. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/write-opts.txt + +Additional options passed in ``opts`` are appended to the ``createIndexes`` command. +See the `MongoDB Manual for createIndexes `__ +for all supported options. + +If no write concern is provided in ``opts``, the collection's write concern is used. + +mongoc_index_model_t +~~~~~~~~~~~~~~~~~~~~ + +Each ``mongoc_index_model_t`` represents an index to create. ``mongoc_index_model_new`` +includes: + +- ``keys`` Expected to match the form of the ``key`` field in the `createIndexes + `__ command. +- ``opts`` Optional index options appended as a sibling to the ``key`` field in the + `createIndexes `__ command. + + +Description +----------- + +This function wraps around the `createIndexes `_ +command. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. + +.. seealso:: + + | :ref:`mongoc_manage_collection_indexes`. diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete.txt new file mode 100644 index 00000000..ae0797cb --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete.txt @@ -0,0 +1,59 @@ +.. _mongoc_collection_delete: + +========================== +mongoc_collection_delete() +========================== + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_collection_delete_one` or :ref:`mongoc_collection_delete_many` + in new code. + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_delete (mongoc_collection_t *collection, + mongoc_delete_flags_t flags, + const bson_t *selector, + const mongoc_write_concern_t *write_concern, + bson_error_t *error) + BSON_GNUC_DEPRECATED_FOR (mongoc_collection_delete_one or + mongoc_collection_delete_many); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_delete_flags_t`. +- ``selector``: A :ref:`bson_t` containing the query to match documents. +- ``write_concern``: A :ref:`mongoc_write_concern_t` or ``NULL``. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +This function shall delete documents in the given ``collection`` that match ``selector``. +The bson ``selector`` is not validated, simply passed along as appropriate to the server. +As such, compatibility and errors should be validated in the appropriate server documentation. + +If you want to limit deletes to a single document, provide ``MONGOC_DELETE_SINGLE_REMOVE`` +in ``flags``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. + +A write concern timeout or write concern error is considered a failure. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_many.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_many.txt new file mode 100644 index 00000000..12aebc5f --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_many.txt @@ -0,0 +1,51 @@ +.. _mongoc_collection_delete_many: + +=============================== +mongoc_collection_delete_many() +=============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_delete_many (mongoc_collection_t *collection, + const bson_t *selector, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``selector``: A :ref:`bson_t` containing the query to match documents. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/delete-many-opts.txt + +Description +----------- + +This function removes all documents in the given ``collection`` that match ``selector``. + +To delete at most one matching document, use :ref:`mongoc_collection_delete_one`. + +If you pass a non-NULL ``reply``, it is filled out with the field "deletedCount". If +there is a server error then ``reply`` contains either a "writeErrors" array with one +subdocument or a "writeConcernErrors" array. The reply must be freed with :ref:`bson_destroy`. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_one.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_one.txt new file mode 100644 index 00000000..c2039173 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_one.txt @@ -0,0 +1,52 @@ +.. _mongoc_collection_delete_one: + +============================== +mongoc_collection_delete_one() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_delete_one (mongoc_collection_t *collection, + const bson_t *selector, + const bson_t *opts, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``selector``: A :ref:`bson_t` containing the query to match documents. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/delete-one-opts.txt + +Description +----------- + +This function removes at most one document in the given ``collection`` that matches +``selector``. + +To delete all matching documents, use :ref:`mongoc_collection_delete_many`. + +If you pass a non-NULL ``reply``, it is filled out with the field "deletedCount". If +there is a server error then ``reply`` contains either a "writeErrors" array with one +subdocument or a "writeConcernErrors" array. The reply must be freed with :ref:`bson_destroy`. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_destroy.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_destroy.txt new file mode 100644 index 00000000..08429b81 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_destroy.txt @@ -0,0 +1,30 @@ +.. _mongoc_collection_destroy: + +=========================== +mongoc_collection_destroy() +=========================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_collection_destroy (mongoc_collection_t *collection); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. + +Description +----------- + +This function shall destroy a :ref:`mongoc_collection_t` and its associated resources. +Does nothing if ``collection`` is NULL. + +.. warning:: + + Always destroy a :ref:`mongoc_cursor_t` created from a collection before destroying + the collection. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop.txt new file mode 100644 index 00000000..a25730dd --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop.txt @@ -0,0 +1,26 @@ +.. _mongoc_collection_drop: + +======================== +mongoc_collection_drop() +======================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_drop (mongoc_collection_t *collection, bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +For more information, see :ref:`mongoc_collection_drop_with_opts`. This function is a +thin wrapper, passing ``NULL`` in as :ref:`opts ` parameter. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index.txt new file mode 100644 index 00000000..f19f849f --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index.txt @@ -0,0 +1,29 @@ +.. _mongoc_collection_drop_index: + +============================== +mongoc_collection_drop_index() +============================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_drop_index (mongoc_collection_t *collection, + const char *index_name, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``index_name``: A string containing the name of the index. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Description +----------- + +For more information, see :ref:`mongoc_collection_drop_index_with_opts`. This function +is a thin wrapper, passing ``NULL`` in as :ref:`opts ` parameter. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index_with_opts.txt new file mode 100644 index 00000000..30678555 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index_with_opts.txt @@ -0,0 +1,49 @@ +.. _mongoc_collection_drop_index_with_opts: + +======================================== +mongoc_collection_drop_index_with_opts() +======================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_drop_index_with_opts (mongoc_collection_t *collection, + const char *index_name, + const bson_t *opts, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``index_name``: A string containing the name of the index. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/write-opts.txt + +Description +----------- + +This function requests than an index on ``collection`` be dropped. + +If no write concern is provided in ``opts``, the collection's write concern is used. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid +arguments or a server or network error. + +.. seealso:: + + | :ref:`mongoc_manage_collection_indexes`. diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_with_opts.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_with_opts.txt new file mode 100644 index 00000000..190ded8f --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_with_opts.txt @@ -0,0 +1,82 @@ +.. _mongoc_collection_drop_with_opts: + +================================== +mongoc_collection_drop_with_opts() +================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_drop_with_opts (mongoc_collection_t *collection, + bson_t *opts, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/write-opts.txt + +Description +----------- + +This function requests that a ``collection`` be dropped, including all indexes associated +with the ``collection``. + +If no write concern is provided in ``opts``, the collection's write concern is used. + +If the collection does not exist, the server responds with an "ns not found" error. It +is safe to ignore this error; set the :ref:`Error API Version ` to 2 +and ignore server error code 26: + +.. code-block:: c + + mongoc_client_t *client; + mongoc_collection_t *collection; + bson_error_t error; + bool r; + + client = mongoc_client_new (NULL); + mongoc_client_set_error_api (client, 2); + collection = mongoc_client_get_collection (client, "db", "collection"); + r = mongoc_collection_drop_with_opts (collection, NULL /* opts */, &error); + if (r) { + printf ("Dropped.\n"); + } else { + printf ("Error message: %s\n", error.message); + if (error.domain == MONGOC_ERROR_SERVER && error.code == 26) { + printf ("Ignoring 'ns not found' error\n"); + } else { + fprintf (stderr, "Unrecognized error!\n"); + } + } + + mongoc_collection_destroy (collection); + mongoc_client_destroy (client); + +In MongoDB 3.0 and older, the "ns not found" error code is the generic +MONGOC_ERROR_QUERY_FAILURE; in this case check whether the error message is equal to +the string "ns not found". + +The ``encryptedFields`` document in ``opts`` may be used to drop a collection for +:ref:`Queryable Encryption `. If ``encryptedFields`` is specified, +the "ns not found" error is not returned. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +Returns true if the collection was successfully dropped. Returns ``false`` and sets ``error`` +if there are invalid arguments or a server or network error. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_ensure_index.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_ensure_index.txt new file mode 100644 index 00000000..a2fa4f35 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_ensure_index.txt @@ -0,0 +1,36 @@ +.. _mongoc_collection_ensure_index: + +================================ +mongoc_collection_ensure_index() +================================ + +.. warning:: + + This function is deprecated and should not be used in new code. See + :ref:`mongoc_manage_collection_indexes`. + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_collection_ensure_index (mongoc_collection_t *collection, + const bson_t *keys, + const mongoc_index_opt_t *opt, + bson_error_t *error) + BSON_GNUC_DEPRECATED; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``keys``: A :ref:`bson_t`. +- ``opt``: A mongoc_index_opt_t. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_estimated_document_count.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_estimated_document_count.txt new file mode 100644 index 00000000..1474e473 --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_estimated_document_count.txt @@ -0,0 +1,100 @@ +.. _mongoc_collection_estimated_document_count: + +============================================ +mongoc_collection_estimated_document_count() +============================================ + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_collection_estimated_document_count (mongoc_collection_t *collection, + const bson_t *opts, + const mongoc_read_prefs_t *read_prefs, + bson_t *reply, + bson_error_t *error); + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``opts``: A :ref:`bson_t`, ``NULL`` to ignore. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t` or ``NULL``. +- ``reply``: A ``bson_t-opt-storage-ptr`` to contain the results. +- ``error``: An optional location for a :ref:`bson_error_t` or ``NULL``. + +.. ``opts-source`` replace:: ``collection`` + +.. include:: /libmongoc/includes/read-opts.txt + +- ``skip``: An int specifying how many documents matching the ``query`` should be skipped + before counting. +- ``limit``: An int specifying the maximum number of documents to count. +- ``comment``: A :ref:`bson_value_t` specifying the comment to attach to this command. + The comment will appear in log messages, profiler output, and currentOp output. Requires + MongoDB 4.4 or later. + +For a list of all options, see `the MongoDB Manual entry on the count command +`__. + +Description +----------- + +This functions executes a count query on ``collection``. In contrast with :ref:`mongoc_collection_count_documents`, +the count returned is *not* guaranteed to be accurate. + +.. include:: /libmongoc/includes/retryable-read.txt + +Behavior +~~~~~~~~ + +This method is implemented using the `count `__ +command. Due to an oversight in versions 5.0.0-5.0.8 of MongoDB, the ``count`` command was not included +in version "1" of the Stable API. Applications using this method with the Stable API are recommended to +upgrade their server version to 5.0.9+ or disable strict mode (via :ref:`mongoc_server_api_strict`) +to avoid encountering errors. + +Errors +------ + +Errors are propagated via the ``error`` parameter. + +Returns +------- + +-1 on failure, otherwise the number of documents counted. + +Example +------- + +.. code-block:: c + + #include + #include + #include + + static void + print_count (mongoc_collection_t *collection, bson_t *query) + { + bson_error_t error; + int64_t count; + bson_t* opts = BCON_NEW ("skip", BCON_INT64(5)); + + count = mongoc_collection_estimated_document_count ( + collection, opts, NULL, NULL, &error); + bson_destroy (opts); + + if (count < 0) { + fprintf (stderr, "Count failed: %s\n", error.message); + } else { + printf ("%" PRId64 " documents counted.\n", count); + } + } + +.. seealso:: + + | :ref:`mongoc_collection_count_documents` + | `Count: Behavior `_ in the MongoDB Manual + diff --git a/source/libmongoc/api/mongoc_collection_t/mongoc_collection_find.txt b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_find.txt new file mode 100644 index 00000000..b77d9dfc --- /dev/null +++ b/source/libmongoc/api/mongoc_collection_t/mongoc_collection_find.txt @@ -0,0 +1,188 @@ +.. _mongoc_collection_find: + +======================== +mongoc_collection_find() +======================== + +.. warning:: + + This function is deprecated and should not be used in new code. + +Use the more convenient :ref:`mongoc_collection_find_with_opts` instead. + +Synopsis +-------- + +.. code-block:: c + + mongoc_cursor_t * + mongoc_collection_find (mongoc_collection_t *collection, + mongoc_query_flags_t flags, + uint32_t skip, + uint32_t limit, + uint32_t batch_size, + const bson_t *query, + const bson_t *fields, + const mongoc_read_prefs_t *read_prefs) + BSON_GNUC_DEPRECATED_FOR (mongoc_collection_find_with_opts) + BSON_GNUC_WARN_UNUSED_RESULT; + +Parameters +---------- + +- ``collection``: A :ref:`mongoc_collection_t`. +- ``flags``: A :ref:`mongoc_query_flags_t`. +- ``skip``: A uint32_t of number of documents to skip or 0. +- ``limit``: A uint32_t of max number of documents to return or 0. +- ``batch_size``: A uint32_t containing batch size of document result sets or 0 for default. Default is 100. +- ``query``: A :ref:`bson_t` containing the query and options to execute. +- ``fields``: A :ref:`bson_t` containing fields to return or ``NULL``. +- ``read_prefs``: A :ref:`mongoc_read_prefs_t` or ``NULL`` for default read preferences. + +Description +----------- + +This function shall execute a query on the underlying ``collection``. + +If no options are necessary, ``query`` can simply contain a query such as ``{a:1}``. If you would +like to specify options such as a sort order, the query must be placed inside of ``{"$query": {}}``. +See the example below for how to properly specify additional options to ``query``. + +.. include:: /libmongoc/includes/retryable-read.txt + +Returns +------- + +.. include:: /libmongoc/includes/returns-cursor.txt + +Example +------- + +.. code-block:: c + :caption: Print All Documents in a Collection + + #include + #include + #include + + static void + print_all_documents (mongoc_collection_t *collection) + { + mongoc_cursor_t *cursor; + bson_error_t error; + const bson_t *doc; + char *str; + bson_t *query; + + query = BCON_NEW ("$query", + "{", + "foo", + BCON_INT32 (1), + "}", + "$orderby", + "{", + "bar", + BCON_INT32 (-1), + "}"); + cursor = mongoc_collection_find ( + collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL); + + while (mongoc_cursor_next (cursor, &doc)) { + str = bson_as_canonical_extended_json (doc, NULL); + printf ("%s\n", str); + bson_free (str); + } + + if (mongoc_cursor_error (cursor, &error)) { + fprintf (stderr, "An error occurred: %s\n", error.message); + } + + mongoc_cursor_destroy (cursor); + bson_destroy (query); + } + +The "find" command +------------------ + +Queries have historically been sent as OP_QUERY wire protocol messages, but beginning +in MongoDB 3.2 queries use `the "find" command `__ +instead. + +The driver automatically converts queries to the new "find" command syntax if needed, so +this change is typically invisible to C Driver users. However, an application written exclusively +for MongoDB 3.2 and later can choose to use the new syntax directly instead of relying on the +driver to convert from the old syntax: + +.. code-block:: c + + /* MongoDB 3.2+ "find" command syntax */ + query = BCON_NEW ("filter", + "{", + "foo", + BCON_INT32 (1), + "}", + "sort", + "{", + "bar", + BCON_INT32 (-1), + "}"); + cursor = mongoc_collection_find ( + collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL); + +The "find" command takes different options from the traditional OP_QUERY message. + +.. list-table:: + :widths: 1 1 1 1 + :stub-columns: 1 + :header-rows: 1 + + * - Query + - Sort + - Show record location + - Other $-options + + * - | ``$query`` + - | ``$orderby`` + - | ``$showDiskLoc`` + - | ``$