From d9208ee654661b18eb304d62fb80d2500f8d8347 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:03:27 -0700 Subject: [PATCH 1/8] Revert "KA feedback 2" This reverts commit 2ca2e76701a51388f8df2ac631b61be7bf5b005e. --- source/libbson.txt | 1 + source/libmongoc/guides/configuring_tls.txt | 3 +-- source/libmongoc/howto/source-install.txt | 2 +- source/libmongoc/includes/change-stream-opts.txt | 8 ++++---- .../tutorials/obtaining-libraries/from-source.txt | 3 ++- .../tutorials/obtaining-libraries/installing.txt | 4 ++-- 6 files changed, 11 insertions(+), 10 deletions(-) diff --git a/source/libbson.txt b/source/libbson.txt index 6d1a3dab..f1b74ed0 100644 --- a/source/libbson.txt +++ b/source/libbson.txt @@ -23,6 +23,7 @@ libbson /libbson/guides /libbson/cross-platform-notes API Documentation + /libbson/api Introduction ------------ diff --git a/source/libmongoc/guides/configuring_tls.txt b/source/libmongoc/guides/configuring_tls.txt index 66d7e216..93e96114 100644 --- a/source/libmongoc/guides/configuring_tls.txt +++ b/source/libmongoc/guides/configuring_tls.txt @@ -56,8 +56,7 @@ Most of the configurable options can be set using the :manual:`Connection String * - | allow_invalid_hostname - | tlsAllowInvalidHostnames -The only exclusions are ``crl_file`` and ``ca_dir``. Those may only be set with `mongoc_ssl_opt_t -<{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__. +The only exclusions are ``crl_file`` and ``ca_dir``. Those may only be set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__. Client Authentication --------------------- diff --git a/source/libmongoc/howto/source-install.txt b/source/libmongoc/howto/source-install.txt index d7cf5378..aede30bf 100644 --- a/source/libmongoc/howto/source-install.txt +++ b/source/libmongoc/howto/source-install.txt @@ -78,7 +78,7 @@ metadata. default, use the following command: .. code-block:: - :caption: Ask pkg-config what directories it will search by default + :caption: Ask `pkg-config` what directories it will search by default $ pkg-config "pkg-config" --variable="pc_path" diff --git a/source/libmongoc/includes/change-stream-opts.txt b/source/libmongoc/includes/change-stream-opts.txt index a3ee5afb..f68c9fc4 100644 --- a/source/libmongoc/includes/change-stream-opts.txt +++ b/source/libmongoc/includes/change-stream-opts.txt @@ -6,11 +6,11 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to `mongoc_change_stream_next <{+api-libmongoc+}/mongoc_change_stream_next.html>`__ -* ``resumeAfter``: A ``Document`` representing the logical starting point of the change stream. The result of `mongoc_change_stream_get_resume_token <{+api-libmongoc+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. -* ``startAfter``: A ``Document`` representing the logical starting point of the change stream. Unlike ``resumeAfter``, this can resume notifications after an "invalidate" event. The result of `mongoc_change_stream_get_resume_token <{+api-libmongoc+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. +* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to `mongoc_change_stream_next <{+api-libbson+}/mongoc_change_stream_next.html>`__ +* ``resumeAfter``: A ``Document`` representing the logical starting point of the change stream. The result of `mongoc_change_stream_get_resume_token <{+api-libbson+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. +* ``startAfter``: A ``Document`` representing the logical starting point of the change stream. Unlike ``resumeAfter``, this can resume notifications after an "invalidate" event. The result of `mongoc_change_stream_get_resume_token <{+api-libbson+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. * ``startAtOperationTime``: A ``Timestamp``. The change stream only provides changes that occurred at or after the specified timestamp. Any command run against the server will return an operation time that can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAfter``. -* ``maxAwaitTimeMS``: An ``int64`` representing the maximum amount of time a call to `mongoc_change_stream_next <{+api-libmongoc+}/mongoc_change_stream_next.html>`__ will block waiting for data +* ``maxAwaitTimeMS``: An ``int64`` representing the maximum amount of time a call to `mongoc_change_stream_next <{+api-libbson+}/mongoc_change_stream_next.html>`__ will block waiting for data * ``fullDocument``: An optional UTF-8 string. Set this option to "default", "updateLookup", "whenAvailable", or "required", If unset, The string "default" is assumed. Set this option to "updateLookup" to direct the change stream cursor to lookup the most current majority-committed version of the document associated to an update change stream event. * ``fullDocumentBeforeChange``: An optional UTF-8 string. Set this option to "whenAvailable", "required", or "off". When unset, the default value is "off". Similar to "fullDocument", but returns the value of the document before the associated change. * ``showExpandedEvents``: Set to ``true`` to return an expanded list of change stream events. Available only on MongoDB versions >=6.0 diff --git a/source/libmongoc/tutorials/obtaining-libraries/from-source.txt b/source/libmongoc/tutorials/obtaining-libraries/from-source.txt index 9538a94a..6cbcd3cf 100644 --- a/source/libmongoc/tutorials/obtaining-libraries/from-source.txt +++ b/source/libmongoc/tutorials/obtaining-libraries/from-source.txt @@ -363,7 +363,8 @@ Footnotes In many cases, CMake will detect a Visual Studio installation and automatically load the environment itself when it is executed. This automatic - detection can be controlled with CMake's ``-G``, ``-T``, and ``-A`` options. The ``-G`` option + detection can be controlled with CMake's ``-G ``, + ``-T ``, and ``-A `` options. The ``-G`` option is the most significant, as it selects which Visual Studio version will be used. The versions of Visual Studio supported depends on the version of CMake that you have installed. diff --git a/source/libmongoc/tutorials/obtaining-libraries/installing.txt b/source/libmongoc/tutorials/obtaining-libraries/installing.txt index ee289d31..618157a8 100644 --- a/source/libmongoc/tutorials/obtaining-libraries/installing.txt +++ b/source/libmongoc/tutorials/obtaining-libraries/installing.txt @@ -15,7 +15,7 @@ The ``libmongoc`` and ``libbson`` libraries are often available in the package management repositories of :ref:`common Linux distributions ` and :ref:`macOS via Homebrew `. -.. note:: +.. note:: For Windows, it is recommended to instead :ref:`build the libraries from source `, for maximum @@ -99,7 +99,7 @@ With CMake, the standard config-file package will be available, as well as the generated ``IMPORTED`` targets: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: `CMakeLists.txt` find_package(mongoc-1.0 CONFIG REQUIRED) target_link_libraries(my-application From d88fee659f3691b533f8818dde85771f6517e43d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:03:43 -0700 Subject: [PATCH 2/8] Revert "build log fixes" This reverts commit 3ecddde480d3f583136e7aefedce889f8f0fdb04. --- source/libbson/guides/json.txt | 2 +- source/libmongoc.txt | 3 ++- source/libmongoc/guides/connection-pooling.txt | 2 +- source/libmongoc/includes/init_cleanup.txt | 2 +- source/libmongoc/includes/write-opts-sources.txt | 2 +- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/libbson/guides/json.txt b/source/libbson/guides/json.txt index dd2831af..7107874b 100644 --- a/source/libbson/guides/json.txt +++ b/source/libbson/guides/json.txt @@ -65,7 +65,7 @@ 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>`__ +Converting back from JSON is also useful and common enough that we added :ref:`bson_init_from_json` and `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__. The following example creates a new `bson_t <{+api-libbson+}/bson_t.html>`__ from the JSON string ``{"a":1}``. diff --git a/source/libmongoc.txt b/source/libmongoc.txt index 91e732ec..fb50aa26 100644 --- a/source/libmongoc.txt +++ b/source/libmongoc.txt @@ -23,8 +23,9 @@ libmongoc /libmongoc/authentication /libmongoc/basic-troubleshooting /libmongoc/guides + /libmongoc/api + /libmongoc/application-performance-monitoring API Documentation - Application Performance Monitoring Introduction ------------ diff --git a/source/libmongoc/guides/connection-pooling.txt b/source/libmongoc/guides/connection-pooling.txt index a31e8b58..5f0ea23b 100644 --- a/source/libmongoc/guides/connection-pooling.txt +++ b/source/libmongoc/guides/connection-pooling.txt @@ -100,6 +100,6 @@ to confirm that a client was actually returned: /* take appropriate action for a timeout */ } -See `connection pool options <{+api-libmongoc+}/mongoc_uri_t.html#connection-pool-options>`__ to configure pool size and behavior, and see `mongoc_client_pool_t +See :ref:`connection_pool_options` to configure pool size and behavior, and see `mongoc_client_pool_t <{+api-libmongoc+}/mongoc_client_pool_t.html>`__ for an extended example of a multi-threaded program that uses the driver in pooled mode. diff --git a/source/libmongoc/includes/init_cleanup.txt b/source/libmongoc/includes/init_cleanup.txt index f684aabc..217fb4c3 100644 --- a/source/libmongoc/includes/init_cleanup.txt +++ b/source/libmongoc/includes/init_cleanup.txt @@ -4,7 +4,7 @@ Initialize the MongoDB C Driver by calling `mongoc_init <{+api-libmongoc+}/mongo It is responsible for initializing global state such as process counters, SSL, and threading primitives. Exception to this is ``mongoc_log_set_handler()``, which should be called before ``mongoc_init()`` or some -log traces would not use your log handling function. See `Custom Log Handlers <{+api-libmongoc+}/logging.html#custom-log-handlers>`__ +log traces would not use your log handling function. See :ref:`Custom Log Handlers ` for a detailed example. Call `mongoc_cleanup <{+api-libmongoc+}/mongoc_cleanup.html>`__ exactly once at the end of your program to release all memory and other resources diff --git a/source/libmongoc/includes/write-opts-sources.txt b/source/libmongoc/includes/write-opts-sources.txt index ae77b037..1d0e2b31 100644 --- a/source/libmongoc/includes/write-opts-sources.txt +++ b/source/libmongoc/includes/write-opts-sources.txt @@ -1,7 +1,7 @@ :orphan: Use this function for commands that write such as "drop" or "createRole" (but not for "insert", -"update", or "delete", see `basic write operations <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html#basic-write-operations>`__). Write concern and collation can be overridden +"update", or "delete", see :ref:`basic-write-ops`). Write concern and collation can be overridden by various sources. In a transaction, read concern and write concern are prohibited in ``opts``. The highest-priority sources for these options are listed first in the following table. The write concern is omitted for MongoDB before 3.4. From c9286581e09666c09560756f7cab4301d9d6db1d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:03:50 -0700 Subject: [PATCH 3/8] Revert "more ref fixes" This reverts commit edb286bdd101e1a32f966393dc6f212726999603. --- .../application-performance-monitoring.txt | 186 ++++++++++++++++++ .../client-side-field-level-encryption.txt | 15 +- source/libmongoc/guides/configuring_tls.txt | 23 ++- .../libmongoc/guides/connection-pooling.txt | 30 ++- source/libmongoc/guides/cursors.txt | 6 +- .../libmongoc/guides/distinct-mapreduce.txt | 6 +- source/libmongoc/guides/in-use-encryption.txt | 20 +- .../guides/manage-collection-indexes.txt | 8 +- source/libmongoc/includes/aggregate-opts.txt | 12 +- .../libmongoc/includes/bulk-insert-opts.txt | 2 +- source/libmongoc/includes/bulk-opts.txt | 6 +- .../includes/bulk-replace-one-opts.txt | 2 +- .../includes/bulk-update-many-opts.txt | 2 +- .../includes/bulk-update-one-opts.txt | 2 +- .../libmongoc/includes/change-stream-opts.txt | 10 +- .../includes/count-document-opts.txt | 8 +- .../libmongoc/includes/create-index-opts.txt | 4 +- .../libmongoc/includes/delete-many-opts.txt | 8 +- source/libmongoc/includes/delete-one-opts.txt | 10 +- .../find-and-modify-appended-opts.txt | 6 +- source/libmongoc/includes/generic-opts.txt | 4 +- .../libmongoc/includes/gridfs-bucket-opts.txt | 4 +- source/libmongoc/includes/init_cleanup.txt | 8 +- .../libmongoc/includes/insert-many-opts.txt | 8 +- source/libmongoc/includes/insert-one-opts.txt | 8 +- .../includes/mongoc_client_pool_call_once.txt | 2 +- source/libmongoc/includes/opts-sources.txt | 2 +- .../libmongoc/includes/read-opts-sources.txt | 3 +- source/libmongoc/includes/read-opts.txt | 6 +- .../includes/read-write-opts-sources.txt | 3 +- source/libmongoc/includes/read-write-opts.txt | 8 +- .../libmongoc/includes/replace-one-opts.txt | 8 +- source/libmongoc/includes/returns-cursor.txt | 8 +- .../includes/seealso/authmechanism.txt | 12 +- .../includes/seealso/cursor-error.txt | 4 +- source/libmongoc/includes/seealso/session.txt | 66 +++---- .../libmongoc/includes/session-lifecycle.txt | 6 +- .../libmongoc/includes/update-many-opts.txt | 8 +- source/libmongoc/includes/update-one-opts.txt | 8 +- .../libmongoc/includes/write-opts-sources.txt | 4 +- source/libmongoc/includes/write-opts.txt | 6 +- source/libmongoc/tutorial.txt | 32 +-- 42 files changed, 382 insertions(+), 202 deletions(-) create mode 100644 source/libmongoc/application-performance-monitoring.txt diff --git a/source/libmongoc/application-performance-monitoring.txt b/source/libmongoc/application-performance-monitoring.txt new file mode 100644 index 00000000..b19b7bf7 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring.txt @@ -0,0 +1,186 @@ +.. _mongoc_application_performance_monitoring: + +======================================== +Application Performance Monitoring (APM) +======================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +The MongoDB C Driver allows you to monitor all the MongoDB operations the driver executes. This +event-notification system conforms to two MongoDB driver specs: + +- `Command Logging and Monitoring `_: + events related to all application operations. +- `SDAM Monitoring `_: + events related to the driver's Server Discovery And Monitoring logic. + +To receive notifications, create a ``mongoc_apm_callbacks_t`` with :ref:`mongoc_apm_callbacks_new`, +set callbacks on it, then pass it to :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +Command-Monitoring Example +-------------------------- + +.. literalinclude:: /libmongoc/includes/examples/example-command-monitoring.c + :language: c + :caption: example-command-monitoring.c + +This example program prints: + +.. code-block:: none + + Command drop started on 127.0.0.1: + { "drop" : "test" } + + Command drop succeeded: + { "ns" : "test.test", "nIndexesWas" : 1, "ok" : 1.0 } + + Command insert started on 127.0.0.1: + { + "insert" : "test", + "ordered" : true, + "documents" : [ + { "_id" : 0 }, { "_id" : 1 } + ] + } + + Command insert succeeded: + { "n" : 2, "ok" : 1.0 } + + Command insert started on 127.0.0.1: + { + "insert" : "test", + "ordered" : true, + "documents" : [ + { "_id" : 0 } + ] + } + + Command insert succeeded: + { + "n" : 0, + "writeErrors" : [ + { "index" : 0, "code" : 11000, "errmsg" : "duplicate key" } + ], + "ok" : 1.0 + } + + started: 3 + succeeded: 3 + failed: 0 + +The output has been edited and formatted for clarity. Depending on your server configuration, messages may +include metadata like database name, logical session ids, or cluster times that are not shown here. + +The final "insert" command is considered successful, despite the writeError, because the server replied to the +overall command with ``"ok": 1``. + +SDAM Monitoring Example +----------------------- + +.. literalinclude:: /libmongoc/includes/examples/example-sdam-monitoring.c + :language: c + :caption: example-sdam-monitoring.c + +Start a 3-node replica set on localhost with set name "rs" and start the program: + +.. code-block:: none + + ./example-sdam-monitoring "mongodb://localhost:27017,localhost:27018/?replicaSet=rs" + +This example program prints something like: + +.. code-block:: none + + topology opening + topology changed: Unknown -> ReplicaSetNoPrimary + secondary UNAVAILABLE + primary UNAVAILABLE + server opening: localhost:27017 + server opening: localhost:27018 + localhost:27017 heartbeat started + localhost:27018 heartbeat started + localhost:27017 heartbeat succeeded: { ... reply ... } + server changed: localhost:27017 Unknown -> RSPrimary + server opening: localhost:27019 + topology changed: ReplicaSetNoPrimary -> ReplicaSetWithPrimary + new servers: + RSPrimary localhost:27017 + secondary UNAVAILABLE + primary AVAILABLE + localhost:27019 heartbeat started + localhost:27018 heartbeat succeeded: { ... reply ... } + server changed: localhost:27018 Unknown -> RSSecondary + topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary + previous servers: + RSPrimary localhost:27017 + new servers: + RSPrimary localhost:27017 + RSSecondary localhost:27018 + secondary AVAILABLE + primary AVAILABLE + localhost:27019 heartbeat succeeded: { ... reply ... } + server changed: localhost:27019 Unknown -> RSSecondary + topology changed: ReplicaSetWithPrimary -> ReplicaSetWithPrimary + previous servers: + RSPrimary localhost:27017 + RSSecondary localhost:27018 + new servers: + RSPrimary localhost:27017 + RSSecondary localhost:27018 + RSSecondary localhost:27019 + secondary AVAILABLE + primary AVAILABLE + topology closed + + Events: + server changed: 3 + server opening: 3 + server closed: 0 + topology changed: 4 + topology opening: 1 + topology closed: 1 + heartbeat started: 3 + heartbeat succeeded: 3 + heartbeat failed: 0 + +The driver connects to the mongods on ports 27017 and 27018, which were specified in the URI, and determines +which is primary. It also discovers the third member, "localhost:27019", and adds it to the topology. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_callbacks_t + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_t + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_t + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_closed_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_t + /libmongoc/application-performance-monitoring/mongoc_apm_server_opening_t + /libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_t + /libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_t + /libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_t + +- :ref:`mongoc_apm_callbacks_t` +- :ref:`mongoc_apm_command_failed_t` +- :ref:`mongoc_apm_command_started_t` +- :ref:`mongoc_apm_command_succeeded_t` +- :ref:`mongoc_apm_server_changed_t` +- :ref:`mongoc_apm_server_closed_t` +- :ref:`mongoc_apm_server_heartbeat_failed_t` +- :ref:`mongoc_apm_server_heartbeat_started_t` +- :ref:`mongoc_apm_server_heartbeat_succeeded_t` +- :ref:`mongoc_apm_server_opening_t` +- :ref:`mongoc_apm_topology_changed_t` +- :ref:`mongoc_apm_topology_closed_t` +- :ref:`mongoc_apm_topology_opening_t` \ No newline at end of file diff --git a/source/libmongoc/guides/client-side-field-level-encryption.txt b/source/libmongoc/guides/client-side-field-level-encryption.txt index 24401265..50ebb98b 100644 --- a/source/libmongoc/guides/client-side-field-level-encryption.txt +++ b/source/libmongoc/guides/client-side-field-level-encryption.txt @@ -28,9 +28,8 @@ dependency for Query Analysis. See :ref:`in-use-encryption` for more information Automatic Client-Side Field Level Encryption -------------------------------------------- -Automatic encryption is enabled by calling `mongoc_client_enable_auto_encryption <{+api-libmongoc+}/mongoc_client_enable_auto_encryption.html>`__ -on a `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__. The following examples show how to set up -automatic encryption using `mongoc_client_encryption_t <{+api-libmongoc+}/mongoc_client_encryption_t.html>`__ to create +Automatic encryption is enabled by calling :ref:`mongoc_client_enable_auto_encryption` on a :ref:`mongoc_client_t`. +The following examples show how to set up automatic encryption using :ref:`mongoc_client_encryption_t` to create a new encryption data key. .. note:: @@ -42,8 +41,8 @@ Providing Local Automatic Encryption Rules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example shows how to specify automatic encryption rules using a schema map set with -`mongoc_auto_encryption_opts_set_schema_map <{+api-libmongoc+}/mongoc_auto_encryption_opts_set_schema_map.html>`__. -The automatic encryption rules are expressed using a strict subset of the JSON Schema syntax. +:ref:`mongoc_auto_encryption_opts_set_schema_map`. The automatic encryption rules are expressed using a strict +subset of the JSON Schema syntax. 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 @@ -63,7 +62,7 @@ The MongoDB 4.2 server supports using schema validation to enforce encryption of This schema validation will prevent an application from inserting unencrypted values for any fields marked with the "encrypt" JSON schema keyword. -The following example shows how to set up automatic encryption using `mongoc_client_encryption_t <{+api-libmongoc+}/mongoc_client_encryption_t.html>`__ to create +The following example shows how to set up automatic encryption using :ref:`mongoc_client_encryption_t` to create a new encryption data key and create a collection with the necessary JSON Schema: .. literalinclude:: /libmongoc/includes/examples/client-side-encryption-server-schema.c @@ -76,7 +75,7 @@ Explicit Encryption ~~~~~~~~~~~~~~~~~~~ Explicit encryption is a MongoDB community feature and does not use :ref:`query_analysis` (``mongocryptd`` or -``crypt_shared``). Explicit encryption is provided by the `mongoc_client_encryption_t <{+api-libmongoc+}/mongoc_client_encryption_t.html>`__ class, for example: +``crypt_shared``). Explicit encryption is provided by the :ref:`mongoc_client_encryption_t` class, for example: .. literalinclude:: /libmongoc/includes/examples/client-side-encryption-explicit.c :caption: client-side-encryption-explicit.c @@ -87,7 +86,7 @@ Explicit Encryption with Automatic Decryption Although automatic encryption requires MongoDB 4.2 enterprise or a MongoDB 4.2 Atlas cluster, automatic decryption is supported for all users. To configure automatic decryption without automatic encryption set ``bypass_auto_encryption=True`` -in `mongoc_auto_encryption_opts_t <{+api-libmongoc+}/mongoc_auto_encryption_opts_t.html>`__: +in :ref:`mongoc_auto_encryption_opts_t`: .. literalinclude:: /libmongoc/includes/examples/client-side-encryption-auto-decryption.c :caption: client-side-encryption-auto-decryption.c diff --git a/source/libmongoc/guides/configuring_tls.txt b/source/libmongoc/guides/configuring_tls.txt index 93e96114..c366a0c4 100644 --- a/source/libmongoc/guides/configuring_tls.txt +++ b/source/libmongoc/guides/configuring_tls.txt @@ -29,10 +29,9 @@ The following URI options may be used to further configure TLS: Configuration with mongoc_ssl_opt_t ----------------------------------- -Alternatively, the `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ struct may be used -to configure TLS with `mongoc_client_set_ssl_opts <{+api-libmongoc+}/mongoc_client_set_ssl_opts.html>`__ -or `mongoc_client_pool_set_ssl_opts <{+api-libmongoc+}/mongoc_client_pool_set_ssl_opts.html>`__. -Most of the configurable options can be set using the :manual:`Connection String URI `. +Alternatively, the :ref:`mongoc_ssl_opt_t` struct may be used to configure TLS with :ref:`mongoc_client_set_ssl_opts` +or :ref:`mongoc_client_pool_set_ssl_opts`. Most of the configurable options can be set using the +:manual:`Connection String URI `. .. list-table:: :header-rows: 1 @@ -56,7 +55,7 @@ Most of the configurable options can be set using the :manual:`Connection String * - | allow_invalid_hostname - | tlsAllowInvalidHostnames -The only exclusions are ``crl_file`` and ``ca_dir``. Those may only be set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__. +The only exclusions are ``crl_file`` and ``ca_dir``. Those may only be set with :ref:`mongoc_ssl_opt_t`. Client Authentication --------------------- @@ -127,12 +126,12 @@ build against it with: When compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the distribution. That can be overridden by setting the ``tlsCAFile`` URI option or with the fields ``ca_file`` and ``ca_dir`` -in the `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__. +in the :ref:`mongoc_ssl_opt_t`. The Online Certificate Status Protocol (OCSP) (see `RFC 6960 `__) is fully supported when using OpenSSL 1.0.1+ with the following notes: -- When a ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__, and the ``crl_file`` revokes the server's certificate, the certificate +- When a ``crl_file`` is set with :ref:`mongoc_ssl_opt_t`, and the ``crl_file`` revokes the server's certificate, the certificate is considered revoked (even if the certificate has a valid stapled OCSP response) LibreSSL / libtls @@ -141,7 +140,7 @@ LibreSSL / libtls The MongoDB C Driver supports LibreSSL through the use of OpenSSL compatibility checks when configured to compile against ``openssl``. It also supports the new ``libtls`` library when configured to build against ``libressl``. -When compiled against the Windows native libraries, the ``crl_file`` option of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ is not supported, +When compiled against the Windows native libraries, the ``crl_file`` option of a :ref:`mongoc_ssl_opt_t` is not supported, and will issue an error if used. Setting ``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck`` has no effect. @@ -160,7 +159,7 @@ Native TLS Support on Windows (Secure Channel) The MongoDB C Driver supports the Windows native TLS library (Secure Channel, or SChannel), and its native crypto library (Cryptography API: Next Generation, or CNG). -When compiled against the Windows native libraries, the ``ca_dir`` option of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ is not supported, +When compiled against the Windows native libraries, the ``ca_dir`` option of a :ref:`mongoc_ssl_opt_t` is not supported, and will issue an error if used. Encrypted PEM files (e.g., setting ``tlsCertificateKeyPassword``) are also not supported, and will result in error when @@ -170,7 +169,7 @@ When ``tlsCAFile`` is set, the driver will only allow server certificates issued When no ``tlsCAFile`` is set, the driver will look up the Certificate Authority using the ``System Local Machine Root`` certificate store to confirm the provided certificate. -When ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__, the driver will import the revocation list to the +When ``crl_file`` is set with :ref:`mongoc_ssl_opt_t`, the driver will import the revocation list to the ``System Local Machine Root`` certificate store. Setting ``tlsDisableOCSPEndpointCheck`` has no effect. @@ -180,7 +179,7 @@ with the following notes: - The Must-Staple extension (see `RFC 7633 `__) is ignored. Connection may continue if a Must-Staple certificate is presented with no stapled response (unless the client receives a revoked response from an OCSP responder). -- When a ``crl_file`` is set with `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__, and the ``crl_file`` revokes the server's certificate, the OCSP response +- When a ``crl_file`` is set with :ref:`mongoc_ssl_opt_t`, and the ``crl_file`` revokes the server's certificate, the OCSP response takes precedence. E.g. if the server presents a certificate with a valid stapled OCSP response, the certificate is considered valid even if the ``crl_file`` marks it as revoked. - Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down. @@ -193,7 +192,7 @@ Native TLS Support on macOS / Darwin (Secure Transport) The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.) native TLS library (Secure Transport), and its native crypto library (Common Crypto, or CC). -When compiled against Secure Transport, the ``ca_dir`` and ``crl_file`` options of a `mongoc_ssl_opt_t <{+api-libmongoc+}/mongoc_ssl_opt_t.html>`__ are not supported. +When compiled against Secure Transport, the ``ca_dir`` and ``crl_file`` options of a :ref:`mongoc_ssl_opt_t` are not supported. An error is issued if either are used. When ``tlsCAFile`` is set, the driver will only allow server certificates issued by the authority (or authorities) provided. diff --git a/source/libmongoc/guides/connection-pooling.txt b/source/libmongoc/guides/connection-pooling.txt index 5f0ea23b..aa7fe358 100644 --- a/source/libmongoc/guides/connection-pooling.txt +++ b/source/libmongoc/guides/connection-pooling.txt @@ -18,7 +18,7 @@ monitor the MongoDB server topology, so the program need not block to scan it. Single Mode ----------- -In single mode, your program creates a `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__ directly: +In single mode, your program creates a :ref:`mongoc_client_t` directly: .. code-block:: c @@ -41,7 +41,7 @@ the topology and performing normal operations. Pooled Mode ----------- -To activate pooled mode, create a `mongoc_client_pool_t <{+api-libmongoc+}/mongoc_client_pool_t.html>`__: +To activate pooled mode, create a :ref:`mongoc_client_pool_t`: .. code-block:: c @@ -50,11 +50,11 @@ To activate pooled mode, create a `mongoc_client_pool_t <{+api-libmongoc+}/mongo mongoc_client_pool_t *pool = mongoc_client_pool_new (uri); -When your program first calls `mongoc_client_pool_pop <{+api-libmongoc+}/mongoc_client_pool_pop.html>`__, the pool -launches monitoring threads in the background. Monitoring threads independently connect to all servers in the connection -string. As monitoring threads receive hello responses from the servers, they update the shared view of the server topology. -Additional monitoring threads and connections are created as new servers are discovered. Monitoring threads are terminated -when servers are removed from the shared view of the server topology. +When your program first calls :ref:`mongoc_client_pool_pop`, the pool launches monitoring threads in the background. +Monitoring threads independently connect to all servers in the connection string. As monitoring threads receive hello +responses from the servers, they update the shared view of the server topology. Additional monitoring threads and +connections are created as new servers are discovered. Monitoring threads are terminated when servers are removed from +the shared view of the server topology. Each thread that executes MongoDB operations must check out a client from the pool: @@ -66,8 +66,7 @@ Each thread that executes MongoDB operations must check out a client from the po mongoc_client_pool_push (pool, client); -The `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__ object is not thread-safe, only the `mongoc_client_pool_t -<{+api-libmongoc+}/mongoc_client_pool_t.html>`__ is. +The :ref:`mongoc_client_t` object is not thread-safe, only the :ref:`mongoc_client_pool_t` is. When the driver is in pooled mode, your program's operations are unblocked as soon as monitoring discovers a usable server. For example, if a thread in your program is waiting to execute an "insert" on the primary, it is unblocked @@ -75,12 +74,10 @@ as soon as the primary is discovered, rather than waiting for all secondaries to The pool opens one connection per server for monitoring, and each client opens its own connection to each server it uses for application operations. Background monitoring threads re-scan servers independently roughly every 10 -seconds. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See `mongoc_uri_t -<{+api-libmongoc+}/mongoc_uri_t.html>`__.) +seconds. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__.) -The connection string can also specify ``waitQueueTimeoutMS`` to limit the time that `mongoc_client_pool_pop -<{+api-libmongoc+}/mongoc_client_pool_pop.html>`__ will wait for a client from the pool. (See `mongoc_uri_t -<{+api-libmongoc+}/mongoc_uri_t.html>`__.) If ``waitQueueTimeoutMS`` is specified, then it is necessary +The connection string can also specify ``waitQueueTimeoutMS`` to limit the time that :ref:`mongoc_client_pool_pop` will +wait for a client from the pool. (See `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__.) If ``waitQueueTimeoutMS`` is specified, then it is necessary to confirm that a client was actually returned: .. code-block:: c @@ -100,6 +97,5 @@ to confirm that a client was actually returned: /* take appropriate action for a timeout */ } -See :ref:`connection_pool_options` to configure pool size and behavior, and see `mongoc_client_pool_t -<{+api-libmongoc+}/mongoc_client_pool_t.html>`__ for an extended example of a multi-threaded program that uses -the driver in pooled mode. +See :ref:`connection_pool_options` to configure pool size and behavior, and see :ref:`mongoc_client_pool_t` +for an extended example of a multi-threaded program that uses the driver in pooled mode. diff --git a/source/libmongoc/guides/cursors.txt b/source/libmongoc/guides/cursors.txt index 1fbbb71c..ca3b9e05 100644 --- a/source/libmongoc/guides/cursors.txt +++ b/source/libmongoc/guides/cursors.txt @@ -50,7 +50,7 @@ how to robustly check for errors. Destroying Server-Side Cursors ------------------------------ -The MongoDB C driver will automatically destroy a server-side cursor when `mongoc_cursor_destroy <{+api-libmongoc+}/mongoc_cursor_destroy.html>`__ +The MongoDB C driver will automatically destroy a server-side cursor when :ref:`mongoc_cursor_destroy` is called. Failure to call this function when done with a cursor will leak memory client side as well as consume extra memory server side. If the cursor was configured to never timeout, it will become a memory leak on the server. @@ -62,7 +62,7 @@ Tailable Cursors Tailable cursors are cursors that remain open even after they've returned a final result. This way, if more documents are added to a collection (i.e., to the cursor's result set), then you can continue to -call `mongoc_cursor_next <{+api-libmongoc+}/mongoc_cursor_next.html>`__ to retrieve those additional results. +call :ref:`mongoc_cursor_next` to retrieve those additional results. Here's a complete test case that demonstrates the use of tailable cursors. @@ -104,5 +104,5 @@ The line of output is a sample from performing ``db.test.insert({})`` from the m .. seealso:: - | `mongoc_cursor_set_max_await_time_ms <{+api-libmongoc+}/mongoc_cursor_set_max_await_time_ms.html>`__. + | :ref:`mongoc_cursor_set_max_await_time_ms`. diff --git a/source/libmongoc/guides/distinct-mapreduce.txt b/source/libmongoc/guides/distinct-mapreduce.txt index 3ecb4dba..024736ca 100644 --- a/source/libmongoc/guides/distinct-mapreduce.txt +++ b/source/libmongoc/guides/distinct-mapreduce.txt @@ -46,9 +46,9 @@ First define the ``map`` and ``reduce`` functions: :language: c :caption: constants.c -Run the ``mapReduce`` command. Use the generic command helpers (e.g. `mongoc_database_command_simple <{+api-libmongoc+}/mongoc_database_command_simple.html>`__). -Do not the read command helpers (e.g. `mongoc_database_read_command_with_opts <{+api-libmongoc+}/mongoc_database_read_command_with_opts.html>`__) -because they are considered retryable read operations. If retryable reads are enabled, those operations will retry once on +Run the ``mapReduce`` command. Use the generic command helpers (e.g. :ref:`mongoc_database_command_simple`). +Do not the read command helpers (e.g. :ref:`mongoc_database_read_command_with_opts`) because they are +considered retryable read operations. If retryable reads are enabled, those operations will retry once on a retryable error, giving undesirable behavior for ``mapReduce``. .. literalinclude:: /libmongoc/includes/examples/basic_aggregation/map-reduce-basic.c diff --git a/source/libmongoc/guides/in-use-encryption.txt b/source/libmongoc/guides/in-use-encryption.txt index 17421a8e..0972ba30 100644 --- a/source/libmongoc/guides/in-use-encryption.txt +++ b/source/libmongoc/guides/in-use-encryption.txt @@ -36,18 +36,16 @@ to require In-Use Encryption be enabled. API --- -`mongoc_client_encryption_t <{+api-libmongoc+}/mongoc_client_encryption_t.html>`__ is used for explicit encryption and key management. -`mongoc_client_enable_auto_encryption <{+api-libmongoc+}/mongoc_client_enable_auto_encryption.html>`__ and -`mongoc_client_pool_enable_auto_encryption <{+api-libmongoc+}/mongoc_client_pool_enable_auto_encryption.html>`__ +:ref:`mongoc_client_encryption_t` is used for explicit encryption and key management. +:ref:`mongoc_client_enable_auto_encryption` and :ref:`mongoc_client_pool_enable_auto_encryption` is used to enable automatic encryption. The Queryable Encryption and CSFLE features share much of the same API with some exceptions. -- The supported algorithms documented in `mongoc_client_encryption_encrypt_opts_set_algorithm <{+api-libmongoc+}/mongoc_client_encryption_encrypt_opts_set_algorithm.html>`__ +- The supported algorithms documented in :ref:`mongoc_client_encryption_encrypt_opts_set_algorithm` do not apply to both features. -- `mongoc_auto_encryption_opts_set_encrypted_fields_map <{+api-libmongoc+}/mongoc_auto_encryption_opts_set_encrypted_fields_map.html>`__ - only applies to Queryable Encryption. -- `mongoc_auto_encryption_opts_set_schema_map <{+api-libmongoc+}/mongoc_auto_encryption_opts_set_schema_map.html>`__ only applies to CSFLE. +- :ref:`mongoc_auto_encryption_opts_set_encrypted_fields_map` only applies to Queryable Encryption. +- :ref:`mongoc_auto_encryption_opts_set_schema_map` only applies to CSFLE. .. _query_analysis: @@ -61,7 +59,7 @@ To support the automatic encryption feature, one of the following dependencies a - The ``crypt_shared`` library. See the MongoDB Manual documentation: `Automatic Encryption Shared Library `__ -A `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__ or `mongoc_client_pool_t <{+api-libmongoc+}/mongoc_client_pool_t.html>`__ configured with auto encryption will automatically -try to load the ``crypt_shared`` library. If loading the ``crypt_shared`` library fails, the `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__ -or `mongoc_client_pool_t <{+api-libmongoc+}/mongoc_client_pool_t.html>`__ will try to spawn the ``mongocryptd`` process from the application's ``PATH``. -To configure use of ``crypt_shared`` and ``mongocryptd`` see `mongoc_auto_encryption_opts_set_extra <{+api-libmongoc+}/mongoc_auto_encryption_opts_set_extra.html>`__. +A :ref:`mongoc_client_t` or :ref:`mongoc_client_pool_t` configured with auto encryption will automatically +try to load the ``crypt_shared`` library. If loading the ``crypt_shared`` library fails, the :ref:`mongoc_client_t` +or :ref:`mongoc_client_pool_t` will try to spawn the ``mongocryptd`` process from the application's ``PATH``. +To configure use of ``crypt_shared`` and ``mongocryptd`` see :ref:`mongoc_auto_encryption_opts_set_extra`. diff --git a/source/libmongoc/guides/manage-collection-indexes.txt b/source/libmongoc/guides/manage-collection-indexes.txt index 03a2cb77..45c9312f 100644 --- a/source/libmongoc/guides/manage-collection-indexes.txt +++ b/source/libmongoc/guides/manage-collection-indexes.txt @@ -4,7 +4,7 @@ Manage Collection Indexes ========================= -To create indexes on a MongoDB collection, use `mongoc_collection_create_indexes_with_opts <{+api-libmongoc+}/mongoc_collection_create_indexes_with_opts.html>`__: +To create indexes on a MongoDB collection, use :ref:`mongoc_collection_create_indexes_with_opts`: .. literalinclude:: /libmongoc/includes/examples/example-manage-collection-indexes.c :language: c @@ -12,7 +12,7 @@ To create indexes on a MongoDB collection, use `mongoc_collection_create_indexes :end-before: // Create an index ... end :dedent: 6 -To list indexes, use `mongoc_collection_find_indexes_with_opts <{+api-libmongoc+}/mongoc_collection_find_indexes_with_opts.html>`__: +To list indexes, use :ref:`mongoc_collection_find_indexes_with_opts`: .. literalinclude:: /libmongoc/includes/examples/example-manage-collection-indexes.c :language: c @@ -20,8 +20,8 @@ To list indexes, use `mongoc_collection_find_indexes_with_opts <{+api-libmongoc+ :end-before: // List indexes ... end :dedent: 6 -To drop an index, use `mongoc_collection_drop_index_with_opts <{+api-libmongoc+}/mongoc_collection_drop_index_with_opts.html>`__. -The index name may be obtained from the ``keys`` document with `mongoc_collection_keys_to_index_string <{+api-libmongoc+}/mongoc_collection_keys_to_index_string.html>`__: +To drop an index, use :ref:`mongoc_collection_drop_index_with_opts`. The index name may be obtained +from the ``keys`` document with :ref:`mongoc_collection_keys_to_index_string`: .. literalinclude:: /libmongoc/includes/examples/example-manage-collection-indexes.c :language: c diff --git a/source/libmongoc/includes/aggregate-opts.txt b/source/libmongoc/includes/aggregate-opts.txt index 5188db06..9079c40d 100644 --- a/source/libmongoc/includes/aggregate-opts.txt +++ b/source/libmongoc/includes/aggregate-opts.txt @@ -6,13 +6,13 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``readConcern``: Construct a `mongoc_read_concern_t <{+api-libmongoc+}/mongoc_read_concern_t.html>`__ and use `mongoc_read_concern_append <{+api-libmongoc+}/mongoc_read_concern_append.html>`__ to add the read concern to ``opts``. See the example code for `mongoc_client_read_command_with_opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from opts-source, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from opts-source, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. -* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. -* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to `mongoc_cursor_next <{+api-libmongoc+}/mongoc_cursor_next.html>`__ +* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. +* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to :ref:`mongoc_cursor_next` * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Only string values are supported prior to MongoDB 4.4. +* ``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. Only string values are supported prior to MongoDB 4.4. * ``hint``: A document or string that specifies the index to use to support the query predicate. diff --git a/source/libmongoc/includes/bulk-insert-opts.txt b/source/libmongoc/includes/bulk-insert-opts.txt index 36470889..601915ff 100644 --- a/source/libmongoc/includes/bulk-insert-opts.txt +++ b/source/libmongoc/includes/bulk-insert-opts.txt @@ -6,5 +6,5 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. +- ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. diff --git a/source/libmongoc/includes/bulk-opts.txt b/source/libmongoc/includes/bulk-opts.txt index f502a42c..be513b79 100644 --- a/source/libmongoc/includes/bulk-opts.txt +++ b/source/libmongoc/includes/bulk-opts.txt @@ -6,8 +6,8 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``ordered``: set to ``false`` to attempt to insert all documents, continuing after errors. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``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. diff --git a/source/libmongoc/includes/bulk-replace-one-opts.txt b/source/libmongoc/includes/bulk-replace-one-opts.txt index 6552cdf9..95128dfe 100644 --- a/source/libmongoc/includes/bulk-replace-one-opts.txt +++ b/source/libmongoc/includes/bulk-replace-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. +- ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. - ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. diff --git a/source/libmongoc/includes/bulk-update-many-opts.txt b/source/libmongoc/includes/bulk-update-many-opts.txt index 58135e9d..469a3bd1 100644 --- a/source/libmongoc/includes/bulk-update-many-opts.txt +++ b/source/libmongoc/includes/bulk-update-many-opts.txt @@ -2,7 +2,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. +- ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. - ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. - ``hint``: A document or string that specifies the index to use to support the query predicate. - ``upsert``: If true, insert a document if none match ``selector``. diff --git a/source/libmongoc/includes/bulk-update-one-opts.txt b/source/libmongoc/includes/bulk-update-one-opts.txt index 5f41a3ec..74fa9c60 100644 --- a/source/libmongoc/includes/bulk-update-one-opts.txt +++ b/source/libmongoc/includes/bulk-update-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``hint``: A document or string that specifies the index to use to support the query predicate. * ``upsert``: If true, insert a document if none match ``selector``. diff --git a/source/libmongoc/includes/change-stream-opts.txt b/source/libmongoc/includes/change-stream-opts.txt index f68c9fc4..a746970c 100644 --- a/source/libmongoc/includes/change-stream-opts.txt +++ b/source/libmongoc/includes/change-stream-opts.txt @@ -6,12 +6,12 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to `mongoc_change_stream_next <{+api-libbson+}/mongoc_change_stream_next.html>`__ -* ``resumeAfter``: A ``Document`` representing the logical starting point of the change stream. The result of `mongoc_change_stream_get_resume_token <{+api-libbson+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. -* ``startAfter``: A ``Document`` representing the logical starting point of the change stream. Unlike ``resumeAfter``, this can resume notifications after an "invalidate" event. The result of `mongoc_change_stream_get_resume_token <{+api-libbson+}/mongoc_change_stream_get_resume_token.html>`__ or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. +* ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to :ref:`mongoc_change_stream_next` +* ``resumeAfter``: A ``Document`` representing the logical starting point of the change stream. The result of :ref:`mongoc_change_stream_get_resume_token` or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. +* ``startAfter``: A ``Document`` representing the logical starting point of the change stream. Unlike ``resumeAfter``, this can resume notifications after an "invalidate" event. The result of :ref:`mongoc_change_stream_get_resume_token` or the ``_id`` field of any change received from a change stream can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. * ``startAtOperationTime``: A ``Timestamp``. The change stream only provides changes that occurred at or after the specified timestamp. Any command run against the server will return an operation time that can be used here. This option is mutually exclusive with ``resumeAfter`` and ``startAfter``. -* ``maxAwaitTimeMS``: An ``int64`` representing the maximum amount of time a call to `mongoc_change_stream_next <{+api-libbson+}/mongoc_change_stream_next.html>`__ will block waiting for data +* ``maxAwaitTimeMS``: An ``int64`` representing the maximum amount of time a call to :ref:`mongoc_change_stream_next` will block waiting for data * ``fullDocument``: An optional UTF-8 string. Set this option to "default", "updateLookup", "whenAvailable", or "required", If unset, The string "default" is assumed. Set this option to "updateLookup" to direct the change stream cursor to lookup the most current majority-committed version of the document associated to an update change stream event. * ``fullDocumentBeforeChange``: An optional UTF-8 string. Set this option to "whenAvailable", "required", or "off". When unset, the default value is "off". Similar to "fullDocument", but returns the value of the document before the associated change. * ``showExpandedEvents``: Set to ``true`` to return an expanded list of change stream events. Available only on MongoDB versions >=6.0 -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Only string values are supported prior to MongoDB 4.4. +* ``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. Only string values are supported prior to MongoDB 4.4. diff --git a/source/libmongoc/includes/count-document-opts.txt b/source/libmongoc/includes/count-document-opts.txt index 3f42abbc..72f37dcf 100644 --- a/source/libmongoc/includes/count-document-opts.txt +++ b/source/libmongoc/includes/count-document-opts.txt @@ -6,11 +6,11 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``readConcern``: Construct a `mongoc_read_concern_t <{+api-libmongoc+}/mongoc_read_concern_t.html>`__ and use `mongoc_read_concern_append <{+api-libmongoc+}/mongoc_read_concern_append.html>`__ to add the read concern to ``opts``. See the example code for `mongoc_client_read_command_with_opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from opts-source, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from opts-source, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. -* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. +* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. * ``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 `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ specifying the comment to attach to this command. The comment will appear in log messages, profiler output, and currentOp output. Only string values are supported prior to MongoDB 4.4. +* ``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. Only string values are supported prior to MongoDB 4.4. * ``hint``: A document or string that specifies the index to use to support the query predicate. diff --git a/source/libmongoc/includes/create-index-opts.txt b/source/libmongoc/includes/create-index-opts.txt index e55ed8ff..c4192c36 100644 --- a/source/libmongoc/includes/create-index-opts.txt +++ b/source/libmongoc/includes/create-index-opts.txt @@ -6,5 +6,5 @@ ``command_opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. diff --git a/source/libmongoc/includes/delete-many-opts.txt b/source/libmongoc/includes/delete-many-opts.txt index 27102427..0a54a58e 100644 --- a/source/libmongoc/includes/delete-many-opts.txt +++ b/source/libmongoc/includes/delete-many-opts.txt @@ -6,10 +6,10 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``hint``: A document or string that specifies the index to use to support the query predicate. * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. diff --git a/source/libmongoc/includes/delete-one-opts.txt b/source/libmongoc/includes/delete-one-opts.txt index e212ef47..9e8d3221 100644 --- a/source/libmongoc/includes/delete-one-opts.txt +++ b/source/libmongoc/includes/delete-one-opts.txt @@ -6,11 +6,11 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -- ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ - that overrides the options inherited from ``collection``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -- ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -- ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +- ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` + that overrides the options inherited from ``collection``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +- ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +- ``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. - ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. - ``hint``: A document or string that specifies the index to use to support the query predicate. - ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. diff --git a/source/libmongoc/includes/find-and-modify-appended-opts.txt b/source/libmongoc/includes/find-and-modify-appended-opts.txt index f6efec69..af5d31e0 100644 --- a/source/libmongoc/includes/find-and-modify-appended-opts.txt +++ b/source/libmongoc/includes/find-and-modify-appended-opts.txt @@ -6,8 +6,8 @@ ``extra`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``hint``: A document or string that specifies the index to use to support the query predicate. * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``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. diff --git a/source/libmongoc/includes/generic-opts.txt b/source/libmongoc/includes/generic-opts.txt index b9eee2dd..a1dafa6a 100644 --- a/source/libmongoc/includes/generic-opts.txt +++ b/source/libmongoc/includes/generic-opts.txt @@ -2,5 +2,5 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/includes/gridfs-bucket-opts.txt b/source/libmongoc/includes/gridfs-bucket-opts.txt index 6c2481eb..2ee5c1cd 100644 --- a/source/libmongoc/includes/gridfs-bucket-opts.txt +++ b/source/libmongoc/includes/gridfs-bucket-opts.txt @@ -8,5 +8,5 @@ * ``bucketName``: A UTF-8 string used as the prefix to the GridFS "chunks" and "files" collections. Defaults to "fs". The bucket name, together with the database and suffix collections must not exceed 120 characters. See the manual for `the max namespace length `_. * ``chunkSizeBytes``: An ``int32`` representing the chunk size. Defaults to 255KB. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``readConcern``: Construct a `mongoc_read_concern_t <{+api-libmongoc+}/mongoc_read_concern_t.html>`__ and use `mongoc_read_concern_append <{+api-libmongoc+}/mongoc_read_concern_append.html>`__ to add the read concern to ``opts``. See the example code for `mongoc_client_read_command_with_opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. diff --git a/source/libmongoc/includes/init_cleanup.txt b/source/libmongoc/includes/init_cleanup.txt index 217fb4c3..8461dd4f 100644 --- a/source/libmongoc/includes/init_cleanup.txt +++ b/source/libmongoc/includes/init_cleanup.txt @@ -1,12 +1,12 @@ :orphan: -Initialize the MongoDB C Driver by calling `mongoc_init <{+api-libmongoc+}/mongoc_init.html>`__ exactly once at the beginning of your program. +Initialize the MongoDB C Driver by calling :ref:`mongoc_init` exactly once at the beginning of your program. It is responsible for initializing global state such as process counters, SSL, and threading primitives. Exception to this is ``mongoc_log_set_handler()``, which should be called before ``mongoc_init()`` or some log traces would not use your log handling function. See :ref:`Custom Log Handlers ` for a detailed example. -Call `mongoc_cleanup <{+api-libmongoc+}/mongoc_cleanup.html>`__ exactly once at the end of your program to release all memory and other resources -allocated by the driver. You must not call any other MongoDB C Driver functions after `mongoc_cleanup <{+api-libmongoc+}/mongoc_cleanup.html>`__. -Note that `mongoc_init <{+api-libmongoc+}/mongoc_init.html>`__ does **not** reinitialize the driver after `mongoc_cleanup <{+api-libmongoc+}/mongoc_cleanup.html>`__. +Call :ref:`mongoc_cleanup` exactly once at the end of your program to release all memory and other resources +allocated by the driver. You must not call any other MongoDB C Driver functions after :ref:`mongoc_cleanup`. +Note that :ref:`mongoc_init` does **not** reinitialize the driver after :ref:`mongoc_cleanup`. diff --git a/source/libmongoc/includes/insert-many-opts.txt b/source/libmongoc/includes/insert-many-opts.txt index d90d3ace..e210d63e 100644 --- a/source/libmongoc/includes/insert-many-opts.txt +++ b/source/libmongoc/includes/insert-many-opts.txt @@ -6,9 +6,9 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``ordered``: set to ``false`` to attempt to insert all documents, continuing after errors. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. diff --git a/source/libmongoc/includes/insert-one-opts.txt b/source/libmongoc/includes/insert-one-opts.txt index 9cca8214..207dc823 100644 --- a/source/libmongoc/includes/insert-one-opts.txt +++ b/source/libmongoc/includes/insert-one-opts.txt @@ -6,8 +6,8 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``collection``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``collection``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. diff --git a/source/libmongoc/includes/mongoc_client_pool_call_once.txt b/source/libmongoc/includes/mongoc_client_pool_call_once.txt index d7f59ccd..f5b6353b 100644 --- a/source/libmongoc/includes/mongoc_client_pool_call_once.txt +++ b/source/libmongoc/includes/mongoc_client_pool_call_once.txt @@ -3,4 +3,4 @@ Thread Safety ------------- -This function can only be called once on a pool, and must be called before the first call to `mongoc_client_pool_pop <{+api-libmongoc+}/mongoc_client_pool_pop.html>`__. +This function can only be called once on a pool, and must be called before the first call to :ref:`mongoc_client_pool_pop`. diff --git a/source/libmongoc/includes/opts-sources.txt b/source/libmongoc/includes/opts-sources.txt index 131d749f..3544bf10 100644 --- a/source/libmongoc/includes/opts-sources.txt +++ b/source/libmongoc/includes/opts-sources.txt @@ -10,4 +10,4 @@ Transaction Transaction Transaction ================== ============== ============== ========= In a transaction, read concern and write concern are prohibited in ``opts`` and the read preference must be primary or NULL. -`See the example for transactions <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__ and for `the "distinct" command with opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. +:ref:`See the example for transactions ` and for :ref:`the "distinct" command with opts `. diff --git a/source/libmongoc/includes/read-opts-sources.txt b/source/libmongoc/includes/read-opts-sources.txt index ae216a83..43550f71 100644 --- a/source/libmongoc/includes/read-opts-sources.txt +++ b/source/libmongoc/includes/read-opts-sources.txt @@ -32,4 +32,5 @@ Transaction Transaction ``database,`` ``client``, ``collection`` ================== ============== ========= -`See the example for transactions <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__ and for `the "distinct" command with opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. +:ref:`See the example for transactions ` and for :ref:`the "distinct" command with opts +`. diff --git a/source/libmongoc/includes/read-opts.txt b/source/libmongoc/includes/read-opts.txt index 1e21ccd4..55f2f63e 100644 --- a/source/libmongoc/includes/read-opts.txt +++ b/source/libmongoc/includes/read-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``readConcern``: Construct a `mongoc_read_concern_t <{+api-libmongoc+}/mongoc_read_concern_t.html>`__ and use `mongoc_read_concern_append <{+api-libmongoc+}/mongoc_read_concern_append.html>`__ to add the read concern to ``opts``. See the example code for `mongoc_client_read_command_with_opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. -* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. +* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/includes/read-write-opts-sources.txt b/source/libmongoc/includes/read-write-opts-sources.txt index 8eb5c922..ccf3bd2c 100644 --- a/source/libmongoc/includes/read-write-opts-sources.txt +++ b/source/libmongoc/includes/read-write-opts-sources.txt @@ -27,4 +27,5 @@ before 3.4. - ``database,`` ``collection``, or ``client`` - -`See the example for transactions <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__ and for `the "distinct" command with opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. +:ref:`See the example for transactions ` and for :ref:`the "distinct" command with opts +`. diff --git a/source/libmongoc/includes/read-write-opts.txt b/source/libmongoc/includes/read-write-opts.txt index f3e707f1..4fc59249 100644 --- a/source/libmongoc/includes/read-write-opts.txt +++ b/source/libmongoc/includes/read-write-opts.txt @@ -6,8 +6,8 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``readConcern``: Construct a `mongoc_read_concern_t <{+api-libmongoc+}/mongoc_read_concern_t.html>`__ and use `mongoc_read_concern_append <{+api-libmongoc+}/mongoc_read_concern_append.html>`__ to add the read concern to ``opts``. See the example code for `mongoc_client_read_command_with_opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +* ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. -* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. +* ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/includes/replace-one-opts.txt b/source/libmongoc/includes/replace-one-opts.txt index fbac72bc..9ea78722 100644 --- a/source/libmongoc/includes/replace-one-opts.txt +++ b/source/libmongoc/includes/replace-one-opts.txt @@ -6,10 +6,10 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``hint``: A document or string that specifies the index to use to support the query predicate. diff --git a/source/libmongoc/includes/returns-cursor.txt b/source/libmongoc/includes/returns-cursor.txt index 9d6c0a6c..3931725a 100644 --- a/source/libmongoc/includes/returns-cursor.txt +++ b/source/libmongoc/includes/returns-cursor.txt @@ -1,10 +1,10 @@ :orphan: -This function returns a newly allocated `mongoc_cursor_t <{+api-libmongoc+}/mongoc_cursor_t.html>`__ that should be freed with `mongoc_cursor_destroy <{+api-libmongoc+}/mongoc_cursor_destroy.html>`__ -when no longer in use. The returned `mongoc_cursor_t <{+api-libmongoc+}/mongoc_cursor_t.html>`__ is never ``NULL``, even on error. The user must call -`mongoc_cursor_next <{+api-libmongoc+}/mongoc_cursor_next.html>`__ on the returned `mongoc_cursor_t <{+api-libmongoc+}/mongoc_cursor_t.html>`__ to execute the initial command. +This function returns a newly allocated :ref:`mongoc_cursor_t` that should be freed with :ref:`mongoc_cursor_destroy` +when no longer in use. The returned :ref:`mongoc_cursor_t` is never ``NULL``, even on error. The user must call +:ref:`mongoc_cursor_next` on the returned :ref:`mongoc_cursor_t` to execute the initial command. -Cursor errors can be checked with `mongoc_cursor_error_document <{+api-libmongoc+}/mongoc_cursor_error_document.html>`__. It always fills out the `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ if +Cursor errors can be checked with :ref:`mongoc_cursor_error_document`. It always fills out the `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ if an error occurred, and optionally includes a server reply document if the error occurred server-side. .. warning:: diff --git a/source/libmongoc/includes/seealso/authmechanism.txt b/source/libmongoc/includes/seealso/authmechanism.txt index b3bcde4e..2186f9f9 100644 --- a/source/libmongoc/includes/seealso/authmechanism.txt +++ b/source/libmongoc/includes/seealso/authmechanism.txt @@ -4,14 +4,14 @@ | :ref:`authentication` - | `mongoc_uri_get_auth_mechanism <{+api-libmongoc+}/mongoc_uri_get_auth_mechanism.html>`__ + | :ref:`mongoc_uri_get_auth_mechanism` - | `mongoc_uri_get_auth_source <{+api-libmongoc+}/mongoc_uri_get_auth_source.html>`__ + | :ref:`mongoc_uri_get_auth_source` - | `mongoc_uri_get_mechanism_properties <{+api-libmongoc+}/mongoc_uri_get_mechanism_properties.html>`__ + | :ref:`mongoc_uri_get_mechanism_properties` - | `mongoc_uri_set_auth_mechanism <{+api-libmongoc+}/mongoc_uri_set_auth_mechanism.html>`__ + | :ref:`mongoc_uri_set_auth_mechanism` - | `mongoc_uri_set_auth_source <{+api-libmongoc+}/mongoc_uri_set_auth_source.html>`__ + | :ref:`mongoc_uri_set_auth_source` - | `mongoc_uri_set_mechanism_properties <{+api-libmongoc+}/mongoc_uri_set_mechanism_properties.html>`__ + | :ref:`mongoc_uri_set_mechanism_properties` diff --git a/source/libmongoc/includes/seealso/cursor-error.txt b/source/libmongoc/includes/seealso/cursor-error.txt index 46a381e6..7a08a0f9 100644 --- a/source/libmongoc/includes/seealso/cursor-error.txt +++ b/source/libmongoc/includes/seealso/cursor-error.txt @@ -2,6 +2,6 @@ .. seealso:: - | `mongoc_cursor_error <{+api-libmongoc+}/mongoc_cursor_error.html>`__ + | :ref:`mongoc_cursor_error` - | `mongoc_cursor_error_document <{+api-libmongoc+}/mongoc_cursor_error_document.html>`__ + | :ref:`mongoc_cursor_error_document` diff --git a/source/libmongoc/includes/seealso/session.txt b/source/libmongoc/includes/seealso/session.txt index 22b49a59..663b15ab 100644 --- a/source/libmongoc/includes/seealso/session.txt +++ b/source/libmongoc/includes/seealso/session.txt @@ -2,68 +2,68 @@ .. seealso:: - | `mongoc_client_session_abort_transaction <{+api-libmongoc+}/mongoc_client_session_abort_transaction.html>`__ + | :ref:`mongoc_client_session_abort_transaction` - | `mongoc_client_session_advance_cluster_time <{+api-libmongoc+}/mongoc_client_session_advance_cluster_time.html>`__ + | :ref:`mongoc_client_session_advance_cluster_time` - | `mongoc_client_session_advance_operation_time <{+api-libmongoc+}/mongoc_client_session_advance_operation_time.html>`__ + | :ref:`mongoc_client_session_advance_operation_time` - | `mongoc_client_session_commit_transaction <{+api-libmongoc+}/mongoc_client_session_commit_transaction.html>`__ + | :ref:`mongoc_client_session_commit_transaction` - | `mongoc_client_session_destroy <{+api-libmongoc+}/mongoc_client_session_destroy.html>`__ + | :ref:`mongoc_client_session_destroy` - | `mongoc_client_session_get_client <{+api-libmongoc+}/mongoc_client_session_get_client.html>`__ + | :ref:`mongoc_client_session_get_client` - | `mongoc_client_session_get_cluster_time <{+api-libmongoc+}/mongoc_client_session_get_cluster_time.html>`__ + | :ref:`mongoc_client_session_get_cluster_time` - | `mongoc_client_session_get_lsid <{+api-libmongoc+}/mongoc_client_session_get_lsid.html>`__ + | :ref:`mongoc_client_session_get_lsid` - | `mongoc_client_session_get_operation_time <{+api-libmongoc+}/mongoc_client_session_get_operation_time.html>`__ + | :ref:`mongoc_client_session_get_operation_time` - | `mongoc_client_session_get_opts <{+api-libmongoc+}/mongoc_client_session_get_opts.html>`__ + | :ref:`mongoc_client_session_get_opts` - | `mongoc_client_session_get_server_id <{+api-libmongoc+}/mongoc_client_session_get_server_id.html>`__ + | :ref:`mongoc_client_session_get_server_id` - | `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__ + | :ref:`mongoc_client_session_start_transaction` - | `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ + | :ref:`mongoc_client_session_t` - | `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__ + | :ref:`mongoc_client_start_session` - | `mongoc_session_opts_clone <{+api-libmongoc+}/mongoc_session_opts_clone.html>`__ + | :ref:`mongoc_session_opts_clone` - | `mongoc_session_opts_destroy <{+api-libmongoc+}/mongoc_session_opts_destroy.html>`__ + | :ref:`mongoc_session_opts_destroy` - | `mongoc_session_opts_get_causal_consistency <{+api-libmongoc+}/mongoc_session_opts_get_causal_consistency.html>`__ + | :ref:`mongoc_session_opts_get_causal_consistency` - | `mongoc_session_opts_get_default_transaction_opts <{+api-libmongoc+}/mongoc_session_opts_get_default_transaction_opts.html>`__ + | :ref:`mongoc_session_opts_get_default_transaction_opts` - | `mongoc_session_opts_get_transaction_opts <{+api-libmongoc+}/mongoc_session_opts_get_transaction_opts.html>`__ + | :ref:`mongoc_session_opts_get_transaction_opts` - | `mongoc_session_opts_new <{+api-libmongoc+}/mongoc_session_opts_new.html>`__ + | :ref:`mongoc_session_opts_new` - | `mongoc_session_opts_set_causal_consistency <{+api-libmongoc+}/mongoc_session_opts_set_causal_consistency.html>`__ + | :ref:`mongoc_session_opts_set_causal_consistency` - | `mongoc_session_opts_set_default_transaction_opts <{+api-libmongoc+}/mongoc_session_opts_set_default_transaction_opts.html>`__ + | :ref:`mongoc_session_opts_set_default_transaction_opts` - | `mongoc_transaction_opts_clone <{+api-libmongoc+}/mongoc_transaction_opts_clone.html>`__ + | :ref:`mongoc_transaction_opts_clone` - | `mongoc_transaction_opts_destroy <{+api-libmongoc+}/mongoc_transaction_opts_destroy.html>`__ + | :ref:`mongoc_transaction_opts_destroy` - | `mongoc_transaction_opts_get_max_commit_time_ms <{+api-libmongoc+}/mongoc_transaction_opts_get_max_commit_time_ms.html>`__ + | :ref:`mongoc_transaction_opts_get_max_commit_time_ms` - | `mongoc_transaction_opts_get_read_concern <{+api-libmongoc+}/mongoc_transaction_opts_get_read_concern.html>`__ + | :ref:`mongoc_transaction_opts_get_read_concern` - | `mongoc_transaction_opts_get_read_prefs <{+api-libmongoc+}/mongoc_transaction_opts_get_read_prefs.html>`__ + | :ref:`mongoc_transaction_opts_get_read_prefs` - | `mongoc_transaction_opts_get_write_concern <{+api-libmongoc+}/mongoc_transaction_opts_get_write_concern.html>`__ + | :ref:`mongoc_transaction_opts_get_write_concern` - | `mongoc_transaction_opts_new <{+api-libmongoc+}/mongoc_transaction_opts_get_write_concern.html>`__ + | :ref:`mongoc_transaction_opts_new` - | `mongoc_transaction_opts_set_max_commit_time_ms <{+api-libmongoc+}/mongoc_transaction_opts_set_max_commit_time_ms.html>`__ + | :ref:`mongoc_transaction_opts_set_max_commit_time_ms` - | `mongoc_transaction_opts_set_read_concern <{+api-libmongoc+}/mongoc_transaction_opts_set_read_concern.html>`__ + | :ref:`mongoc_transaction_opts_set_read_concern` - | `mongoc_transaction_opts_set_read_prefs <{+api-libmongoc+}/mongoc_transaction_opts_set_read_prefs.html>`__ + | :ref:`mongoc_transaction_opts_set_read_prefs` - | `mongoc_transaction_opts_set_write_concern <{+api-libmongoc+}/mongoc_transaction_opts_set_write_concern.html>`__ + | :ref:`mongoc_transaction_opts_set_write_concern` diff --git a/source/libmongoc/includes/session-lifecycle.txt b/source/libmongoc/includes/session-lifecycle.txt index 3073c980..c360eee7 100644 --- a/source/libmongoc/includes/session-lifecycle.txt +++ b/source/libmongoc/includes/session-lifecycle.txt @@ -1,11 +1,11 @@ :orphan: -Start a session with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__, use the session for a sequence of operations and multi-document transactions, then free it with `mongoc_client_session_destroy <{+api-libmongoc+}/mongoc_client_session_destroy.html>`__. Any `mongoc_cursor_t <{+api-libmongoc+}/mongoc_cursor_t.html>`__ or `mongoc_change_stream_t <{+api-libmongoc+}/mongoc_change_stream_t.html>`__ using a session must be destroyed before the session, and a session must be destroyed before the `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__ it came from. +Start a session with :ref:`mongoc_client_start_session`, use the session for a sequence of operations and multi-document transactions, then free it with :ref:`mongoc_client_session_destroy`. Any :ref:`mongoc_cursor_t` or :ref:`mongoc_change_stream_t` using a session must be destroyed before the session, and a session must be destroyed before the :ref:`mongoc_client_t` it came from. -By default, sessions are `causally consistent `_. To disable causal consistency, before starting a session create a `mongoc_session_opt_t <{+api-libmongoc+}/mongoc_session_opt_t.html>`__ with `mongoc_session_opts_new <{+api-libmongoc+}/mongoc_session_opts_new.html>`__ and call `mongoc_session_opts_set_causal_consistency <{+api-libmongoc+}/mongoc_session_opts_set_causal_consistency.html>`__, then free the struct with `mongoc_session_opts_destroy <{+api-libmongoc+}/mongoc_session_opts_destroy.html>`__. +By default, sessions are `causally consistent `_. To disable causal consistency, before starting a session create a :ref:`mongoc_session_opt_t` with :ref:`mongoc_session_opts_new` and call :ref:`mongoc_session_opts_set_causal_consistency`, then free the struct with :ref:`mongoc_session_opts_destroy`. Unacknowledged writes are prohibited with sessions. .. the timeout warning is mandated by the Driver Sessions Spec -A `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ must be used by only one thread at a time. Due to session pooling, `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__ may return a session that has been idle for some time and is about to be closed after its idle timeout. Use the session within one minute of acquiring it to refresh the session and avoid a timeout. +A :ref:`mongoc_client_session_t` must be used by only one thread at a time. Due to session pooling, :ref:`mongoc_client_start_session` may return a session that has been idle for some time and is about to be closed after its idle timeout. Use the session within one minute of acquiring it to refresh the session and avoid a timeout. diff --git a/source/libmongoc/includes/update-many-opts.txt b/source/libmongoc/includes/update-many-opts.txt index 2db9abae..bb61dd60 100644 --- a/source/libmongoc/includes/update-many-opts.txt +++ b/source/libmongoc/includes/update-many-opts.txt @@ -6,10 +6,10 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``hint``: A document or string that specifies the index to use to support the query predicate. diff --git a/source/libmongoc/includes/update-one-opts.txt b/source/libmongoc/includes/update-one-opts.txt index 2db9abae..bb61dd60 100644 --- a/source/libmongoc/includes/update-one-opts.txt +++ b/source/libmongoc/includes/update-one-opts.txt @@ -6,10 +6,10 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -* ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. -* ``validate``: Construct a bitwise-or of all desired `bson_validate_flags_t <{+api-libbson+}/bson_validate_with_error.html>`__. Set to ``false`` to skip client-side validation of the provided BSON documents. -* ``comment``: A `bson_value_t <{+api-libbson+}/bson_value_t.html>`__ 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. +* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. +* ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. +* ``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. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``hint``: A document or string that specifies the index to use to support the query predicate. diff --git a/source/libmongoc/includes/write-opts-sources.txt b/source/libmongoc/includes/write-opts-sources.txt index 1d0e2b31..a298b53e 100644 --- a/source/libmongoc/includes/write-opts-sources.txt +++ b/source/libmongoc/includes/write-opts-sources.txt @@ -22,5 +22,5 @@ concern is omitted for MongoDB before 3.4. * - ``database,`` ``collection``, or ``client`` - -`See the example for transactions <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__ and for -`the "distinct" command with opts <{+api-libmongoc+}/mongoc_client_read_command_with_opts.html>`__. +:ref:`See the example for transactions ` and for +:ref:`the "distinct" command with opts `. diff --git a/source/libmongoc/includes/write-opts.txt b/source/libmongoc/includes/write-opts.txt index c92ccefc..1cb34d14 100644 --- a/source/libmongoc/includes/write-opts.txt +++ b/source/libmongoc/includes/write-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use `mongoc_write_concern_append <{+api-libmongoc+}/mongoc_write_concern_append.html>`__ to add the write concern to ``opts``. See the example code for `mongoc_client_write_command_with_opts <{+api-libmongoc+}/mongoc_client_write_command_with_opts.html>`__. -- ``sessionId``: First, construct a `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__ with `mongoc_client_start_session <{+api-libmongoc+}/mongoc_client_start_session.html>`__. You can begin a transaction with `mongoc_client_session_start_transaction <{+api-libmongoc+}/mongoc_client_session_start_transaction.html>`__, optionally with a `mongoc_transaction_opt_t <{+api-libmongoc+}/mongoc_transaction_opt_t.html>`__ that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use `mongoc_client_session_append <{+api-libmongoc+}/mongoc_client_session_append.html>`__ to add the session to ``opts``. See the example code for `mongoc_client_session_t <{+api-libmongoc+}/mongoc_client_session_t.html>`__. +- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +- ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. - ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. -- ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling `mongoc_client_select_server <{+api-libmongoc+}/mongoc_client_select_server.html>`__, then `mongoc_server_description_id <{+api-libmongoc+}/mongoc_server_description_id.html>`__ on its return value. +- ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/tutorial.txt b/source/libmongoc/tutorial.txt index e0f815b6..657cf47b 100644 --- a/source/libmongoc/tutorial.txt +++ b/source/libmongoc/tutorial.txt @@ -12,7 +12,7 @@ Tutorial This guide offers a brief introduction to the MongoDB C Driver. -For more information on the C API, please refer to the `api <{+api-libmongoc+}/api.html>`__. +For more information on the C API, please refer to the :ref:`api`. Installing @@ -114,13 +114,13 @@ See the :ref:`libmongoc and Visual Studio guide `. Making a Connection ------------------- -Access MongoDB with a `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__. It transparently connects to standalone servers, replica sets -and sharded clusters on demand. To perform operations on a database or collection, create a `mongoc_database_t <{+api-libmongoc+}/mongoc_database_t.html>`__ -or `mongoc_collection_t <{+api-libmongoc+}/mongoc_collection_t.html>`__ struct from the `mongoc_client_t <{+api-libmongoc+}/mongoc_client_t.html>`__. +Access MongoDB with a :ref:`mongoc_client_t`. It transparently connects to standalone servers, replica sets +and sharded clusters on demand. To perform operations on a database or collection, create a :ref:`mongoc_database_t` +or `mongoc_collection_t <{+api-libmongoc+}/mongoc_collection_t.html>`__ struct from the :ref:`mongoc_client_t`. -At the start of an application, call `mongoc_init <{+api-libmongoc+}/mongoc_init.html>`__ before any other libmongoc functions. At the end, call +At the start of an application, call :ref:`mongoc_init` before any other libmongoc functions. At the end, call the appropriate destroy function for each collection, database, or client handle, in reverse order from how they -were constructed. Call `mongoc_cleanup <{+api-libmongoc+}/mongoc_cleanup.html>`__ before exiting. +were constructed. Call :ref:`mongoc_cleanup` before exiting. The example below establishes a connection to a standalone server on ``localhost``, registers the client application as "connect-example," and performs a simple command. @@ -144,7 +144,7 @@ documents. There are several ways to construct them: appending key-value pairs, Appending BSON ~~~~~~~~~~~~~~ -A BSON document, represented as a `bson_t <{+api-libbson+}/bson_t.html>`__ in code, can be constructed one field at a time using +A BSON document, represented as a :ref:`bson_t ` in code, can be constructed one field at a time using libbson's append functions. For example, to create a document like this: @@ -167,7 +167,7 @@ Use the following code: .. literalinclude:: /libmongoc/includes/examples/tutorial/appending.c :language: c -See the :ref:`libbson documentation ` for all of the types that can be appended to a `bson_t <{+api-libbson+}/bson_t.html>`__. +See the :ref:`libbson documentation ` for all of the types that can be appended to a `bson_t <{+api-libbson+}/bson_t.html>`__. Using BCON ~~~~~~~~~~ @@ -232,7 +232,7 @@ Notice that BCON can create arrays, subdocuments and arbitrary fields. Creating BSON from JSON ~~~~~~~~~~~~~~~~~~~~~~~ -For *single* documents, BSON can be created from JSON strings via `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__. +For *single* documents, BSON can be created from JSON strings via :ref:`bson_new_from_json `. .. code-block:: c @@ -261,7 +261,7 @@ For *single* documents, BSON can be created from JSON strings via `bson_new_from return 0; } -To initialize BSON from a sequence of JSON documents, use `bson_json_reader_t <{+api-libbson+}/bson_json_reader_t.html>`__. +To initialize BSON from a sequence of JSON documents, use :ref:`bson_json_reader_t `. .. _tutorial_crud_operations: @@ -274,7 +274,7 @@ Inserting a Document ~~~~~~~~~~~~~~~~~~~~ To insert documents into a collection, first obtain a handle to a ``mongoc_collection_t`` via a -``mongoc_client_t``. Then, use `mongoc_collection_insert_one <{+api-libmongoc+}/mongoc_collection_insert_one.html>`__ to add BSON documents to the collection. +``mongoc_client_t``. Then, use :ref:`mongoc_collection_insert_one` to add BSON documents to the collection. This example inserts into the database "mydb" and collection "mycoll". When finished, ensure that allocated structures are freed by using their respective destroy functions. @@ -350,8 +350,8 @@ To verify that the insert succeeded, connect with the MongoDB shell. Finding a Document ~~~~~~~~~~~~~~~~~~ -To query a MongoDB collection with the C driver, use the function `mongoc_collection_find_with_opts <{+api-libmongoc+}/mongoc_collection_find_with_opts.html>`__. -This returns a `cursor <{+api-libmongoc+}/mongoc_cursor_t.html>`__ to the matching documents. +To query a MongoDB collection with the C driver, use the function :ref:`mongoc_collection_find_with_opts() +`. This returns a :ref:`cursor ` to the matching documents. The following examples iterate through the result cursors and print the matches to ``stdout`` as JSON strings. Use a document as a query specifier; for example, @@ -478,7 +478,7 @@ to look for all documents matching ``{"hello" : "world"}``. Updating a Document ~~~~~~~~~~~~~~~~~~~ -This code snippet gives an example of using `mongoc_collection_update_one <{+api-libmongoc+}/mongoc_collection_update_one.html>`__ to +This code snippet gives an example of using :ref:`mongoc_collection_update_one() ` to update the fields of a document. Using the "mydb" database, the following example inserts an example document into the "mycoll" collection. Then, @@ -576,7 +576,7 @@ To verify that the update succeeded, connect with the MongoDB shell. Deleting a Document ~~~~~~~~~~~~~~~~~~~ -This example illustrates the use of `mongoc_collection_delete_one <{+api-libmongoc+}/mongoc_collection_delete_one.html>`__ to delete a document. +This example illustrates the use of :ref:`mongoc_collection_delete_one` to delete a document. The following code inserts a sample document into the database "mydb" and collection "mycoll". Then, it deletes all documents matching ``{"hello" : "world"}``. @@ -754,7 +754,7 @@ Threading The MongoDB C Driver is thread-unaware in the vast majority of its operations. This means it is up to the programmer to guarantee thread-safety. -However, `mongoc_client_pool_t <{+api-libmongoc+}/mongoc_client_pool_t.html>`__ is thread-safe and is used to fetch a ``mongoc_client_t`` in a thread-safe manner. +However, :ref:`mongoc_client_pool_t` is thread-safe and is used to fetch a ``mongoc_client_t`` in a thread-safe manner. After retrieving a client from the pool, the client structure should be considered owned by the calling thread. When the thread is finished, the client should be placed back into the pool. From 3d7460fcbf2f7ba587bcdd2ef5d8f3e71f856daa Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:03:58 -0700 Subject: [PATCH 4/8] Revert "snooty fix" This reverts commit daca1f7c7276a250ec6bc965396914165a343573. --- snooty.toml | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/snooty.toml b/snooty.toml index ed6a2a4b..7c1aed4e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -13,6 +13,37 @@ toc_landing_pages = [ "/libbson/cross-platform-notes", "/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", @@ -29,5 +60,4 @@ is-experimental = "is part of the experimental Queryable Encryption API and may 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 +api-libbson = "https://mongoc.org/libbson/current" \ No newline at end of file From 3f6b73145e1a4856cfb708fc29139db472cba323 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:04:06 -0700 Subject: [PATCH 5/8] Revert "some ref updates" This reverts commit 3cf72738a61f21bc992e5abdec330be217147af9. --- snooty.toml | 18 +++++- .../cross-platform-notes/threading.txt | 6 +- source/libbson/guides/json.txt | 17 +++--- source/libbson/guides/lifetimes.txt | 24 ++++---- source/libbson/guides/streaming-bson.txt | 24 ++++---- .../libbson/includes/seealso/bson-as-json.rst | 14 ++--- .../libbson/includes/seealso/create-bson.rst | 22 ++++---- source/libbson/includes/seealso/iter-init.rst | 8 +-- source/libbson/includes/seealso/json.rst | 6 +- source/libbson/tutorials/creating.txt | 10 ++-- source/libbson/tutorials/errors.txt | 6 +- source/libbson/tutorials/oid.txt | 19 +++---- source/libbson/tutorials/parsing.txt | 26 ++++----- source/libbson/tutorials/utf8.txt | 2 +- .../mongoc_apm_callbacks_destroy.txt | 20 +++++++ .../mongoc_apm_callbacks_new.txt | 25 +++++++++ .../mongoc_apm_callbacks_t.txt | 56 +++++++++++++++++++ ...oc_apm_command_failed_get_command_name.txt | 32 +++++++++++ .../mongoc_apm_command_failed_get_context.txt | 31 ++++++++++ ...mongoc_apm_command_failed_get_duration.txt | 31 ++++++++++ .../mongoc_apm_command_failed_get_error.txt | 27 +++++++++ .../mongoc_apm_command_failed_get_host.txt | 32 +++++++++++ ...oc_apm_command_failed_get_operation_id.txt | 32 +++++++++++ .../mongoc_apm_command_failed_get_reply.txt | 34 +++++++++++ ...ngoc_apm_command_failed_get_request_id.txt | 32 +++++++++++ ...ommand_failed_get_server_connection_id.txt | 44 +++++++++++++++ ..._failed_get_server_connection_id_int64.txt | 36 ++++++++++++ ...ongoc_apm_command_failed_get_server_id.txt | 31 ++++++++++ ...ngoc_apm_command_failed_get_service_id.txt | 27 +++++++++ .../mongoc_apm_command_failed_t.txt | 50 +++++++++++++++++ ...mongoc_apm_command_started_get_command.txt | 32 +++++++++++ ...c_apm_command_started_get_command_name.txt | 32 +++++++++++ ...mongoc_apm_command_started_get_context.txt | 31 ++++++++++ ..._apm_command_started_get_database_name.txt | 32 +++++++++++ .../mongoc_apm_command_started_get_host.txt | 32 +++++++++++ ...c_apm_command_started_get_operation_id.txt | 32 +++++++++++ ...goc_apm_command_started_get_request_id.txt | 32 +++++++++++ ...mmand_started_get_server_connection_id.txt | 42 ++++++++++++++ ...started_get_server_connection_id_int64.txt | 34 +++++++++++ ...ngoc_apm_command_started_get_server_id.txt | 31 ++++++++++ ...goc_apm_command_started_get_service_id.txt | 27 +++++++++ .../mongoc_apm_command_started_t.txt | 47 ++++++++++++++++ ...apm_command_succeeded_get_command_name.txt | 32 +++++++++++ ...ngoc_apm_command_succeeded_get_context.txt | 31 ++++++++++ ...goc_apm_command_succeeded_get_duration.txt | 31 ++++++++++ .../mongoc_apm_command_succeeded_get_host.txt | 33 +++++++++++ ...apm_command_succeeded_get_operation_id.txt | 32 +++++++++++ ...mongoc_apm_command_succeeded_get_reply.txt | 32 +++++++++++ ...c_apm_command_succeeded_get_request_id.txt | 32 +++++++++++ ...and_succeeded_get_server_connection_id.txt | 42 ++++++++++++++ ...cceeded_get_server_connection_id_int64.txt | 34 +++++++++++ ...oc_apm_command_succeeded_get_server_id.txt | 31 ++++++++++ ...c_apm_command_succeeded_get_service_id.txt | 27 +++++++++ .../mongoc_apm_command_succeeded_t.txt | 47 ++++++++++++++++ .../mongoc_apm_server_changed_get_context.txt | 31 ++++++++++ .../mongoc_apm_server_changed_get_host.txt | 32 +++++++++++ ...apm_server_changed_get_new_description.txt | 32 +++++++++++ ...erver_changed_get_previous_description.txt | 32 +++++++++++ ...goc_apm_server_changed_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_server_changed_t.txt | 36 ++++++++++++ .../mongoc_apm_server_closed_get_context.txt | 30 ++++++++++ .../mongoc_apm_server_closed_get_host.txt | 32 +++++++++++ ...ngoc_apm_server_closed_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_server_closed_t.txt | 32 +++++++++++ ...pm_server_heartbeat_failed_get_awaited.txt | 31 ++++++++++ ...pm_server_heartbeat_failed_get_context.txt | 31 ++++++++++ ...m_server_heartbeat_failed_get_duration.txt | 31 ++++++++++ ..._apm_server_heartbeat_failed_get_error.txt | 27 +++++++++ ...c_apm_server_heartbeat_failed_get_host.txt | 33 +++++++++++ .../mongoc_apm_server_heartbeat_failed_t.txt | 36 ++++++++++++ ...m_server_heartbeat_started_get_awaited.txt | 31 ++++++++++ ...m_server_heartbeat_started_get_context.txt | 31 ++++++++++ ..._apm_server_heartbeat_started_get_host.txt | 33 +++++++++++ .../mongoc_apm_server_heartbeat_started_t.txt | 32 +++++++++++ ...server_heartbeat_succeeded_get_awaited.txt | 31 ++++++++++ ...server_heartbeat_succeeded_get_context.txt | 31 ++++++++++ ...erver_heartbeat_succeeded_get_duration.txt | 31 ++++++++++ ...pm_server_heartbeat_succeeded_get_host.txt | 33 +++++++++++ ...m_server_heartbeat_succeeded_get_reply.txt | 32 +++++++++++ ...ongoc_apm_server_heartbeat_succeeded_t.txt | 36 ++++++++++++ .../mongoc_apm_server_opening_get_context.txt | 31 ++++++++++ .../mongoc_apm_server_opening_get_host.txt | 32 +++++++++++ ...goc_apm_server_opening_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_server_opening_t.txt | 32 +++++++++++ .../mongoc_apm_set_command_failed_cb.txt | 31 ++++++++++ .../mongoc_apm_set_command_started_cb.txt | 31 ++++++++++ .../mongoc_apm_set_command_succeeded_cb.txt | 31 ++++++++++ .../mongoc_apm_set_server_changed_cb.txt | 31 ++++++++++ .../mongoc_apm_set_server_closed_cb.txt | 32 +++++++++++ ...goc_apm_set_server_heartbeat_failed_cb.txt | 32 +++++++++++ ...oc_apm_set_server_heartbeat_started_cb.txt | 32 +++++++++++ ..._apm_set_server_heartbeat_succeeded_cb.txt | 32 +++++++++++ .../mongoc_apm_set_server_opening_cb.txt | 32 +++++++++++ .../mongoc_apm_set_topology_changed_cb.txt | 33 +++++++++++ .../mongoc_apm_set_topology_closed_cb.txt | 32 +++++++++++ .../mongoc_apm_set_topology_opening_cb.txt | 30 ++++++++++ ...ongoc_apm_topology_changed_get_context.txt | 31 ++++++++++ ...m_topology_changed_get_new_description.txt | 32 +++++++++++ ...ology_changed_get_previous_description.txt | 32 +++++++++++ ...c_apm_topology_changed_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_topology_changed_t.txt | 34 +++++++++++ ...mongoc_apm_topology_closed_get_context.txt | 31 ++++++++++ ...oc_apm_topology_closed_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_topology_closed_t.txt | 30 ++++++++++ ...ongoc_apm_topology_opening_get_context.txt | 31 ++++++++++ ...c_apm_topology_opening_get_topology_id.txt | 32 +++++++++++ .../mongoc_apm_topology_opening_t.txt | 29 ++++++++++ .../libmongoc/guides/advanced-connections.txt | 2 +- source/libmongoc/guides/bulk.txt | 19 +++---- .../libmongoc/guides/connection-pooling.txt | 6 +- source/libmongoc/includes/aggregate-opts.txt | 2 +- source/libmongoc/includes/bulk-opts.txt | 2 +- .../libmongoc/includes/create-index-opts.txt | 2 +- .../libmongoc/includes/delete-many-opts.txt | 2 +- source/libmongoc/includes/delete-one-opts.txt | 2 +- .../find-and-modify-appended-opts.txt | 2 +- .../libmongoc/includes/gridfs-bucket-opts.txt | 2 +- .../includes/gridfs-bucket-upload-opts.txt | 2 +- .../libmongoc/includes/insert-many-opts.txt | 2 +- source/libmongoc/includes/insert-one-opts.txt | 2 +- source/libmongoc/includes/read-write-opts.txt | 2 +- .../libmongoc/includes/replace-one-opts.txt | 2 +- .../includes/retryable-read-aggregate.txt | 2 +- source/libmongoc/includes/retryable-read.txt | 2 +- source/libmongoc/includes/returns-cursor.txt | 2 +- .../libmongoc/includes/update-many-opts.txt | 2 +- source/libmongoc/includes/update-one-opts.txt | 2 +- source/libmongoc/includes/write-opts.txt | 2 +- source/libmongoc/tutorial.txt | 4 +- 129 files changed, 3167 insertions(+), 133 deletions(-) create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_destroy.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_new.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_command_name.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_duration.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_error.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_operation_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_reply.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_request_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id_int64.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_service_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command_name.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_database_name.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_operation_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_request_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id_int64.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_service_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_command_name.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_duration.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_operation_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_reply.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_request_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id_int64.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_service_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_new_description.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_previous_description.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_awaited.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_duration.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_error.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_awaited.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_awaited.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_duration.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_reply.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_host.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_failed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_started_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_succeeded_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_changed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_closed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_failed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_started_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_succeeded_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_opening_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_changed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_closed_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_opening_cb.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_new_description.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_previous_description.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_t.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_context.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_topology_id.txt create mode 100644 source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_t.txt diff --git a/snooty.toml b/snooty.toml index 7c1aed4e..256093af 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,6 +11,21 @@ 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", @@ -59,5 +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" \ No newline at end of file +opt-is-experimental = "This option {+is-experimental+}" \ No newline at end of file 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 7107874b..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 @@ -66,9 +66,9 @@ Converting JSON to BSON ----------------------- Converting back from JSON is also useful and common enough that we added :ref:`bson_init_from_json` -and `bson_new_from_json <{+api-libbson+}/bson_new_from_json.html>`__. +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/application-performance-monitoring/mongoc_apm_callbacks_destroy.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_destroy.txt new file mode 100644 index 00000000..e3d34e24 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_destroy.txt @@ -0,0 +1,20 @@ +.. _mongoc_apm_callbacks_destroy: + +============================== +mongoc_apm_callbacks_destroy() +============================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_callbacks_destroy (mongoc_apm_callbacks_t *callbacks); + +Free a :ref:`mongoc_apm_callbacks_t`. Does nothing if ``callbacks`` is NULL. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_new.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_new.txt new file mode 100644 index 00000000..b1754396 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_new.txt @@ -0,0 +1,25 @@ +.. _mongoc_apm_callbacks_new: + +========================== +mongoc_apm_callbacks_new() +========================== + +Synopsis +-------- + +.. code-block:: c + + mongoc_apm_callbacks_t * + mongoc_apm_callbacks_new (void) BSON_GNUC_WARN_UNUSED_RESULT; + +Create a struct to hold event-notification callbacks. + +Returns +------- + +A new ``mongoc_apm_callbacks_t`` you must free with :ref:`mongoc_apm_callbacks_destroy`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_t.txt new file mode 100644 index 00000000..c4b787f2 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_callbacks_t.txt @@ -0,0 +1,56 @@ +.. _mongoc_apm_callbacks_t: + +====================== +mongoc_apm_callbacks_t +====================== + +Notification callbacks + +Synopsis +-------- + +Used to receive notification of events, such as when a MongoDB command begins, succeeds, or fails. + +Create a ``mongoc_apm_callbacks_t`` with :ref:`mongoc_apm_callbacks_new`, set callbacks on it, then +pass it to :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_callbacks_destroy + /libmongoc/application-performance-monitoring/mongoc_apm_callbacks_new + /libmongoc/application-performance-monitoring/mongoc_apm_set_command_failed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_command_started_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_command_succeeded_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_changed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_closed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_failed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_started_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_succeeded_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_server_opening_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_topology_changed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_topology_closed_cb + /libmongoc/application-performance-monitoring/mongoc_apm_set_topology_opening_cb + +- :ref:`mongoc_apm_callbacks_destroy` +- :ref:`mongoc_apm_callbacks_new` +- :ref:`mongoc_apm_set_command_failed_cb` +- :ref:`mongoc_apm_set_command_started_cb` +- :ref:`mongoc_apm_set_command_succeeded_cb` +- :ref:`mongoc_apm_set_server_changed_cb` +- :ref:`mongoc_apm_set_server_closed_cb` +- :ref:`mongoc_apm_set_server_heartbeat_failed_cb` +- :ref:`mongoc_apm_set_server_heartbeat_started_cb` +- :ref:`mongoc_apm_set_server_heartbeat_succeeded_cb` +- :ref:`mongoc_apm_set_server_opening_cb` +- :ref:`mongoc_apm_set_topology_changed_cb` +- :ref:`mongoc_apm_set_topology_closed_cb` +- :ref:`mongoc_apm_set_topology_opening_cb` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_command_name.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_command_name.txt new file mode 100644 index 00000000..d0c1af44 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_command_name.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_failed_get_command_name: + +============================================ +mongoc_apm_command_failed_get_command_name() +============================================ + +Synopsis +-------- + +.. code-block:: c + + const char * + mongoc_apm_command_failed_get_command_name ( + const mongoc_apm_command_failed_t *event); + +Returns this event's command name. The data is only valid in the scope of the callback that receives +this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +A string that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_context.txt new file mode 100644 index 00000000..a8c7c872 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_failed_get_context: + +======================================= +mongoc_apm_command_failed_get_context() +======================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_command_failed_get_context ( + const mongoc_apm_command_failed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_duration.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_duration.txt new file mode 100644 index 00000000..950db931 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_duration.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_failed_get_duration: + +======================================== +mongoc_apm_command_failed_get_duration() +======================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_failed_get_duration ( + const mongoc_apm_command_failed_t *event); + +Returns this event's duration in microseconds. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The event's duration. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_error.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_error.txt new file mode 100644 index 00000000..d12f2185 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_error.txt @@ -0,0 +1,27 @@ +.. _mongoc_apm_command_failed_get_error: + +===================================== +mongoc_apm_command_failed_get_error() +===================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_command_failed_get_error (const mongoc_apm_command_failed_t *event, + bson_error_t *error); + +Copies this event's error info. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. +- ``error``: A :ref:`bson_error_t` to receive the event's error info. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_host.txt new file mode 100644 index 00000000..4a5ac194 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_host.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_failed_get_host: + +==================================== +mongoc_apm_command_failed_get_host() +==================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_command_failed_get_host (const mongoc_apm_command_failed_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, it is +solely the server for this event. The data is only valid in the scope of the callback that receives +this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_operation_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_operation_id.txt new file mode 100644 index 00000000..77be5f17 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_operation_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_failed_get_operation_id: + +============================================ +mongoc_apm_command_failed_get_operation_id() +============================================ + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_failed_get_operation_id ( + const mongoc_apm_command_failed_t *event); + +Returns this event's operation id. This number correlates all the commands in a bulk operation, +or all the "find" and "getMore" commands required to stream a large query result. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The event's operation id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_reply.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_reply.txt new file mode 100644 index 00000000..8103bac4 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_reply.txt @@ -0,0 +1,34 @@ +.. _mongoc_apm_command_failed_get_reply: + +===================================== +mongoc_apm_command_failed_get_reply() +===================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_apm_command_failed_get_reply ( + const mongoc_apm_command_failed_t *event); + +Returns the server's reply to a command that failed. The reply contains details about why +the command failed. If no server reply was received, such as in the event of a network error, +then the reply is a valid empty BSON document. The data is only valid in the scope of the +callback that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_request_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_request_id.txt new file mode 100644 index 00000000..704590e3 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_request_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_failed_get_request_id: + +========================================== +mongoc_apm_command_failed_get_request_id() +========================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_failed_get_request_id ( + const mongoc_apm_command_failed_t *event); + +Returns this event's wire-protocol request id. Use this number to correlate client-side +events with server log messages. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The event's request id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id.txt new file mode 100644 index 00000000..39bb63a8 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id.txt @@ -0,0 +1,44 @@ +.. _mongoc_apm_command_failed_get_server_connection_id: + +==================================================== +mongoc_apm_command_failed_get_server_connection_id() +==================================================== + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_apm_command_failed_get_server_connection_id_int64` in new code. + +Synopsis +-------- + +.. code-block:: c + + int32_t + mongoc_apm_command_failed_get_server_connection_id ( + const mongoc_apm_command_failed_t *event) + BSON_GNUC_DEPRECATED_FOR ( + "mongoc_apm_command_failed_get_server_connection_id_int64"); + +Returns this event's context. + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID (:ref:`mongoc_apm_command_failed_get_server_id`) +and is returned by the hello or legacy hello response as "connectionId" from the +server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id_int64.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id_int64.txt new file mode 100644 index 00000000..03a219ca --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id_int64.txt @@ -0,0 +1,36 @@ +.. _mongoc_apm_command_failed_get_server_connection_id_int64: + +========================================================== +mongoc_apm_command_failed_get_server_connection_id_int64() +========================================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_failed_get_server_connection_id_int64 ( + const mongoc_apm_command_failed_t *event); + +Returns this event's context. + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID (:ref:`mongoc_apm_command_failed_get_server_id`) +and is returned by the hello or legacy hello response as "connectionId" from the +server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_id.txt new file mode 100644 index 00000000..0c3b45a6 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_id.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_failed_get_server_id: + +========================================= +mongoc_apm_command_failed_get_server_id() +========================================= + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_apm_command_failed_get_server_id ( + const mongoc_apm_command_failed_t *event); + +Returns this event's server id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +The event's server id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_service_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_service_id.txt new file mode 100644 index 00000000..ff781f07 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_service_id.txt @@ -0,0 +1,27 @@ +.. _mongoc_apm_command_failed_get_service_id: + +========================================== +mongoc_apm_command_failed_get_service_id() +========================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_oid_t * + mongoc_apm_command_failed_get_service_id ( + const mongoc_apm_command_failed_t *event); + +Returns this event's service ID, which identifies the MongoDB service behind a +load balancer, or ``NULL`` if not connected to a load balanced cluster. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_failed_t`. + +Returns +------- + +A :ref:`bson_oid_t` that should not be modified or freed or ``NULL``. diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_t.txt new file mode 100644 index 00000000..fc83fbaa --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_failed_t.txt @@ -0,0 +1,50 @@ +.. _mongoc_apm_command_failed_t: + +=========================== +mongoc_apm_command_failed_t +=========================== + +Command-failed event + +Synopsis +-------- + +An event notification sent when the driver fails to execute a MongoDB command. + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_command_name + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_duration + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_error + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_operation_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_reply + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_request_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_service_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_failed_get_server_connection_id_int64 + +- :ref:`mongoc_apm_command_failed_get_command_name` +- :ref:`mongoc_apm_command_failed_get_context` +- :ref:`mongoc_apm_command_failed_get_duration` +- :ref:`mongoc_apm_command_failed_get_error` +- :ref:`mongoc_apm_command_failed_get_host` +- :ref:`mongoc_apm_command_failed_get_operation_id` +- :ref:`mongoc_apm_command_failed_get_reply` +- :ref:`mongoc_apm_command_failed_get_request_id` +- :ref:`mongoc_apm_command_failed_get_server_id` +- :ref:`mongoc_apm_command_failed_get_service_id` +- :ref:`mongoc_apm_command_failed_get_server_connection_id` +- :ref:`mongoc_apm_command_failed_get_server_connection_id_int64` + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command.txt new file mode 100644 index 00000000..5d678b01 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_command: + +======================================== +mongoc_apm_command_started_get_command() +======================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_apm_command_started_get_command ( + const mongoc_apm_command_started_t *event); + +Returns this event's command. The data is only valid in the scope of the callback that receives +this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command_name.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command_name.txt new file mode 100644 index 00000000..a76c64f7 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command_name.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_command_name: + +============================================= +mongoc_apm_command_started_get_command_name() +============================================= + +Synopsis +-------- + +.. code-block:: c + + const char * + mongoc_apm_command_started_get_command_name ( + const mongoc_apm_command_started_t *event); + +Returns this event's command name. The data is only valid in the scope of the callback that +receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +A string that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_context.txt new file mode 100644 index 00000000..595ca947 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_started_get_context: + +======================================== +mongoc_apm_command_started_get_context() +======================================== + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_command_started_get_context ( + const mongoc_apm_command_started_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_database_name.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_database_name.txt new file mode 100644 index 00000000..f7471195 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_database_name.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_database_name: + +============================================== +mongoc_apm_command_started_get_database_name() +============================================== + +Synopsis +-------- + +.. code-block:: c + + const char * + mongoc_apm_command_started_get_database_name ( + const mongoc_apm_command_started_t *event); + +Returns this event's database name. The data is only valid in the scope of the callback that receives +this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +A string that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_host.txt new file mode 100644 index 00000000..7eb1d7c1 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_host.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_host: + +===================================== +mongoc_apm_command_started_get_host() +===================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_command_started_get_host (const mongoc_apm_command_started_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, it +is solely the server for this event. The data is only valid in the scope of the callback that +receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_operation_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_operation_id.txt new file mode 100644 index 00000000..203e0ac6 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_operation_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_operation_id: + +============================================= +mongoc_apm_command_started_get_operation_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_started_get_operation_id ( + const mongoc_apm_command_started_t *event); + +Returns this event's operation id. This number correlates all the commands in a bulk operation, +or all the "find" and "getMore" commands required to stream a large query result. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The event's operation id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_request_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_request_id.txt new file mode 100644 index 00000000..4fc3b094 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_request_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_started_get_request_id: + +=========================================== +mongoc_apm_command_started_get_request_id() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_started_get_request_id ( + const mongoc_apm_command_started_t *event); + +Returns this event's wire-protocol request id. Use this number to correlate client-side events +with server log messages. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The event's request id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id.txt new file mode 100644 index 00000000..6221d0b6 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id.txt @@ -0,0 +1,42 @@ +.. _mongoc_apm_command_started_get_server_connection_id: + +===================================================== +mongoc_apm_command_started_get_server_connection_id() +===================================================== + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_apm_command_started_get_server_connection_id_int64` in new code. + +Synopsis +-------- + +.. code-block:: c + + int32_t + mongoc_apm_command_started_get_server_connection_id ( + const mongoc_apm_command_started_t *event) + BSON_GNUC_DEPRECATED_FOR ( + "mongoc_apm_command_started_get_server_connection_id_int64"); + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID (:ref:`mongoc_apm_command_started_get_server_id`) +and is returned by the hello or legacy hello response as "connectionId" from the +server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id_int64.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id_int64.txt new file mode 100644 index 00000000..beba630f --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id_int64.txt @@ -0,0 +1,34 @@ +.. _mongoc_apm_command_started_get_server_connection_id_int64: + +=========================================================== +mongoc_apm_command_started_get_server_connection_id_int64() +=========================================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_started_get_server_connection_id_int64 ( + const mongoc_apm_command_started_t *event); + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID (:ref:`mongoc_apm_command_started_get_server_id`) +and is returned by the hello or legacy hello response as "connectionId" from the +server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_id.txt new file mode 100644 index 00000000..9ab56b20 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_id.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_started_get_server_id: + +========================================== +mongoc_apm_command_started_get_server_id() +========================================== + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_apm_command_started_get_server_id ( + const mongoc_apm_command_started_t *event); + +Returns this event's server id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +The event's server id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_service_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_service_id.txt new file mode 100644 index 00000000..26ff3630 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_service_id.txt @@ -0,0 +1,27 @@ +.. _mongoc_apm_command_started_get_service_id: + +=========================================== +mongoc_apm_command_started_get_service_id() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_oid_t * + mongoc_apm_command_started_get_service_id ( + const mongoc_apm_command_started_t *event); + +Returns this event's service ID, which identifies the MongoDB service behind a +load balancer, or ``NULL`` if not connected to a load balanced cluster. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_started_t`. + +Returns +------- + +A :ref:`bson_oid_t` that should not be modified or freed or ``NULL``. diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_t.txt new file mode 100644 index 00000000..8e94e94c --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_started_t.txt @@ -0,0 +1,47 @@ +.. _mongoc_apm_command_started_t: + +============================ +mongoc_apm_command_started_t +============================ + +Command-started event + +Synopsis +-------- + +An event notification sent when the driver begins executing a MongoDB command. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_command_name + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_database_name + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_operation_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_request_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_service_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_started_get_server_connection_id_int64 + +- :ref:`mongoc_apm_command_started_get_command` +- :ref:`mongoc_apm_command_started_get_command_name` +- :ref:`mongoc_apm_command_started_get_context` +- :ref:`mongoc_apm_command_started_get_database_name` +- :ref:`mongoc_apm_command_started_get_host` +- :ref:`mongoc_apm_command_started_get_operation_id` +- :ref:`mongoc_apm_command_started_get_request_id` +- :ref:`mongoc_apm_command_started_get_server_id` +- :ref:`mongoc_apm_command_started_get_service_id` +- :ref:`mongoc_apm_command_started_get_server_connection_id` +- :ref:`mongoc_apm_command_started_get_server_connection_id_int64` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_command_name.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_command_name.txt new file mode 100644 index 00000000..a0a8a667 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_command_name.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_succeeded_get_command_name: + +=============================================== +mongoc_apm_command_succeeded_get_command_name() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + const char * + mongoc_apm_command_succeeded_get_command_name ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's command name. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +A string that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_context.txt new file mode 100644 index 00000000..7895e0c2 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_succeeded_get_context: + +========================================== +mongoc_apm_command_succeeded_get_context() +========================================== + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_command_succeeded_get_context ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_duration.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_duration.txt new file mode 100644 index 00000000..d46d2ddd --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_duration.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_succeeded_get_duration: + +=========================================== +mongoc_apm_command_succeeded_get_duration() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_succeeded_get_duration ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's duration in microseconds. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The event's duration. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_host.txt new file mode 100644 index 00000000..dc4afc7b --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_host.txt @@ -0,0 +1,33 @@ +.. _mongoc_apm_command_succeeded_get_host: + +======================================= +mongoc_apm_command_succeeded_get_host() +======================================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_command_succeeded_get_host ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_operation_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_operation_id.txt new file mode 100644 index 00000000..96fc4e80 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_operation_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_succeeded_get_operation_id: + +=============================================== +mongoc_apm_command_succeeded_get_operation_id() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_succeeded_get_operation_id ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's operation id. This number correlates all the commands in a bulk operation, +or all the "find" and "getMore" commands required to stream a large query result. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The event's operation id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_reply.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_reply.txt new file mode 100644 index 00000000..776504b5 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_reply.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_succeeded_get_reply: + +======================================== +mongoc_apm_command_succeeded_get_reply() +======================================== + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_apm_command_succeeded_get_reply ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's reply. The data is only valid in the scope of the callback that receives +this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_request_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_request_id.txt new file mode 100644 index 00000000..2811b365 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_request_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_command_succeeded_get_request_id: + +============================================= +mongoc_apm_command_succeeded_get_request_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_succeeded_get_request_id ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's wire-protocol request id. Use this number to correlate client-side +events with server log messages. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The event's request id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id.txt new file mode 100644 index 00000000..623fbfff --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id.txt @@ -0,0 +1,42 @@ +.. _mongoc_apm_command_succeeded_get_server_connection_id: + +======================================================= +mongoc_apm_command_succeeded_get_server_connection_id() +======================================================= + +.. warning:: + + This function is deprecated and should not be used in new code. + + Please use :ref:`mongoc_apm_command_succeeded_get_server_connection_id_int64` in new code. + +Synopsis +-------- + +.. code-block:: c + + int32_t + mongoc_apm_command_succeeded_get_server_connection_id ( + const mongoc_apm_command_succeeded_t *event) + BSON_GNUC_DEPRECATED_FOR ( + "mongoc_apm_command_succeeded_get_server_connection_id_int64"); + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID +(:ref:`mongoc_apm_command_succeeded_get_server_id`) and is returned by the +hello or legacy hello response as "connectionId" from the server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id_int64.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id_int64.txt new file mode 100644 index 00000000..79767ee5 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id_int64.txt @@ -0,0 +1,34 @@ +.. _mongoc_apm_command_succeeded_get_server_connection_id_int64: + +============================================================= +mongoc_apm_command_succeeded_get_server_connection_id_int64() +============================================================= + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_command_succeeded_get_server_connection_id_int64 ( + const mongoc_apm_command_succeeded_t *event); + +Returns the server connection ID for the command. The server connection ID is +distinct from the server ID +(:ref:`mongoc_apm_command_succeeded_get_server_id`) and is returned by the +hello or legacy hello response as "connectionId" from the server on 4.2+. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The server connection ID as a positive integer or -1 if it is not available. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_id.txt new file mode 100644 index 00000000..50e0fe1a --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_id.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_command_succeeded_get_server_id: + +============================================ +mongoc_apm_command_succeeded_get_server_id() +============================================ + +Synopsis +-------- + +.. code-block:: c + + uint32_t + mongoc_apm_command_succeeded_get_server_id ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's server id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +The event's server id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_service_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_service_id.txt new file mode 100644 index 00000000..720dfea6 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_service_id.txt @@ -0,0 +1,27 @@ +.. _mongoc_apm_command_succeeded_get_service_id: + +============================================= +mongoc_apm_command_succeeded_get_service_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + const bson_oid_t * + mongoc_apm_command_succeeded_get_service_id ( + const mongoc_apm_command_succeeded_t *event); + +Returns this event's service ID, which identifies the MongoDB service behind a +load balancer, or ``NULL`` if not connected to a load balanced cluster. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_command_succeeded_t`. + +Returns +------- + +A :ref:`bson_oid_t` that should not be modified or freed or ``NULL``. diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_t.txt new file mode 100644 index 00000000..487d6509 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_t.txt @@ -0,0 +1,47 @@ +.. _mongoc_apm_command_succeeded_t: + +============================== +mongoc_apm_command_succeeded_t +============================== + +Command-succeeded event + +Synopsis +-------- + +An event notification sent when the driver successfully executes a MongoDB command. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_command_name + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_duration + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_operation_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_reply + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_request_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_service_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id + /libmongoc/application-performance-monitoring/mongoc_apm_command_succeeded_get_server_connection_id_int64 + +- :ref:`mongoc_apm_command_succeeded_get_command_name` +- :ref:`mongoc_apm_command_succeeded_get_context` +- :ref:`mongoc_apm_command_succeeded_get_duration` +- :ref:`mongoc_apm_command_succeeded_get_host` +- :ref:`mongoc_apm_command_succeeded_get_operation_id` +- :ref:`mongoc_apm_command_succeeded_get_reply` +- :ref:`mongoc_apm_command_succeeded_get_request_id` +- :ref:`mongoc_apm_command_succeeded_get_server_id` +- :ref:`mongoc_apm_command_succeeded_get_service_id` +- :ref:`mongoc_apm_command_succeeded_get_server_connection_id` +- :ref:`mongoc_apm_command_succeeded_get_server_connection_id_int64` diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_context.txt new file mode 100644 index 00000000..535bf8c2 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_changed_get_context: + +======================================= +mongoc_apm_server_changed_get_context() +======================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_changed_get_context ( + const mongoc_apm_server_changed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_changed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_host.txt new file mode 100644 index 00000000..77d37081 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_host.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_changed_get_host: + +==================================== +mongoc_apm_server_changed_get_host() +==================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_changed_get_host (const mongoc_apm_server_changed_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_changed_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_new_description.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_new_description.txt new file mode 100644 index 00000000..f528290d --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_new_description.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_changed_get_new_description: + +=============================================== +mongoc_apm_server_changed_get_new_description() +=============================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_server_description_t * + mongoc_apm_server_changed_get_new_description ( + const mongoc_apm_server_changed_t *event); + +Returns this event's new description. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_changed_t`. + +Returns +------- + +A :ref:`mongoc_server_description_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_previous_description.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_previous_description.txt new file mode 100644 index 00000000..c0ea56ec --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_previous_description.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_changed_get_previous_description: + +==================================================== +mongoc_apm_server_changed_get_previous_description() +==================================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_server_description_t * + mongoc_apm_server_changed_get_previous_description ( + const mongoc_apm_server_changed_t *event); + +Returns this event's previous description. The data is only valid in the scope of the +callback that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_changed_t`. + +Returns +------- + +A :ref:`mongoc_server_description_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_topology_id.txt new file mode 100644 index 00000000..c830ad7f --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_changed_get_topology_id: + +=========================================== +mongoc_apm_server_changed_get_topology_id() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_server_changed_get_topology_id ( + const mongoc_apm_server_changed_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_changed_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_t.txt new file mode 100644 index 00000000..c5a8524e --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_changed_t.txt @@ -0,0 +1,36 @@ +.. _mongoc_apm_server_changed_t: + +=========================== +mongoc_apm_server_changed_t +=========================== + +Server-changed event + +Synopsis +-------- + +An event notification sent when the driver observes a change in status of a server it is +connected to. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_new_description + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_previous_description + /libmongoc/application-performance-monitoring/mongoc_apm_server_changed_get_topology_id + +- :ref:`mongoc_apm_server_changed_get_context` +- :ref:`mongoc_apm_server_changed_get_host` +- :ref:`mongoc_apm_server_changed_get_new_description` +- :ref:`mongoc_apm_server_changed_get_previous_description` +- :ref:`mongoc_apm_server_changed_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_context.txt new file mode 100644 index 00000000..1b22d25a --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_context.txt @@ -0,0 +1,30 @@ +.. _mongoc_apm_server_closed_get_context: + +====================================== +mongoc_apm_server_closed_get_context() +====================================== + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_closed_get_context (const mongoc_apm_server_closed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_closed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_host.txt new file mode 100644 index 00000000..fb014b68 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_host.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_closed_get_host: + +=================================== +mongoc_apm_server_closed_get_host() +=================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_closed_get_host (const mongoc_apm_server_closed_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_closed_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_topology_id.txt new file mode 100644 index 00000000..c5c90c00 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_closed_get_topology_id: + +========================================== +mongoc_apm_server_closed_get_topology_id() +========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_server_closed_get_topology_id ( + const mongoc_apm_server_closed_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_closed_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_t.txt new file mode 100644 index 00000000..e2899909 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_closed_t.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_closed_t: + +========================== +mongoc_apm_server_closed_t +========================== + +Server-closed event + +Synopsis +-------- + +An event notification sent when the driver stops monitoring a server and removes its +:ref:`mongoc_server_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_server_closed_get_topology_id + +- :ref:`mongoc_apm_server_closed_get_context` +- :ref:`mongoc_apm_server_closed_get_host` +- :ref:`mongoc_apm_server_closed_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_awaited.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_awaited.txt new file mode 100644 index 00000000..8f71e146 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_awaited.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_failed_get_awaited: + +================================================ +mongoc_apm_server_heartbeat_failed_get_awaited() +================================================ + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_apm_server_heartbeat_failed_get_awaited ( + const mongoc_apm_server_heartbeat_failed_t *event); + +Returns whether this event came from an awaitable hello. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_failed_t`. + +Returns +------- + +A bool indicating whether the heartbeat event came from an awaitable hello. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_context.txt new file mode 100644 index 00000000..9c9d0c5e --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_failed_get_context: + +================================================ +mongoc_apm_server_heartbeat_failed_get_context() +================================================ + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_heartbeat_failed_get_context ( + const mongoc_apm_server_heartbeat_failed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_failed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_duration.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_duration.txt new file mode 100644 index 00000000..a3bbfc00 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_duration.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_failed_get_duration: + +================================================= +mongoc_apm_server_heartbeat_failed_get_duration() +================================================= + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_server_heartbeat_failed_get_duration ( + const mongoc_apm_server_heartbeat_failed_t *event); + +Returns this event's duration in microseconds. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_failed_t`. + +Returns +------- + +The event's duration. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_error.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_error.txt new file mode 100644 index 00000000..13aeb0f2 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_error.txt @@ -0,0 +1,27 @@ +.. _mongoc_apm_server_heartbeat_failed_get_error: + +============================================== +mongoc_apm_server_heartbeat_failed_get_error() +============================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_server_heartbeat_failed_get_error ( + const mongoc_apm_server_heartbeat_failed_t *event, bson_error_t *error); + +Copies this event's error info. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_failed_t`. +- ``error``: A :ref:`bson_error_t` to receive the event's error info. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_host.txt new file mode 100644 index 00000000..c42cef23 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_host.txt @@ -0,0 +1,33 @@ +.. _mongoc_apm_server_heartbeat_failed_get_host: + +============================================= +mongoc_apm_server_heartbeat_failed_get_host() +============================================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_heartbeat_failed_get_host ( + const mongoc_apm_server_heartbeat_failed_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_failed_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_t.txt new file mode 100644 index 00000000..523d7fc8 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_t.txt @@ -0,0 +1,36 @@ +.. _mongoc_apm_server_heartbeat_failed_t: + +==================================== +mongoc_apm_server_heartbeat_failed_t +==================================== + +Heartbeat-failed event + +Synopsis +-------- + +An event notification sent when the driver failed to send a "hello" command to check the status +of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_awaited + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_duration + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_error + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_failed_get_host + +- :ref:`mongoc_apm_server_heartbeat_failed_get_awaited` +- :ref:`mongoc_apm_server_heartbeat_failed_get_context` +- :ref:`mongoc_apm_server_heartbeat_failed_get_duration` +- :ref:`mongoc_apm_server_heartbeat_failed_get_error` +- :ref:`mongoc_apm_server_heartbeat_failed_get_host` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_awaited.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_awaited.txt new file mode 100644 index 00000000..99775d60 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_awaited.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_started_get_awaited: + +================================================= +mongoc_apm_server_heartbeat_started_get_awaited() +================================================= + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_apm_server_heartbeat_started_get_awaited ( + const mongoc_apm_server_heartbeat_started_t *event); + +Returns whether this event came from an awaitable hello. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_started_t`. + +Returns +------- + +A bool indicating whether the heartbeat event came from an awaitable hello. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_context.txt new file mode 100644 index 00000000..0245c14f --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_started_get_context: + +================================================= +mongoc_apm_server_heartbeat_started_get_context() +================================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_heartbeat_started_get_context ( + const mongoc_apm_server_heartbeat_started_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_started_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_host.txt new file mode 100644 index 00000000..4e6a0849 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_host.txt @@ -0,0 +1,33 @@ +.. _mongoc_apm_server_heartbeat_started_get_host: + +============================================== +mongoc_apm_server_heartbeat_started_get_host() +============================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_heartbeat_started_get_host ( + const mongoc_apm_server_heartbeat_started_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_started_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_t.txt new file mode 100644 index 00000000..b8288394 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_t.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_heartbeat_started_t: + +===================================== +mongoc_apm_server_heartbeat_started_t +===================================== + +Heartbeat-started event + +Synopsis +-------- + +An event notification sent when the driver begins executing a "hello" command to check the +status of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_awaited + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_started_get_host + +- :ref:`mongoc_apm_server_heartbeat_started_get_awaited` +- :ref:`mongoc_apm_server_heartbeat_started_get_context` +- :ref:`mongoc_apm_server_heartbeat_started_get_host` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_awaited.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_awaited.txt new file mode 100644 index 00000000..20f08189 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_awaited.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_succeeded_get_awaited: + +=================================================== +mongoc_apm_server_heartbeat_succeeded_get_awaited() +=================================================== + +Synopsis +-------- + +.. code-block:: c + + bool + mongoc_apm_server_heartbeat_succeeded_get_awaited ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + +Returns whether this event came from an awaitable hello. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_succeeded_t`. + +Returns +------- + +A bool indicating whether the heartbeat event came from an awaitable hello. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_context.txt new file mode 100644 index 00000000..9f6c08e4 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_succeeded_get_context: + +=================================================== +mongoc_apm_server_heartbeat_succeeded_get_context() +=================================================== + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_heartbeat_succeeded_get_context ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_succeeded_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_duration.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_duration.txt new file mode 100644 index 00000000..e806b48c --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_duration.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_heartbeat_succeeded_get_duration: + +==================================================== +mongoc_apm_server_heartbeat_succeeded_get_duration() +==================================================== + +Synopsis +-------- + +.. code-block:: c + + int64_t + mongoc_apm_server_heartbeat_succeeded_get_duration ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + +Returns this event's duration in microseconds. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_succeeded_t`. + +Returns +------- + +The event's duration. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_host.txt new file mode 100644 index 00000000..fa1bb121 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_host.txt @@ -0,0 +1,33 @@ +.. _mongoc_apm_server_heartbeat_succeeded_get_host: + +================================================ +mongoc_apm_server_heartbeat_succeeded_get_host() +================================================ + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_heartbeat_succeeded_get_host ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_succeeded_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_reply.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_reply.txt new file mode 100644 index 00000000..83c2dd76 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_reply.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_heartbeat_succeeded_get_reply: + +================================================= +mongoc_apm_server_heartbeat_succeeded_get_reply() +================================================= + +Synopsis +-------- + +.. code-block:: c + + const bson_t * + mongoc_apm_server_heartbeat_succeeded_get_reply ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + +Returns this event's reply. The data is only valid in the scope of the callback that +receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_heartbeat_succeeded_t`. + +Returns +------- + +A :ref:`bson_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_t.txt new file mode 100644 index 00000000..e353eeb0 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_t.txt @@ -0,0 +1,36 @@ +.. _mongoc_apm_server_heartbeat_succeeded_t: + +======================================= +mongoc_apm_server_heartbeat_succeeded_t +======================================= + +Heartbeat-succeeded event + +Synopsis +-------- + +An event notification sent when the driver completes a "hello" command to check the status +of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_awaited + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_duration + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_server_heartbeat_succeeded_get_reply + +- :ref:`mongoc_apm_server_heartbeat_succeeded_get_awaited` +- :ref:`mongoc_apm_server_heartbeat_succeeded_get_context` +- :ref:`mongoc_apm_server_heartbeat_succeeded_get_duration` +- :ref:`mongoc_apm_server_heartbeat_succeeded_get_host` +- :ref:`mongoc_apm_server_heartbeat_succeeded_get_reply` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_context.txt new file mode 100644 index 00000000..c691490b --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_server_opening_get_context: + +======================================= +mongoc_apm_server_opening_get_context() +======================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_server_opening_get_context ( + const mongoc_apm_server_opening_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_opening_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_host.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_host.txt new file mode 100644 index 00000000..b826c873 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_host.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_opening_get_host: + +==================================== +mongoc_apm_server_opening_get_host() +==================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_host_list_t * + mongoc_apm_server_opening_get_host (const mongoc_apm_server_opening_t *event); + +Returns this event's host. This :ref:`mongoc_host_list_t` is *not* part of a linked list, +it is solely the server for this event. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_opening_t`. + +Returns +------- + +A :ref:`mongoc_host_list_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_topology_id.txt new file mode 100644 index 00000000..92d4d6ff --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_opening_get_topology_id: + +=========================================== +mongoc_apm_server_opening_get_topology_id() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_server_opening_get_topology_id ( + const mongoc_apm_server_opening_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_server_opening_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_t.txt new file mode 100644 index 00000000..13d96c65 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_server_opening_t.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_server_opening_t: + +=========================== +mongoc_apm_server_opening_t +=========================== + +Server-opening event + +Synopsis +-------- + +An event notification sent when the driver adds a :ref:`mongoc_server_description_t` for a new +server it was not monitoring before. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_host + /libmongoc/application-performance-monitoring/mongoc_apm_server_opening_get_topology_id + +- :ref:`mongoc_apm_server_opening_get_context` +- :ref:`mongoc_apm_server_opening_get_host` +- :ref:`mongoc_apm_server_opening_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_failed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_failed_cb.txt new file mode 100644 index 00000000..8fc75715 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_failed_cb.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_set_command_failed_cb: + +================================== +mongoc_apm_set_command_failed_cb() +================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_command_failed_cb_t) ( + const mongoc_apm_command_failed_t *event); + + void + mongoc_apm_set_command_failed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_command_failed_cb_t cb); + +Receive an event notification whenever the driver fails to execute a MongoDB operation. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_command_failed_t` whenever a MongoDB + operation fails. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_started_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_started_cb.txt new file mode 100644 index 00000000..73c0de38 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_started_cb.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_set_command_started_cb: + +=================================== +mongoc_apm_set_command_started_cb() +=================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_command_started_cb_t) ( + const mongoc_apm_command_started_t *event); + + void + mongoc_apm_set_command_started_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_command_started_cb_t cb); + +Receive an event notification whenever the driver starts a MongoDB operation. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_command_started_t` whenever the driver + begins a MongoDB operation. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_succeeded_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_succeeded_cb.txt new file mode 100644 index 00000000..8118fbc1 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_command_succeeded_cb.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_set_command_succeeded_cb: + +===================================== +mongoc_apm_set_command_succeeded_cb() +===================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_command_succeeded_cb_t) ( + const mongoc_apm_command_succeeded_t *event); + + void + mongoc_apm_set_command_succeeded_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_command_succeeded_cb_t cb); + +Receive an event notification whenever the driver completes a MongoDB operation. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_command_succeeded_t` whenever the driver + completes a MongoDB operation. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_changed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_changed_cb.txt new file mode 100644 index 00000000..bdefdf35 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_changed_cb.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_set_server_changed_cb: + +================================== +mongoc_apm_set_server_changed_cb() +================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_changed_cb_t) ( + const mongoc_apm_server_changed_t *event); + + void + mongoc_apm_set_server_changed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_changed_cb_t cb); + +Receive an event notification whenever the driver observes a change in status of a server +it is connected to. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_changed_t` whenever the driver observes a change in status of a server it is connected to. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_closed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_closed_cb.txt new file mode 100644 index 00000000..63d10465 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_closed_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_server_closed_cb: + +================================= +mongoc_apm_set_server_closed_cb() +================================= + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_closed_cb_t) ( + const mongoc_apm_server_closed_t *event); + + void + mongoc_apm_set_server_closed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_closed_cb_t cb); + +Receive an event notification whenever the driver stops monitoring a server and removes +its :ref:`mongoc_server_description_t`. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_closed_t` whenever the driver + stops monitoring a server and removes its :ref:`mongoc_server_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_failed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_failed_cb.txt new file mode 100644 index 00000000..03dc13ef --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_failed_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_server_heartbeat_failed_cb: + +=========================================== +mongoc_apm_set_server_heartbeat_failed_cb() +=========================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_heartbeat_failed_cb_t) ( + const mongoc_apm_server_heartbeat_failed_t *event); + + void + mongoc_apm_set_server_heartbeat_failed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_heartbeat_failed_cb_t cb); + +Receive an event notification whenever the driver fails to send a "hello" command to check +the status of a server. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_heartbeat_failed_t` whenever the + driver fails to send a "hello" command to check the status of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_started_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_started_cb.txt new file mode 100644 index 00000000..07ad9c9c --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_started_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_server_heartbeat_started_cb: + +============================================ +mongoc_apm_set_server_heartbeat_started_cb() +============================================ + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_heartbeat_started_cb_t) ( + const mongoc_apm_server_heartbeat_started_t *event); + + void + mongoc_apm_set_server_heartbeat_started_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_heartbeat_started_cb_t cb); + +Receive an event notification whenever the driver begins executing a "hello" command to check +the status of a server. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_heartbeat_started_t` whenever the + driver begins executing a "hello" command to check the status of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_succeeded_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_succeeded_cb.txt new file mode 100644 index 00000000..466dee8b --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_heartbeat_succeeded_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_server_heartbeat_succeeded_cb: + +============================================== +mongoc_apm_set_server_heartbeat_succeeded_cb() +============================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_heartbeat_succeeded_cb_t) ( + const mongoc_apm_server_heartbeat_succeeded_t *event); + + void + mongoc_apm_set_server_heartbeat_succeeded_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_heartbeat_succeeded_cb_t cb); + +Receive an event notification whenever the driver completes a "hello" command to check the +status of a server. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_heartbeat_succeeded_t` whenever the + driver completes a "hello" command to check the status of a server. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_opening_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_opening_cb.txt new file mode 100644 index 00000000..ac8fd38c --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_server_opening_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_server_opening_cb: + +================================== +mongoc_apm_set_server_opening_cb() +================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_server_opening_cb_t) ( + const mongoc_apm_server_opening_t *event); + + void + mongoc_apm_set_server_opening_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_server_opening_cb_t cb); + +Receive an event notification whenever the driver adds a :ref:`mongoc_server_description_t` +for a new server it was not monitoring before. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_server_opening_t` whenever the driver adds + a :ref:`mongoc_server_description_t` for a new server it was not monitoring before. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_changed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_changed_cb.txt new file mode 100644 index 00000000..da7606f1 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_changed_cb.txt @@ -0,0 +1,33 @@ +.. _mongoc_apm_set_topology_changed_cb: + +==================================== +mongoc_apm_set_topology_changed_cb() +==================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_topology_changed_cb_t) ( + const mongoc_apm_topology_changed_t *event); + + void + mongoc_apm_set_topology_changed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_topology_changed_cb_t cb); + +Receive an event notification whenever the driver observes a change in any of the +servers it is connected to or a change in the overall server topology. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_topology_changed_t` whenever the driver + observes a change in any of the servers it is connected to or a change in the overall server + topology. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_closed_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_closed_cb.txt new file mode 100644 index 00000000..c6140658 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_closed_cb.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_set_topology_closed_cb: + +=================================== +mongoc_apm_set_topology_closed_cb() +=================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_topology_closed_cb_t) ( + const mongoc_apm_topology_closed_t *event); + + void + mongoc_apm_set_topology_closed_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_topology_closed_cb_t cb); + +Receive an event notification whenever the driver stops monitoring a server topology +and destroys its :ref:`mongoc_topology_description_t`. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_topology_closed_t` whenever the driver + stops monitoring a server topology and destroys its :ref:`mongoc_topology_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_opening_cb.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_opening_cb.txt new file mode 100644 index 00000000..7eb69ebe --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_set_topology_opening_cb.txt @@ -0,0 +1,30 @@ +.. _mongoc_apm_set_topology_opening_cb: + +==================================== +mongoc_apm_set_topology_opening_cb() +==================================== + +Synopsis +-------- + +.. code-block:: c + + typedef void (*mongoc_apm_topology_opening_cb_t) ( + const mongoc_apm_topology_opening_t *event); + + void + mongoc_apm_set_topology_opening_cb (mongoc_apm_callbacks_t *callbacks, + mongoc_apm_topology_opening_cb_t cb); + +Receive an event notification whenever the driver initializes a :ref:`mongoc_topology_description_t`. + +Parameters +---------- + +- ``callbacks``: A :ref:`mongoc_apm_callbacks_t`. +- ``cb``: A function to call with a :ref:`mongoc_apm_topology_opening_t` whenever the driver initializes a :ref:`mongoc_topology_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_context.txt new file mode 100644 index 00000000..f671a155 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_topology_changed_get_context: + +========================================= +mongoc_apm_topology_changed_get_context() +========================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_topology_changed_get_context ( + const mongoc_apm_topology_changed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_changed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_new_description.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_new_description.txt new file mode 100644 index 00000000..ada8e95d --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_new_description.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_topology_changed_get_new_description: + +================================================= +mongoc_apm_topology_changed_get_new_description() +================================================= + +Synopsis +-------- + +.. code-block:: c + + const mongoc_topology_description_t * + mongoc_apm_topology_changed_get_new_description ( + const mongoc_apm_topology_changed_t *event); + +Returns this event's new description. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_changed_t`. + +Returns +------- + +A :ref:`mongoc_topology_description_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_previous_description.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_previous_description.txt new file mode 100644 index 00000000..bbc1b08a --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_previous_description.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_topology_changed_get_previous_description: + +====================================================== +mongoc_apm_topology_changed_get_previous_description() +====================================================== + +Synopsis +-------- + +.. code-block:: c + + const mongoc_topology_description_t * + mongoc_apm_topology_changed_get_previous_description ( + const mongoc_apm_topology_changed_t *event); + +Returns this event's previous description. The data is only valid in the scope of the callback +that receives this event; copy it if it will be accessed after the callback returns. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_changed_t`. + +Returns +------- + +A :ref:`mongoc_topology_description_t` that should not be modified or freed. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_topology_id.txt new file mode 100644 index 00000000..1a8295e3 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_topology_changed_get_topology_id: + +============================================= +mongoc_apm_topology_changed_get_topology_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_topology_changed_get_topology_id ( + const mongoc_apm_topology_changed_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_changed_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_t.txt new file mode 100644 index 00000000..bf866901 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_t.txt @@ -0,0 +1,34 @@ +.. _mongoc_apm_topology_changed_t: + +============================= +mongoc_apm_topology_changed_t +============================= + +Topology-changed event + +Synopsis +-------- + +An event notification sent when the driver observes a change in any of the servers it is +connected to or a change in the overall server topology. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_new_description + /libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_previous_description + /libmongoc/application-performance-monitoring/mongoc_apm_topology_changed_get_topology_id + +- :ref:`mongoc_apm_topology_changed_get_context` +- :ref:`mongoc_apm_topology_changed_get_new_description` +- :ref:`mongoc_apm_topology_changed_get_previous_description` +- :ref:`mongoc_apm_topology_changed_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_context.txt new file mode 100644 index 00000000..dd2f42ce --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_topology_closed_get_context: + +======================================== +mongoc_apm_topology_closed_get_context() +======================================== + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_topology_closed_get_context ( + const mongoc_apm_topology_closed_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_closed_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_topology_id.txt new file mode 100644 index 00000000..8e4310fd --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_topology_closed_get_topology_id: + +============================================ +mongoc_apm_topology_closed_get_topology_id() +============================================ + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_topology_closed_get_topology_id ( + const mongoc_apm_topology_closed_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_closed_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_t.txt new file mode 100644 index 00000000..80629378 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_t.txt @@ -0,0 +1,30 @@ +.. _mongoc_apm_topology_closed_t: + +============================ +mongoc_apm_topology_closed_t +============================ + +Topology-closed event + +Synopsis +-------- + +An event notification sent when the driver stops monitoring a server topology and destroys +its :ref:`mongoc_topology_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_topology_closed_get_topology_id + +- :ref:`mongoc_apm_topology_closed_get_context` +- :ref:`mongoc_apm_topology_closed_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_context.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_context.txt new file mode 100644 index 00000000..90c0db57 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_context.txt @@ -0,0 +1,31 @@ +.. _mongoc_apm_topology_opening_get_context: + +========================================= +mongoc_apm_topology_opening_get_context() +========================================= + +Synopsis +-------- + +.. code-block:: c + + void * + mongoc_apm_topology_opening_get_context ( + const mongoc_apm_topology_opening_t *event); + +Returns this event's context. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_opening_t`. + +Returns +------- + +The pointer passed with :ref:`mongoc_client_set_apm_callbacks` or :ref:`mongoc_client_pool_set_apm_callbacks`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_topology_id.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_topology_id.txt new file mode 100644 index 00000000..37d33994 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_topology_id.txt @@ -0,0 +1,32 @@ +.. _mongoc_apm_topology_opening_get_topology_id: + +============================================= +mongoc_apm_topology_opening_get_topology_id() +============================================= + +Synopsis +-------- + +.. code-block:: c + + void + mongoc_apm_topology_opening_get_topology_id ( + const mongoc_apm_topology_opening_t *event, bson_oid_t *topology_id); + +Returns this event's topology id. + +Parameters +---------- + +- ``event``: A :ref:`mongoc_apm_topology_opening_t`. +- ``topology_id``: A :ref:`bson_oid_t` to receive the event's topology_id. + +Returns +------- + +The event's topology id. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + diff --git a/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_t.txt b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_t.txt new file mode 100644 index 00000000..380f6b06 --- /dev/null +++ b/source/libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_t.txt @@ -0,0 +1,29 @@ +.. _mongoc_apm_topology_opening_t: + +============================= +mongoc_apm_topology_opening_t +============================= + +Topology-opening event + +Synopsis +-------- + +An event notification sent when the driver initializes a :ref:`mongoc_topology_description_t`. + +.. seealso:: + + | :ref:`Introduction to Application Performance Monitoring ` + +Functions +--------- + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_context + /libmongoc/application-performance-monitoring/mongoc_apm_topology_opening_get_topology_id + +- :ref:`mongoc_apm_topology_opening_get_context` +- :ref:`mongoc_apm_topology_opening_get_topology_id` \ No newline at end of file diff --git a/source/libmongoc/guides/advanced-connections.txt b/source/libmongoc/guides/advanced-connections.txt index fd52c642..9b95ce83 100644 --- a/source/libmongoc/guides/advanced-connections.txt +++ b/source/libmongoc/guides/advanced-connections.txt @@ -171,7 +171,7 @@ This content has been relocated to the :ref:`Data Compression `__ docs. +The full list of connection options can be found in the :ref:`mongoc_uri_t` docs. Certain socket/connection related options are not configurable: diff --git a/source/libmongoc/guides/bulk.txt b/source/libmongoc/guides/bulk.txt index 247867cc..7cd520d9 100644 --- a/source/libmongoc/guides/bulk.txt +++ b/source/libmongoc/guides/bulk.txt @@ -17,7 +17,7 @@ throughput. Bulk Insert ----------- -First we need to fetch a bulk operation handle from the `mongoc_collection_t <{+api-libmongoc+}/mongoc_collection_t.html>`__. +First we need to fetch a bulk operation handle from the :ref:`mongoc_collection_t`. .. code-block:: c @@ -28,11 +28,9 @@ We can now start inserting documents to the bulk operation. These will be buffer operation. The bulk operation will coalesce insertions as a single batch for each consecutive call to -`mongoc_bulk_operation_insert <{+api-libmongoc+}/mongoc_bulk_operation_insert.html>`__. This creates -a pipelined effect when possible. +:ref:`mongoc_bulk_operation_insert`. This creates a pipelined effect when possible. -To execute the bulk operation and receive the result we call `mongoc_bulk_operation_execute -<{+api-libmongoc+}/mongoc_bulk_operation_execute.html>`__. +To execute the bulk operation and receive the result we call :ref:`mongoc_bulk_operation_execute`. .. literalinclude:: /libmongoc/includes/examples/bulk/bulk1.c :language: c @@ -115,7 +113,7 @@ Example ``reply`` document: Error: E11000 duplicate key error index: test.test.$_id_ dup key: { : 1 } -The `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ domain is ``MONGOC_ERROR_COMMAND`` and its code is 11000. +The :ref:`bson_error_t` domain is ``MONGOC_ERROR_COMMAND`` and its code is 11000. .. _bulk_operation_bypassing_document_validation: @@ -154,14 +152,13 @@ Running the above example will result in: "nUpserted" : 0, "writeErrors" : [] } -The `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ domain is ``MONGOC_ERROR_COMMAND``. +The :ref:`bson_error_t` domain is ``MONGOC_ERROR_COMMAND``. Bulk Operation Write Concerns ----------------------------- -By default bulk operations are executed with the `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ -of the collection they are executed against. A custom write concern can be passed to the -`mongoc_collection_create_bulk_operation_with_opts <{+api-libmongoc+}/mongoc_collection_create_bulk_operation_with_opts.html>`__ +By default bulk operations are executed with the :ref:`mongoc_write_concern_t` of the collection they +are executed against. A custom write concern can be passed to the :ref:`mongoc_collection_create_bulk_operation_with_opts` method. Write concern errors (e.g. wtimeout) will be reported after all operations are attempted, regardless of execution order. @@ -186,7 +183,7 @@ Example ``reply`` document and error message: Error: waiting for replication timed out -The `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ domain is ``MONGOC_ERROR_WRITE_CONCERN`` if there are write concern errors and no +The :ref:`bson_error_t` domain is ``MONGOC_ERROR_WRITE_CONCERN`` if there are write concern errors and no write errors. Write errors indicate failed operations, so they take precedence over write concern errors, which mean merely that the write concern is not satisfied *yet*. diff --git a/source/libmongoc/guides/connection-pooling.txt b/source/libmongoc/guides/connection-pooling.txt index aa7fe358..d52a2211 100644 --- a/source/libmongoc/guides/connection-pooling.txt +++ b/source/libmongoc/guides/connection-pooling.txt @@ -33,7 +33,7 @@ have completed or timed out. Once the scan completes, the client executes your p In single mode, the client re-scans the server topology roughly once per minute. If more than a minute has elapsed since the previous scan, the next operation on the client will block while the client completes its -scan. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__.) +scan. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See :ref:`mongoc_uri_t`.) A single client opens one connection per server in your topology: these connections are used both for scanning the topology and performing normal operations. @@ -74,10 +74,10 @@ as soon as the primary is discovered, rather than waiting for all secondaries to The pool opens one connection per server for monitoring, and each client opens its own connection to each server it uses for application operations. Background monitoring threads re-scan servers independently roughly every 10 -seconds. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__.) +seconds. This interval is configurable with ``heartbeatFrequencyMS`` in the connection string. (See :ref:`mongoc_uri_t`.) The connection string can also specify ``waitQueueTimeoutMS`` to limit the time that :ref:`mongoc_client_pool_pop` will -wait for a client from the pool. (See `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__.) If ``waitQueueTimeoutMS`` is specified, then it is necessary +wait for a client from the pool. (See :ref:`mongoc_uri_t`.) If ``waitQueueTimeoutMS`` is specified, then it is necessary to confirm that a client was actually returned: .. code-block:: c diff --git a/source/libmongoc/includes/aggregate-opts.txt b/source/libmongoc/includes/aggregate-opts.txt index 9079c40d..9bb099ec 100644 --- a/source/libmongoc/includes/aggregate-opts.txt +++ b/source/libmongoc/includes/aggregate-opts.txt @@ -7,7 +7,7 @@ ``opts`` may be NULL or a BSON document with additional command options: * ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from opts-source, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``bypassDocumentValidation``: Set to ``true`` to skip server-side schema validation of the provided BSON documents. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. diff --git a/source/libmongoc/includes/bulk-opts.txt b/source/libmongoc/includes/bulk-opts.txt index be513b79..25455e46 100644 --- a/source/libmongoc/includes/bulk-opts.txt +++ b/source/libmongoc/includes/bulk-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``ordered``: set to ``false`` to attempt to insert all documents, continuing after errors. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. diff --git a/source/libmongoc/includes/create-index-opts.txt b/source/libmongoc/includes/create-index-opts.txt index c4192c36..dbba5841 100644 --- a/source/libmongoc/includes/create-index-opts.txt +++ b/source/libmongoc/includes/create-index-opts.txt @@ -6,5 +6,5 @@ ``command_opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. diff --git a/source/libmongoc/includes/delete-many-opts.txt b/source/libmongoc/includes/delete-many-opts.txt index 0a54a58e..2be63b12 100644 --- a/source/libmongoc/includes/delete-many-opts.txt +++ b/source/libmongoc/includes/delete-many-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/delete-one-opts.txt b/source/libmongoc/includes/delete-one-opts.txt index 9e8d3221..e666ccd7 100644 --- a/source/libmongoc/includes/delete-one-opts.txt +++ b/source/libmongoc/includes/delete-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +- ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. - ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``collection``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. - ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. diff --git a/source/libmongoc/includes/find-and-modify-appended-opts.txt b/source/libmongoc/includes/find-and-modify-appended-opts.txt index af5d31e0..2d4ee519 100644 --- a/source/libmongoc/includes/find-and-modify-appended-opts.txt +++ b/source/libmongoc/includes/find-and-modify-appended-opts.txt @@ -6,7 +6,7 @@ ``extra`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``hint``: A document or string that specifies the index to use to support the query predicate. * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language. diff --git a/source/libmongoc/includes/gridfs-bucket-opts.txt b/source/libmongoc/includes/gridfs-bucket-opts.txt index 2ee5c1cd..25acb4bc 100644 --- a/source/libmongoc/includes/gridfs-bucket-opts.txt +++ b/source/libmongoc/includes/gridfs-bucket-opts.txt @@ -8,5 +8,5 @@ * ``bucketName``: A UTF-8 string used as the prefix to the GridFS "chunks" and "files" collections. Defaults to "fs". The bucket name, together with the database and suffix collections must not exceed 120 characters. See the manual for `the max namespace length `_. * ``chunkSizeBytes``: An ``int32`` representing the chunk size. Defaults to 255KB. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. diff --git a/source/libmongoc/includes/gridfs-bucket-upload-opts.txt b/source/libmongoc/includes/gridfs-bucket-upload-opts.txt index 9fb528cc..90bddd64 100644 --- a/source/libmongoc/includes/gridfs-bucket-upload-opts.txt +++ b/source/libmongoc/includes/gridfs-bucket-upload-opts.txt @@ -7,4 +7,4 @@ ``opts`` may be NULL or a BSON document with additional command options: * ``chunkSizeBytes``: An ``int32`` chunk size to use for this file. Overrides the ``chunkSizeBytes`` set on ``bucket``. -* ``metadata``: A `bson_t <{+api-libbson+}/bson_t.html>`__ representing metadata to include with the file. +* ``metadata``: A :ref:`bson_t` representing metadata to include with the file. diff --git a/source/libmongoc/includes/insert-many-opts.txt b/source/libmongoc/includes/insert-many-opts.txt index e210d63e..bbc2318c 100644 --- a/source/libmongoc/includes/insert-many-opts.txt +++ b/source/libmongoc/includes/insert-many-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/insert-one-opts.txt b/source/libmongoc/includes/insert-one-opts.txt index 207dc823..6780c9d1 100644 --- a/source/libmongoc/includes/insert-one-opts.txt +++ b/source/libmongoc/includes/insert-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``collection``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/read-write-opts.txt b/source/libmongoc/includes/read-write-opts.txt index 4fc59249..783bd894 100644 --- a/source/libmongoc/includes/read-write-opts.txt +++ b/source/libmongoc/includes/read-write-opts.txt @@ -7,7 +7,7 @@ ``opts`` may be NULL or a BSON document with additional command options: * ``readConcern``: Construct a :ref:`mongoc_read_concern_t` and use :ref:`mongoc_read_concern_append` to add the read concern to ``opts``. See the example code for :ref:`mongoc_client_read_command_with_opts`. Read concern requires MongoDB 3.2 or later, otherwise an error is returned. -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. * ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/includes/replace-one-opts.txt b/source/libmongoc/includes/replace-one-opts.txt index 9ea78722..1d0eb1d0 100644 --- a/source/libmongoc/includes/replace-one-opts.txt +++ b/source/libmongoc/includes/replace-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/retryable-read-aggregate.txt b/source/libmongoc/includes/retryable-read-aggregate.txt index faa20fa0..980349b5 100644 --- a/source/libmongoc/includes/retryable-read-aggregate.txt +++ b/source/libmongoc/includes/retryable-read-aggregate.txt @@ -2,4 +2,4 @@ This function is considered a retryable read operation unless the pipeline contains a write stage like $out or $merge. Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. -If ``retryreads`` is false in the URI (see `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__) the retry behavior does not apply. \ No newline at end of file +If ``retryreads`` is false in the URI (see :ref:`mongoc_uri_t`) the retry behavior does not apply. \ No newline at end of file diff --git a/source/libmongoc/includes/retryable-read.txt b/source/libmongoc/includes/retryable-read.txt index db4cfe02..a157e560 100644 --- a/source/libmongoc/includes/retryable-read.txt +++ b/source/libmongoc/includes/retryable-read.txt @@ -2,4 +2,4 @@ This function is considered a retryable read operation. Upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. -If ``retryreads`` is false in the URI (see `mongoc_uri_t <{+api-libmongoc+}/mongoc_uri_t.html>`__) the retry behavior does not apply. \ No newline at end of file +If ``retryreads`` is false in the URI (see :ref:`mongoc_uri_t`) the retry behavior does not apply. \ No newline at end of file diff --git a/source/libmongoc/includes/returns-cursor.txt b/source/libmongoc/includes/returns-cursor.txt index 3931725a..26ffeb21 100644 --- a/source/libmongoc/includes/returns-cursor.txt +++ b/source/libmongoc/includes/returns-cursor.txt @@ -4,7 +4,7 @@ This function returns a newly allocated :ref:`mongoc_cursor_t` that should be fr when no longer in use. The returned :ref:`mongoc_cursor_t` is never ``NULL``, even on error. The user must call :ref:`mongoc_cursor_next` on the returned :ref:`mongoc_cursor_t` to execute the initial command. -Cursor errors can be checked with :ref:`mongoc_cursor_error_document`. It always fills out the `bson_error_t <{+api-libbson+}/bson_error_t.html>`__ if +Cursor errors can be checked with :ref:`mongoc_cursor_error_document`. It always fills out the :ref:`bson_error_t` if an error occurred, and optionally includes a server reply document if the error occurred server-side. .. warning:: diff --git a/source/libmongoc/includes/update-many-opts.txt b/source/libmongoc/includes/update-many-opts.txt index bb61dd60..50eb6ab6 100644 --- a/source/libmongoc/includes/update-many-opts.txt +++ b/source/libmongoc/includes/update-many-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/update-one-opts.txt b/source/libmongoc/includes/update-one-opts.txt index bb61dd60..50eb6ab6 100644 --- a/source/libmongoc/includes/update-one-opts.txt +++ b/source/libmongoc/includes/update-one-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -* ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +* ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. * ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. * ``validate``: Construct a bitwise-or of all desired :ref:`bson_validate_flags_t `. Set to ``false`` to skip client-side validation of the provided BSON documents. * ``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. diff --git a/source/libmongoc/includes/write-opts.txt b/source/libmongoc/includes/write-opts.txt index 1cb34d14..5b867dcf 100644 --- a/source/libmongoc/includes/write-opts.txt +++ b/source/libmongoc/includes/write-opts.txt @@ -6,7 +6,7 @@ ``opts`` may be NULL or a BSON document with additional command options: -- ``writeConcern``: Construct a `mongoc_write_concern_t <{+api-libmongoc+}/mongoc_write_concern_t.html>`__ and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. +- ``writeConcern``: Construct a :ref:`mongoc_write_concern_t` and use :ref:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :ref:`mongoc_client_write_command_with_opts`. - ``sessionId``: First, construct a :ref:`mongoc_client_session_t` with :ref:`mongoc_client_start_session`. You can begin a transaction with :ref:`mongoc_client_session_start_transaction`, optionally with a :ref:`mongoc_transaction_opt_t` that overrides the options inherited from ``database,`` ``collection``, or ``client``, and use :ref:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :ref:`mongoc_client_session_t`. - ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order `, and `the MongoDB Manual entry on Collation `_. Collation requires MongoDB 3.2 or later, otherwise an error is returned. - ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :ref:`mongoc_client_select_server`, then :ref:`mongoc_server_description_id` on its return value. diff --git a/source/libmongoc/tutorial.txt b/source/libmongoc/tutorial.txt index 657cf47b..e39c251b 100644 --- a/source/libmongoc/tutorial.txt +++ b/source/libmongoc/tutorial.txt @@ -116,7 +116,7 @@ Making a Connection Access MongoDB with a :ref:`mongoc_client_t`. It transparently connects to standalone servers, replica sets and sharded clusters on demand. To perform operations on a database or collection, create a :ref:`mongoc_database_t` -or `mongoc_collection_t <{+api-libmongoc+}/mongoc_collection_t.html>`__ struct from the :ref:`mongoc_client_t`. +or :ref:`mongoc_collection_t` struct from the :ref:`mongoc_client_t`. At the start of an application, call :ref:`mongoc_init` before any other libmongoc functions. At the end, call the appropriate destroy function for each collection, database, or client handle, in reverse order from how they @@ -167,7 +167,7 @@ Use the following code: .. literalinclude:: /libmongoc/includes/examples/tutorial/appending.c :language: c -See the :ref:`libbson documentation ` for all of the types that can be appended to a `bson_t <{+api-libbson+}/bson_t.html>`__. +See the :ref:`libbson documentation ` for all of the types that can be appended to a :ref:`bson_t`. Using BCON ~~~~~~~~~~ From b534bd396ceca6322d145b8839df35b062c56795 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 15 Apr 2024 15:04:14 -0700 Subject: [PATCH 6/8] Revert "api link" This reverts commit f9de2be7f760bff50dba5cc8705d2a12f9da6201. --- source/libbson.txt | 1 - source/libbson/api.txt | 49 ++ source/libbson/api/bson_array_builder_t.txt | 219 +++++++ source/libbson/api/bson_context_t.txt | 77 +++ .../bson_context_t/bson_context_destroy.txt | 28 + .../bson_context_get_default.txt | 20 + .../api/bson_context_t/bson_context_new.txt | 42 ++ source/libbson/api/bson_decimal128_t.txt | 76 +++ .../bson_decimal128_from_string.txt | 42 ++ .../bson_decimal128_from_string_w_len.txt | 45 ++ .../bson_decimal128_to_string.txt | 33 + source/libbson/api/bson_error_t.txt | 55 ++ .../api/bson_error_t/bson_set_error.txt | 30 + .../api/bson_error_t/bson_strerror_r.txt | 31 + .../libbson/api/bson_get_monotonic_time.txt | 24 + source/libbson/api/bson_iter_t.txt | 236 +++++++ .../api/bson_iter_t/bson_iter_array.txt | 33 + .../api/bson_iter_t/bson_iter_as_bool.txt | 41 ++ .../api/bson_iter_t/bson_iter_as_double.txt | 38 ++ .../api/bson_iter_t/bson_iter_as_int64.txt | 35 + .../api/bson_iter_t/bson_iter_binary.txt | 38 ++ .../api/bson_iter_t/bson_iter_bool.txt | 33 + .../api/bson_iter_t/bson_iter_code.txt | 34 + .../api/bson_iter_t/bson_iter_codewscope.txt | 40 ++ .../api/bson_iter_t/bson_iter_date_time.txt | 33 + .../api/bson_iter_t/bson_iter_dbpointer.txt | 34 + .../api/bson_iter_t/bson_iter_decimal128.txt | 34 + .../api/bson_iter_t/bson_iter_document.txt | 33 + .../api/bson_iter_t/bson_iter_double.txt | 32 + .../api/bson_iter_t/bson_iter_dup_utf8.txt | 30 + .../api/bson_iter_t/bson_iter_find.txt | 34 + .../api/bson_iter_t/bson_iter_find_case.txt | 32 + .../bson_iter_t/bson_iter_find_descendant.txt | 36 ++ .../api/bson_iter_t/bson_iter_find_w_len.txt | 35 + .../api/bson_iter_t/bson_iter_init.txt | 73 +++ .../api/bson_iter_t/bson_iter_init_find.txt | 27 + .../bson_iter_t/bson_iter_init_find_case.txt | 29 + .../bson_iter_t/bson_iter_init_find_w_len.txt | 31 + .../bson_iter_t/bson_iter_init_from_data.txt | 57 ++ .../bson_iter_init_from_data_at_offset.txt | 62 ++ .../api/bson_iter_t/bson_iter_int32.txt | 32 + .../api/bson_iter_t/bson_iter_int64.txt | 32 + .../libbson/api/bson_iter_t/bson_iter_key.txt | 33 + .../api/bson_iter_t/bson_iter_key_len.txt | 35 + .../api/bson_iter_t/bson_iter_next.txt | 32 + .../api/bson_iter_t/bson_iter_offset.txt | 33 + .../libbson/api/bson_iter_t/bson_iter_oid.txt | 32 + .../bson_iter_t/bson_iter_overwrite_bool.txt | 29 + .../bson_iter_overwrite_date_time.txt | 29 + .../bson_iter_overwrite_decimal128.txt | 30 + .../bson_iter_overwrite_double.txt | 29 + .../bson_iter_t/bson_iter_overwrite_int32.txt | 29 + .../bson_iter_t/bson_iter_overwrite_int64.txt | 29 + .../bson_iter_t/bson_iter_overwrite_oid.txt | 29 + .../bson_iter_overwrite_timestamp.txt | 32 + .../api/bson_iter_t/bson_iter_recurse.txt | 36 ++ .../api/bson_iter_t/bson_iter_regex.txt | 34 + .../api/bson_iter_t/bson_iter_symbol.txt | 35 + .../api/bson_iter_t/bson_iter_time_t.txt | 30 + .../api/bson_iter_t/bson_iter_timestamp.txt | 38 ++ .../api/bson_iter_t/bson_iter_timeval.txt | 26 + .../api/bson_iter_t/bson_iter_type.txt | 54 ++ .../api/bson_iter_t/bson_iter_utf8.txt | 43 ++ .../api/bson_iter_t/bson_iter_value.txt | 32 + .../api/bson_iter_t/bson_iter_visit_all.txt | 37 ++ source/libbson/api/bson_json_reader_t.txt | 153 +++++ .../bson_json_data_reader_ingest.txt | 28 + .../bson_json_data_reader_new.txt | 32 + .../bson_json_reader_destroy.txt | 23 + .../bson_json_reader_new.txt | 39 ++ .../bson_json_reader_new_from_fd.txt | 30 + .../bson_json_reader_new_from_file.txt | 35 + .../bson_json_reader_read.txt | 39 ++ source/libbson/api/bson_memory.txt | 50 ++ .../api/bson_memory/bson_aligned_alloc.txt | 39 ++ .../api/bson_memory/bson_aligned_alloc0.txt | 40 ++ source/libbson/api/bson_memory/bson_free.txt | 24 + .../libbson/api/bson_memory/bson_malloc.txt | 37 ++ .../libbson/api/bson_memory/bson_malloc0.txt | 37 ++ .../bson_memory/bson_mem_restore_vtable.txt | 24 + .../api/bson_memory/bson_mem_set_vtable.txt | 40 ++ .../libbson/api/bson_memory/bson_realloc.txt | 39 ++ .../api/bson_memory/bson_realloc_ctx.txt | 27 + .../api/bson_memory/bson_realloc_func.txt | 27 + .../api/bson_memory/bson_zero_free.txt | 28 + source/libbson/api/bson_oid_t.txt | 125 ++++ .../api/bson_oid_t/bson_oid_compare.txt | 31 + .../bson_oid_t/bson_oid_compare_unsafe.txt | 18 + .../libbson/api/bson_oid_t/bson_oid_copy.txt | 25 + .../api/bson_oid_t/bson_oid_copy_unsafe.txt | 18 + .../libbson/api/bson_oid_t/bson_oid_equal.txt | 30 + .../api/bson_oid_t/bson_oid_equal_unsafe.txt | 18 + .../api/bson_oid_t/bson_oid_get_time_t.txt | 29 + .../bson_oid_t/bson_oid_get_time_t_unsafe.txt | 18 + .../libbson/api/bson_oid_t/bson_oid_hash.txt | 29 + .../api/bson_oid_t/bson_oid_hash_unsafe.txt | 18 + .../libbson/api/bson_oid_t/bson_oid_init.txt | 25 + .../bson_oid_t/bson_oid_init_from_data.txt | 25 + .../bson_oid_t/bson_oid_init_from_string.txt | 32 + .../bson_oid_init_from_string_unsafe.txt | 18 + .../api/bson_oid_t/bson_oid_init_sequence.txt | 37 ++ .../api/bson_oid_t/bson_oid_is_valid.txt | 30 + .../api/bson_oid_t/bson_oid_to_string.txt | 25 + source/libbson/api/bson_reader_t.txt | 154 +++++ .../api/bson_reader_t/bson_reader_destroy.txt | 23 + .../bson_reader_destroy_func_t.txt | 26 + .../bson_reader_new_from_data.txt | 32 + .../bson_reader_t/bson_reader_new_from_fd.txt | 36 ++ .../bson_reader_new_from_file.txt | 35 + .../bson_reader_new_from_handle.txt | 34 + .../api/bson_reader_t/bson_reader_read.txt | 53 ++ .../bson_reader_t/bson_reader_read_func_t.txt | 40 ++ .../api/bson_reader_t/bson_reader_reset.txt | 26 + .../bson_reader_set_destroy_func.txt | 27 + .../bson_reader_set_read_func.txt | 25 + .../api/bson_reader_t/bson_reader_tell.txt | 29 + source/libbson/api/bson_string_t.txt | 69 ++ .../api/bson_string_t/bson_string_append.txt | 26 + .../bson_string_t/bson_string_append_c.txt | 25 + .../bson_string_append_printf.txt | 26 + .../bson_string_append_unichar.txt | 26 + .../api/bson_string_t/bson_string_free.txt | 30 + .../api/bson_string_t/bson_string_new.txt | 30 + .../bson_string_t/bson_string_truncate.txt | 28 + source/libbson/api/bson_subtype_t.txt | 43 ++ source/libbson/api/bson_t.txt | 249 +++++++ .../libbson/api/bson_t/bson_append_array.txt | 44 ++ .../api/bson_t/bson_append_array_begin.txt | 51 ++ .../api/bson_t/bson_append_array_end.txt | 34 + .../libbson/api/bson_t/bson_append_binary.txt | 43 ++ .../libbson/api/bson_t/bson_append_bool.txt | 36 ++ .../libbson/api/bson_t/bson_append_code.txt | 39 ++ .../bson_t/bson_append_code_with_scope.txt | 44 ++ .../api/bson_t/bson_append_date_time.txt | 40 ++ .../api/bson_t/bson_append_dbpointer.txt | 42 ++ .../api/bson_t/bson_append_decimal128.txt | 39 ++ .../api/bson_t/bson_append_document.txt | 39 ++ .../api/bson_t/bson_append_document_begin.txt | 42 ++ .../api/bson_t/bson_append_document_end.txt | 30 + .../libbson/api/bson_t/bson_append_double.txt | 39 ++ .../libbson/api/bson_t/bson_append_int32.txt | 39 ++ .../libbson/api/bson_t/bson_append_int64.txt | 39 ++ .../libbson/api/bson_t/bson_append_iter.txt | 35 + .../libbson/api/bson_t/bson_append_maxkey.txt | 36 ++ .../libbson/api/bson_t/bson_append_minkey.txt | 36 ++ .../api/bson_t/bson_append_now_utc.txt | 34 + .../libbson/api/bson_t/bson_append_null.txt | 34 + source/libbson/api/bson_t/bson_append_oid.txt | 39 ++ .../libbson/api/bson_t/bson_append_regex.txt | 50 ++ .../api/bson_t/bson_append_regex_w_len.txt | 50 ++ .../libbson/api/bson_t/bson_append_symbol.txt | 44 ++ .../libbson/api/bson_t/bson_append_time_t.txt | 39 ++ .../api/bson_t/bson_append_timestamp.txt | 46 ++ .../api/bson_t/bson_append_timeval.txt | 39 ++ .../api/bson_t/bson_append_undefined.txt | 36 ++ .../libbson/api/bson_t/bson_append_utf8.txt | 53 ++ .../libbson/api/bson_t/bson_append_value.txt | 39 ++ .../bson_array_as_canonical_extended_json.txt | 70 ++ .../libbson/api/bson_t/bson_array_as_json.txt | 72 +++ .../bson_array_as_relaxed_extended_json.txt | 69 ++ .../bson_as_canonical_extended_json.txt | 49 ++ source/libbson/api/bson_t/bson_as_json.txt | 67 ++ .../api/bson_t/bson_as_json_with_opts.txt | 55 ++ .../bson_t/bson_as_relaxed_extended_json.txt | 49 ++ source/libbson/api/bson_t/bson_compare.txt | 38 ++ source/libbson/api/bson_t/bson_concat.txt | 31 + source/libbson/api/bson_t/bson_copy.txt | 32 + source/libbson/api/bson_t/bson_copy_to.txt | 28 + .../api/bson_t/bson_copy_to_excluding.txt | 43 ++ .../bson_t/bson_copy_to_excluding_noinit.txt | 70 ++ .../bson_copy_to_excluding_noinit_va.txt | 38 ++ source/libbson/api/bson_t/bson_count_keys.txt | 29 + source/libbson/api/bson_t/bson_destroy.txt | 28 + .../api/bson_t/bson_destroy_with_steal.txt | 40 ++ source/libbson/api/bson_t/bson_equal.txt | 30 + source/libbson/api/bson_t/bson_get_data.txt | 31 + source/libbson/api/bson_t/bson_has_field.txt | 30 + source/libbson/api/bson_t/bson_init.txt | 26 + .../api/bson_t/bson_init_from_json.txt | 62 ++ .../libbson/api/bson_t/bson_init_static.txt | 38 ++ .../libbson/api/bson_t/bson_json_mode_t.txt | 32 + .../api/bson_t/bson_json_opts_destroy.txt | 23 + .../libbson/api/bson_t/bson_json_opts_new.txt | 36 ++ .../bson_json_opts_set_outermost_array.txt | 26 + .../libbson/api/bson_t/bson_json_opts_t.txt | 57 ++ source/libbson/api/bson_t/bson_new.txt | 26 + .../api/bson_t/bson_new_from_buffer.txt | 43 ++ .../libbson/api/bson_t/bson_new_from_data.txt | 33 + .../libbson/api/bson_t/bson_new_from_json.txt | 48 ++ source/libbson/api/bson_t/bson_reinit.txt | 29 + .../api/bson_t/bson_reserve_buffer.txt | 116 ++++ source/libbson/api/bson_t/bson_sized_new.txt | 32 + source/libbson/api/bson_t/bson_steal.txt | 86 +++ source/libbson/api/bson_t/bson_validate.txt | 42 ++ .../api/bson_t/bson_validate_with_error.txt | 65 ++ source/libbson/api/bson_type_t.txt | 58 ++ source/libbson/api/bson_unichar_t.txt | 38 ++ source/libbson/api/bson_value_t.txt | 100 +++ .../api/bson_value_t/bson_value_copy.txt | 26 + .../api/bson_value_t/bson_value_destroy.txt | 23 + source/libbson/api/bson_visitor_t.txt | 231 +++++++ source/libbson/api/bson_writer_t.txt | 86 +++ .../api/bson_writer_t/bson_writer_begin.txt | 32 + .../api/bson_writer_t/bson_writer_destroy.txt | 25 + .../api/bson_writer_t/bson_writer_end.txt | 24 + .../bson_writer_t/bson_writer_get_length.txt | 33 + .../api/bson_writer_t/bson_writer_new.txt | 40 ++ .../bson_writer_t/bson_writer_rollback.txt | 26 + .../api/character_and_string_routines.txt | 54 ++ .../bson_ascii_strtoll.txt | 45 ++ .../bson_isspace.txt | 30 + .../bson_snprintf.txt | 33 + .../bson_strcasecmp.txt | 31 + .../character_string_routines/bson_strdup.txt | 29 + .../bson_strdup_printf.txt | 29 + .../bson_strdupv_printf.txt | 30 + .../bson_strfreev.txt | 24 + .../bson_strncpy.txt | 34 + .../bson_strndup.txt | 31 + .../bson_strnlen.txt | 30 + .../bson_uint32_to_string.txt | 59 ++ .../bson_utf8_escape_for_json.txt | 35 + .../bson_utf8_from_unichar.txt | 27 + .../bson_utf8_get_char.txt | 30 + .../bson_utf8_next_char.txt | 32 + .../bson_utf8_validate.txt | 32 + .../bson_vsnprintf.txt | 33 + source/libbson/api/version.txt | 60 ++ .../api/version/bson_check_version.txt | 31 + .../api/version/bson_get_major_version.txt | 24 + .../api/version/bson_get_micro_version.txt | 24 + .../api/version/bson_get_minor_version.txt | 24 + .../libbson/api/version/bson_get_version.txt | 25 + source/libmongoc.txt | 1 - source/libmongoc/api.txt | 97 +++ source/libmongoc/api/errors.txt | 329 ++++++++++ .../api/errors/mongoc_error_has_label.txt | 28 + source/libmongoc/api/gridfs.txt | 13 + source/libmongoc/api/init-cleanup.txt | 34 + .../api/init-cleanup/mongoc_cleanup.txt | 18 + .../api/init-cleanup/mongoc_init.txt | 18 + source/libmongoc/api/lifecycle.txt | 70 ++ source/libmongoc/api/logging.txt | 141 ++++ .../api/mongoc_auto_encryption_opts_t.txt | 53 ++ .../mongoc_auto_encryption_opts_destroy.txt | 27 + .../mongoc_auto_encryption_opts_new.txt | 44 ++ ...yption_opts_set_bypass_auto_encryption.txt | 30 + ...ryption_opts_set_bypass_query_analysis.txt | 34 + ...cryption_opts_set_encrypted_fields_map.txt | 36 ++ .../mongoc_auto_encryption_opts_set_extra.txt | 69 ++ ...to_encryption_opts_set_keyvault_client.txt | 36 ++ ...cryption_opts_set_keyvault_client_pool.txt | 36 ++ ...encryption_opts_set_keyvault_namespace.txt | 30 + ...s_set_kms_credential_provider_callback.txt | 31 + ...auto_encryption_opts_set_kms_providers.txt | 95 +++ ...oc_auto_encryption_opts_set_schema_map.txt | 66 ++ ...ngoc_auto_encryption_opts_set_tls_opts.txt | 60 ++ .../libmongoc/api/mongoc_bulk_operation_t.txt | 84 +++ .../mongoc_bulk_operation_delete.txt | 43 ++ .../mongoc_bulk_operation_delete_one.txt | 42 ++ .../mongoc_bulk_operation_destroy.txt | 21 + .../mongoc_bulk_operation_execute.txt | 56 ++ .../mongoc_bulk_operation_get_hint.txt | 32 + ...ongoc_bulk_operation_get_write_concern.txt | 29 + .../mongoc_bulk_operation_insert.txt | 35 + ...mongoc_bulk_operation_insert_with_opts.txt | 39 ++ .../mongoc_bulk_operation_remove.txt | 40 ++ ...c_bulk_operation_remove_many_with_opts.txt | 46 ++ .../mongoc_bulk_operation_remove_one.txt | 37 ++ ...oc_bulk_operation_remove_one_with_opts.txt | 46 ++ .../mongoc_bulk_operation_replace_one.txt | 43 ++ ...c_bulk_operation_replace_one_with_opts.txt | 52 ++ ...eration_set_bypass_document_validation.txt | 30 + ...ngoc_bulk_operation_set_client_session.txt | 31 + .../mongoc_bulk_operation_set_comment.txt | 29 + .../mongoc_bulk_operation_set_hint.txt | 34 + .../mongoc_bulk_operation_set_let.txt | 29 + .../mongoc_bulk_operation_update.txt | 45 ++ ...c_bulk_operation_update_many_with_opts.txt | 51 ++ .../mongoc_bulk_operation_update_one.txt | 42 ++ ...oc_bulk_operation_update_one_with_opts.txt | 52 ++ .../libmongoc/api/mongoc_change_stream_t.txt | 78 +++ .../mongoc_change_stream_destroy.txt | 20 + .../mongoc_change_stream_error_document.txt | 32 + .../mongoc_change_stream_get_resume_token.txt | 39 ++ .../mongoc_change_stream_next.txt | 42 ++ .../api/mongoc_client_encryption_t.txt | 88 +++ .../api/mongoc_client_encryption_t/.DS_Store | Bin 0 -> 14340 bytes ...goc_client_encryption_add_key_alt_name.txt | 40 ++ ...ongoc_client_encryption_create_datakey.txt | 50 ++ ...encryption_create_encrypted_collection.txt | 91 +++ ...client_encryption_datakey_opts_destroy.txt | 21 + ...goc_client_encryption_datakey_opts_new.txt | 19 + ...ncryption_datakey_opts_set_keyaltnames.txt | 31 + ...ncryption_datakey_opts_set_keymaterial.txt | 32 + ..._encryption_datakey_opts_set_masterkey.txt | 73 +++ ...ongoc_client_encryption_datakey_opts_t.txt | 38 ++ .../mongoc_client_encryption_decrypt.txt | 40 ++ .../mongoc_client_encryption_delete_key.txt | 37 ++ .../mongoc_client_encryption_destroy.txt | 22 + .../mongoc_client_encryption_encrypt.txt | 64 ++ ...c_client_encryption_encrypt_expression.txt | 76 +++ ...client_encryption_encrypt_opts_destroy.txt | 21 + ...goc_client_encryption_encrypt_opts_new.txt | 19 + ..._encryption_encrypt_opts_set_algorithm.txt | 45 ++ ...ion_encrypt_opts_set_contention_factor.txt | 26 + ...encryption_encrypt_opts_set_keyaltname.txt | 30 + ...ient_encryption_encrypt_opts_set_keyid.txt | 27 + ...encryption_encrypt_opts_set_query_type.txt | 30 + ...encryption_encrypt_opts_set_range_opts.txt | 33 + ...ongoc_client_encryption_encrypt_opts_t.txt | 45 ++ ..._encryption_encrypt_range_opts_destroy.txt | 29 + ...ient_encryption_encrypt_range_opts_new.txt | 29 + ..._encryption_encrypt_range_opts_set_max.txt | 40 ++ ..._encryption_encrypt_range_opts_set_min.txt | 40 ++ ...ption_encrypt_range_opts_set_precision.txt | 43 ++ ...yption_encrypt_range_opts_set_sparsity.txt | 35 + ...client_encryption_encrypt_range_opts_t.txt | 52 ++ ...nt_encryption_get_crypt_shared_version.txt | 38 ++ .../mongoc_client_encryption_get_key.txt | 36 ++ ..._client_encryption_get_key_by_alt_name.txt | 37 ++ .../mongoc_client_encryption_get_keys.txt | 32 + .../mongoc_client_encryption_new.txt | 35 + .../mongoc_client_encryption_opts_destroy.txt | 21 + .../mongoc_client_encryption_opts_new.txt | 18 + ...nt_encryption_opts_set_keyvault_client.txt | 33 + ...encryption_opts_set_keyvault_namespace.txt | 31 + ...s_set_kms_credential_provider_callback.txt | 64 ++ ...ient_encryption_opts_set_kms_providers.txt | 96 +++ ...oc_client_encryption_opts_set_tls_opts.txt | 60 ++ .../mongoc_client_encryption_opts_t.txt | 42 ++ ..._client_encryption_remove_key_alt_name.txt | 42 ++ ..._client_encryption_rewrap_many_datakey.txt | 52 ++ ...ion_rewrap_many_datakey_result_destroy.txt | 23 + ...y_datakey_result_get_bulk_write_result.txt | 34 + ...ryption_rewrap_many_datakey_result_new.txt | 20 + ...ncryption_rewrap_many_datakey_result_t.txt | 35 + source/libmongoc/api/mongoc_client_pool_t.txt | 64 ++ .../mongoc_client_pool_destroy.txt | 29 + ...goc_client_pool_enable_auto_encryption.txt | 55 ++ .../mongoc_client_pool_max_size.txt | 24 + .../mongoc_client_pool_min_size.txt | 37 ++ .../mongoc_client_pool_new.txt | 31 + .../mongoc_client_pool_new_with_error.txt | 31 + .../mongoc_client_pool_pop.txt | 35 + .../mongoc_client_pool_push.txt | 23 + .../mongoc_client_pool_set_apm_callbacks.txt | 40 ++ .../mongoc_client_pool_set_appname.txt | 31 + .../mongoc_client_pool_set_error_api.txt | 32 + .../mongoc_client_pool_set_server_api.txt | 31 + .../mongoc_client_pool_set_ssl_opts.txt | 44 ++ .../mongoc_client_pool_try_pop.txt | 29 + .../libmongoc/api/mongoc_client_session_t.txt | 70 ++ ...ongoc_client_session_abort_transaction.txt | 32 + ...oc_client_session_advance_cluster_time.txt | 29 + ..._client_session_advance_operation_time.txt | 32 + .../mongoc_client_session_append.txt | 41 ++ ...ngoc_client_session_commit_transaction.txt | 36 ++ .../mongoc_client_session_destroy.txt | 26 + .../mongoc_client_session_get_client.txt | 27 + ...mongoc_client_session_get_cluster_time.txt | 29 + .../mongoc_client_session_get_dirty.txt | 33 + .../mongoc_client_session_get_lsid.txt | 28 + ...ngoc_client_session_get_operation_time.txt | 28 + .../mongoc_client_session_get_opts.txt | 27 + .../mongoc_client_session_get_server_id.txt | 28 + ...c_client_session_get_transaction_state.txt | 25 + .../mongoc_client_session_in_transaction.txt | 25 + ...ongoc_client_session_start_transaction.txt | 52 ++ ...mongoc_client_session_with_transaction.txt | 59 ++ ...c_client_session_with_transaction_cb_t.txt | 41 ++ source/libmongoc/api/mongoc_client_t.txt | 143 +++++ .../mongoc_client_t/mongoc_client_command.txt | 59 ++ .../mongoc_client_command_simple.txt | 52 ++ ...c_client_command_simple_with_server_id.txt | 45 ++ .../mongoc_client_command_with_opts.txt | 64 ++ .../mongoc_client_t/mongoc_client_destroy.txt | 29 + .../mongoc_client_enable_auto_encryption.txt | 56 ++ ...mongoc_client_find_databases_with_opts.txt | 43 ++ .../mongoc_client_get_collection.txt | 38 ++ ...mongoc_client_get_crypt_shared_version.txt | 39 ++ .../mongoc_client_get_database.txt | 34 + .../mongoc_client_get_database_names.txt | 47 ++ ...oc_client_get_database_names_with_opts.txt | 65 ++ .../mongoc_client_get_default_database.txt | 53 ++ .../mongoc_client_get_gridfs.txt | 40 ++ ...ongoc_client_get_handshake_description.txt | 68 ++ .../mongoc_client_get_read_concern.txt | 27 + .../mongoc_client_get_read_prefs.txt | 27 + .../mongoc_client_get_server_description.txt | 29 + .../mongoc_client_get_server_descriptions.txt | 60 ++ .../mongoc_client_get_server_status.txt | 48 ++ .../mongoc_client_t/mongoc_client_get_uri.txt | 26 + .../mongoc_client_get_write_concern.txt | 27 + .../api/mongoc_client_t/mongoc_client_new.txt | 31 + .../mongoc_client_new_from_uri.txt | 32 + .../mongoc_client_new_from_uri_with_error.txt | 31 + .../mongoc_client_read_command_with_opts.txt | 67 ++ ...oc_client_read_write_command_with_opts.txt | 66 ++ .../mongoc_client_t/mongoc_client_reset.txt | 32 + .../mongoc_client_select_server.txt | 39 ++ .../mongoc_client_set_apm_callbacks.txt | 38 ++ .../mongoc_client_set_appname.txt | 37 ++ .../mongoc_client_set_error_api.txt | 29 + .../mongoc_client_set_read_concern.txt | 31 + .../mongoc_client_set_read_prefs.txt | 31 + .../mongoc_client_set_server_api.txt | 31 + .../mongoc_client_set_ssl_opts.txt | 43 ++ .../mongoc_client_set_stream_initiator.txt | 32 + .../mongoc_client_set_write_concern.txt | 32 + .../mongoc_client_start_session.txt | 41 ++ .../mongoc_client_t/mongoc_client_watch.txt | 53 ++ .../mongoc_client_write_command_with_opts.txt | 70 ++ .../mongoc_handshake_data_append.txt | 88 +++ source/libmongoc/api/mongoc_collection_t.txt | 142 ++++ .../mongoc_collection_aggregate.txt | 147 +++++ .../mongoc_collection_command.txt | 44 ++ .../mongoc_collection_command_simple.txt | 62 ++ .../mongoc_collection_command_with_opts.txt | 62 ++ .../mongoc_collection_copy.txt | 35 + .../mongoc_collection_count.txt | 97 +++ .../mongoc_collection_count_documents.txt | 111 ++++ .../mongoc_collection_count_with_opts.txt | 150 +++++ ...ongoc_collection_create_bulk_operation.txt | 71 ++ ...ection_create_bulk_operation_with_opts.txt | 56 ++ .../mongoc_collection_create_index.txt | 29 + ...ngoc_collection_create_index_with_opts.txt | 64 ++ ...oc_collection_create_indexes_with_opts.txt | 78 +++ .../mongoc_collection_delete.txt | 59 ++ .../mongoc_collection_delete_many.txt | 51 ++ .../mongoc_collection_delete_one.txt | 52 ++ .../mongoc_collection_destroy.txt | 30 + .../mongoc_collection_drop.txt | 26 + .../mongoc_collection_drop_index.txt | 29 + ...mongoc_collection_drop_index_with_opts.txt | 49 ++ .../mongoc_collection_drop_with_opts.txt | 82 +++ .../mongoc_collection_ensure_index.txt | 36 ++ ...oc_collection_estimated_document_count.txt | 100 +++ .../mongoc_collection_find.txt | 188 ++++++ .../mongoc_collection_find_and_modify.txt | 77 +++ ...c_collection_find_and_modify_with_opts.txt | 60 ++ .../mongoc_collection_find_indexes.txt | 50 ++ ...ngoc_collection_find_indexes_with_opts.txt | 52 ++ .../mongoc_collection_find_with_opts.txt | 263 ++++++++ .../mongoc_collection_get_last_error.txt | 33 + .../mongoc_collection_get_name.txt | 29 + .../mongoc_collection_get_read_concern.txt | 29 + .../mongoc_collection_get_read_prefs.txt | 30 + .../mongoc_collection_get_write_concern.txt | 30 + .../mongoc_collection_insert.txt | 52 ++ .../mongoc_collection_insert_bulk.txt | 56 ++ .../mongoc_collection_insert_many.txt | 62 ++ .../mongoc_collection_insert_one.txt | 59 ++ ...mongoc_collection_keys_to_index_string.txt | 36 ++ ...ngoc_collection_read_command_with_opts.txt | 62 ++ ...ollection_read_write_command_with_opts.txt | 66 ++ .../mongoc_collection_remove.txt | 50 ++ .../mongoc_collection_rename.txt | 33 + .../mongoc_collection_rename_with_opts.txt | 64 ++ .../mongoc_collection_replace_one.txt | 64 ++ .../mongoc_collection_save.txt | 53 ++ .../mongoc_collection_set_read_concern.txt | 29 + .../mongoc_collection_set_read_prefs.txt | 32 + .../mongoc_collection_set_write_concern.txt | 31 + .../mongoc_collection_stats.txt | 51 ++ .../mongoc_collection_update.txt | 53 ++ .../mongoc_collection_update_many.txt | 63 ++ .../mongoc_collection_update_one.txt | 71 ++ .../mongoc_collection_validate.txt | 54 ++ .../mongoc_collection_watch.txt | 54 ++ ...goc_collection_write_command_with_opts.txt | 67 ++ source/libmongoc/api/mongoc_cursor_t.txt | 90 +++ .../mongoc_cursor_t/mongoc_cursor_clone.txt | 37 ++ .../mongoc_cursor_t/mongoc_cursor_current.txt | 29 + .../mongoc_cursor_t/mongoc_cursor_destroy.txt | 25 + .../mongoc_cursor_t/mongoc_cursor_error.txt | 36 ++ .../mongoc_cursor_error_document.txt | 144 +++++ .../mongoc_cursor_get_batch_size.txt | 29 + .../mongoc_cursor_get_hint.txt | 30 + .../mongoc_cursor_get_host.txt | 25 + .../mongoc_cursor_t/mongoc_cursor_get_id.txt | 27 + .../mongoc_cursor_get_limit.txt | 24 + .../mongoc_cursor_get_max_await_time_ms.txt | 24 + .../mongoc_cursor_is_alive.txt | 32 + .../mongoc_cursor_t/mongoc_cursor_more.txt | 47 ++ .../mongoc_cursor_new_from_command_reply.txt | 77 +++ ...ursor_new_from_command_reply_with_opts.txt | 76 +++ .../mongoc_cursor_t/mongoc_cursor_next.txt | 42 ++ .../mongoc_cursor_set_batch_size.txt | 33 + .../mongoc_cursor_set_hint.txt | 38 ++ .../mongoc_cursor_set_limit.txt | 41 ++ .../mongoc_cursor_set_max_await_time_ms.txt | 42 ++ source/libmongoc/api/mongoc_database_t.txt | 115 ++++ .../mongoc_database_add_user.txt | 47 ++ .../mongoc_database_aggregate.txt | 119 ++++ .../mongoc_database_command.txt | 53 ++ .../mongoc_database_command_simple.txt | 48 ++ .../mongoc_database_command_with_opts.txt | 64 ++ .../mongoc_database_copy.txt | 32 + .../mongoc_database_create_collection.txt | 50 ++ .../mongoc_database_destroy.txt | 22 + .../mongoc_database_drop.txt | 25 + .../mongoc_database_drop_with_opts.txt | 47 ++ .../mongoc_database_find_collections.txt | 56 ++ ...oc_database_find_collections_with_opts.txt | 87 +++ .../mongoc_database_get_collection.txt | 23 + .../mongoc_database_get_collection_names.txt | 47 ++ ...atabase_get_collection_names_with_opts.txt | 76 +++ .../mongoc_database_get_name.txt | 26 + .../mongoc_database_get_read_concern.txt | 27 + .../mongoc_database_get_read_prefs.txt | 26 + .../mongoc_database_get_write_concern.txt | 27 + .../mongoc_database_has_collection.txt | 38 ++ ...mongoc_database_read_command_with_opts.txt | 62 ++ ..._database_read_write_command_with_opts.txt | 66 ++ .../mongoc_database_remove_all_users.txt | 35 + .../mongoc_database_remove_user.txt | 37 ++ .../mongoc_database_set_read_concern.txt | 28 + .../mongoc_database_set_read_prefs.txt | 31 + .../mongoc_database_set_write_concern.txt | 29 + .../mongoc_database_watch.txt | 54 ++ ...ongoc_database_write_command_with_opts.txt | 71 ++ .../libmongoc/api/mongoc_delete_flags_t.txt | 23 + .../api/mongoc_find_and_modify_opts_t.txt | 198 ++++++ .../mongoc_find_and_modify_opts_append.txt | 46 ++ .../mongoc_find_and_modify_opts_destroy.txt | 26 + ...fy_opts_get_bypass_document_validation.txt | 26 + ...mongoc_find_and_modify_opts_get_fields.txt | 27 + .../mongoc_find_and_modify_opts_get_flags.txt | 25 + ...c_find_and_modify_opts_get_max_time_ms.txt | 25 + .../mongoc_find_and_modify_opts_get_sort.txt | 27 + ...mongoc_find_and_modify_opts_get_update.txt | 27 + .../mongoc_find_and_modify_opts_new.txt | 20 + ...fy_opts_set_bypass_document_validation.txt | 64 ++ ...mongoc_find_and_modify_opts_set_fields.txt | 55 ++ .../mongoc_find_and_modify_opts_set_flags.txt | 81 +++ ...c_find_and_modify_opts_set_max_time_ms.txt | 45 ++ .../mongoc_find_and_modify_opts_set_sort.txt | 62 ++ ...mongoc_find_and_modify_opts_set_update.txt | 61 ++ source/libmongoc/api/mongoc_gridfs_t.txt | 117 ++++ .../mongoc_gridfs_bucket_abort_upload.txt | 36 ++ .../mongoc_gridfs_bucket_delete_by_id.txt | 31 + .../mongoc_gridfs_bucket_destroy.txt | 23 + ...ongoc_gridfs_bucket_download_to_stream.txt | 46 ++ .../mongoc_gridfs_bucket_find.txt | 34 + .../mongoc_gridfs_bucket_new.txt | 38 ++ ...goc_gridfs_bucket_open_download_stream.txt | 39 ++ ...ongoc_gridfs_bucket_open_upload_stream.txt | 49 ++ ...idfs_bucket_open_upload_stream_with_id.txt | 49 ++ .../mongoc_gridfs_bucket_stream_error.txt | 40 ++ .../mongoc_gridfs_bucket_t.txt | 80 +++ ...ongoc_gridfs_bucket_upload_from_stream.txt | 51 ++ ...idfs_bucket_upload_from_stream_with_id.txt | 51 ++ .../mongoc_gridfs_create_file.txt | 35 + .../mongoc_gridfs_create_file_from_stream.txt | 37 ++ .../mongoc_gridfs_t/mongoc_gridfs_destroy.txt | 24 + .../mongoc_gridfs_t/mongoc_gridfs_drop.txt | 36 ++ .../mongoc_gridfs_file_destroy.txt | 24 + .../mongoc_gridfs_file_error.txt | 35 + .../mongoc_gridfs_file_get_aliases.txt | 29 + .../mongoc_gridfs_file_get_chunk_size.txt | 29 + .../mongoc_gridfs_file_get_content_type.txt | 29 + .../mongoc_gridfs_file_get_filename.txt | 29 + .../mongoc_gridfs_file_get_id.txt | 32 + .../mongoc_gridfs_file_get_length.txt | 29 + .../mongoc_gridfs_file_get_md5.txt | 29 + .../mongoc_gridfs_file_get_metadata.txt | 29 + .../mongoc_gridfs_file_get_upload_date.txt | 29 + .../mongoc_gridfs_file_list_destroy.txt | 24 + .../mongoc_gridfs_file_list_error.txt | 36 ++ .../mongoc_gridfs_file_list_next.txt | 32 + .../mongoc_gridfs_file_list_t.txt | 56 ++ .../mongoc_gridfs_file_opt_t.txt | 26 + .../mongoc_gridfs_file_readv.txt | 41 ++ .../mongoc_gridfs_file_remove.txt | 36 ++ .../mongoc_gridfs_file_save.txt | 34 + .../mongoc_gridfs_file_seek.txt | 63 ++ .../mongoc_gridfs_file_set_aliases.txt | 27 + .../mongoc_gridfs_file_set_content_type.txt | 28 + .../mongoc_gridfs_file_set_filename.txt | 28 + .../mongoc_gridfs_file_set_id.txt | 34 + .../mongoc_gridfs_file_set_md5.txt | 27 + .../mongoc_gridfs_file_set_metadata.txt | 28 + .../mongoc_gridfs_t/mongoc_gridfs_file_t.txt | 92 +++ .../mongoc_gridfs_file_tell.txt | 29 + .../mongoc_gridfs_file_writev.txt | 40 ++ .../mongoc_gridfs_t/mongoc_gridfs_find.txt | 40 ++ .../mongoc_gridfs_find_one.txt | 49 ++ .../mongoc_gridfs_find_one_by_filename.txt | 43 ++ .../mongoc_gridfs_find_one_with_opts.txt | 49 ++ .../mongoc_gridfs_find_with_opts.txt | 39 ++ .../mongoc_gridfs_get_chunks.txt | 30 + .../mongoc_gridfs_get_files.txt | 30 + .../mongoc_gridfs_remove_by_filename.txt | 38 ++ .../mongoc_stream_gridfs_new.txt | 35 + .../mongoc_handshake_data_append.textClipping | Bin 0 -> 279 bytes source/libmongoc/api/mongoc_host_list_t.txt | 30 + source/libmongoc/api/mongoc_index_opt_t.txt | 102 +++ .../mongoc_index_opt_geo_get_default.txt | 19 + .../mongoc_index_opt_geo_init.txt | 24 + .../mongoc_index_opt_geo_t.txt | 46 ++ .../mongoc_index_opt_get_default.txt | 19 + .../mongoc_index_opt_init.txt | 25 + .../mongoc_index_opt_wt_get_default.txt | 19 + .../mongoc_index_opt_wt_init.txt | 24 + .../mongoc_index_opt_wt_t.txt | 43 ++ .../libmongoc/api/mongoc_insert_flags_t.txt | 43 ++ source/libmongoc/api/mongoc_iovec_t.txt | 31 + source/libmongoc/api/mongoc_optional_t.txt | 33 + .../mongoc_optional_copy.txt | 21 + .../mongoc_optional_init.txt | 20 + .../mongoc_optional_is_set.txt | 25 + .../mongoc_optional_set_value.txt | 21 + .../mongoc_optional_value.txt | 25 + source/libmongoc/api/mongoc_query_flags_t.txt | 63 ++ source/libmongoc/api/mongoc_rand.txt | 62 ++ .../api/mongoc_rand/mongoc_rand_add.txt | 26 + .../api/mongoc_rand/mongoc_rand_seed.txt | 25 + .../api/mongoc_rand/mongoc_rand_status.txt | 24 + .../libmongoc/api/mongoc_read_concern_t.txt | 86 +++ .../mongoc_read_concern_append.txt | 35 + .../mongoc_read_concern_copy.txt | 30 + .../mongoc_read_concern_destroy.txt | 23 + .../mongoc_read_concern_get_level.txt | 28 + .../mongoc_read_concern_is_default.txt | 26 + .../mongoc_read_concern_new.txt | 20 + .../mongoc_read_concern_set_level.txt | 34 + source/libmongoc/api/mongoc_read_mode_t.txt | 28 + source/libmongoc/api/mongoc_read_prefs_t.txt | 128 ++++ .../mongoc_read_prefs_add_tag.txt | 25 + .../mongoc_read_prefs_copy.txt | 30 + .../mongoc_read_prefs_destroy.txt | 22 + .../mongoc_read_prefs_get_hedge.txt | 28 + ...c_read_prefs_get_max_staleness_seconds.txt | 24 + .../mongoc_read_prefs_get_mode.txt | 28 + .../mongoc_read_prefs_get_tags.txt | 28 + .../mongoc_read_prefs_is_valid.txt | 30 + .../mongoc_read_prefs_new.txt | 30 + .../mongoc_read_prefs_set_hedge.txt | 34 + ...c_read_prefs_set_max_staleness_seconds.txt | 25 + .../mongoc_read_prefs_set_mode.txt | 25 + .../mongoc_read_prefs_set_tags.txt | 94 +++ .../libmongoc/api/mongoc_remove_flags_t.txt | 30 + source/libmongoc/api/mongoc_reply_flags_t.txt | 34 + source/libmongoc/api/mongoc_server_api_t.txt | 50 ++ .../mongoc_server_api_copy.txt | 26 + .../mongoc_server_api_deprecation_errors.txt | 21 + .../mongoc_server_api_destroy.txt | 14 + ...ngoc_server_api_get_deprecation_errors.txt | 24 + .../mongoc_server_api_get_strict.txt | 24 + .../mongoc_server_api_get_version.txt | 24 + .../mongoc_server_api_new.txt | 20 + .../mongoc_server_api_strict.txt | 20 + .../mongoc_server_api_version_from_string.txt | 26 + .../mongoc_server_api_version_t.txt | 34 + .../mongoc_server_api_version_to_string.txt | 24 + .../api/mongoc_server_description_t.txt | 60 ++ .../api/mongoc_server_description_t/.DS_Store | Bin 0 -> 6148 bytes .../mongoc_server_description_destroy.txt | 22 + ...ngoc_server_description_hello_response.txt | 35 + .../mongoc_server_description_host.txt | 28 + .../mongoc_server_description_id.txt | 23 + .../mongoc_server_description_ismaster.txt | 38 ++ ...oc_server_description_last_update_time.txt | 27 + .../mongoc_server_description_new_copy.txt | 30 + ...goc_server_description_round_trip_time.txt | 24 + .../mongoc_server_description_type.txt | 34 + ...mongoc_server_descriptions_destroy_all.txt | 22 + source/libmongoc/api/mongoc_session_opt_t.txt | 47 ++ .../mongoc_session_opts_clone.txt | 28 + .../mongoc_session_opts_destroy.txt | 27 + ...oc_session_opts_get_causal_consistency.txt | 22 + ...sion_opts_get_default_transaction_opts.txt | 27 + .../mongoc_session_opts_get_snapshot.txt | 22 + ...ngoc_session_opts_get_transaction_opts.txt | 31 + .../mongoc_session_opts_new.txt | 24 + ...oc_session_opts_set_causal_consistency.txt | 76 +++ ...sion_opts_set_default_transaction_opts.txt | 32 + .../mongoc_session_opts_set_snapshot.txt | 68 ++ source/libmongoc/api/mongoc_socket_t.txt | 59 ++ .../mongoc_socket_t/mongoc_socket_accept.txt | 32 + .../mongoc_socket_t/mongoc_socket_bind.txt | 32 + .../mongoc_socket_t/mongoc_socket_close.txt | 29 + .../mongoc_socket_t/mongoc_socket_connect.txt | 37 ++ .../mongoc_socket_t/mongoc_socket_destroy.txt | 22 + .../mongoc_socket_t/mongoc_socket_errno.txt | 28 + .../mongoc_socket_getnameinfo.txt | 29 + .../mongoc_socket_getsockname.txt | 32 + .../mongoc_socket_t/mongoc_socket_listen.txt | 30 + .../api/mongoc_socket_t/mongoc_socket_new.txt | 34 + .../mongoc_socket_t/mongoc_socket_recv.txt | 38 ++ .../mongoc_socket_t/mongoc_socket_send.txt | 36 ++ .../mongoc_socket_t/mongoc_socket_sendv.txt | 35 + .../mongoc_socket_setsockopt.txt | 37 ++ .../api/mongoc_ssl_opt_get_default.txt | 19 + source/libmongoc/api/mongoc_ssl_opt_t.txt | 55 ++ source/libmongoc/api/mongoc_stream_t.txt | 80 +++ .../mongoc_stream_buffered_new.txt | 31 + .../mongoc_stream_buffered_t.txt | 24 + .../mongoc_stream_t/mongoc_stream_close.txt | 29 + .../mongoc_stream_t/mongoc_stream_cork.txt | 35 + .../mongoc_stream_t/mongoc_stream_destroy.txt | 19 + .../mongoc_stream_file_get_fd.txt | 29 + .../mongoc_stream_file_new.txt | 29 + .../mongoc_stream_file_new_for_path.txt | 32 + .../mongoc_stream_t/mongoc_stream_file_t.txt | 30 + .../mongoc_stream_t/mongoc_stream_flush.txt | 28 + .../mongoc_stream_get_base_stream.txt | 25 + .../mongoc_stream_t/mongoc_stream_read.txt | 49 ++ .../mongoc_stream_t/mongoc_stream_readv.txt | 49 ++ .../mongoc_stream_setsockopt.txt | 33 + .../mongoc_stream_should_retry.txt | 22 + .../mongoc_stream_socket_get_socket.txt | 25 + .../mongoc_stream_socket_new.txt | 32 + .../mongoc_stream_socket_t.txt | 28 + .../mongoc_stream_timed_out.txt | 22 + .../mongoc_stream_t/mongoc_stream_tls_t.txt | 14 + .../mongoc_stream_t/mongoc_stream_uncork.txt | 35 + .../mongoc_stream_t/mongoc_stream_write.txt | 48 ++ .../mongoc_stream_t/mongoc_stream_writev.txt | 41 ++ .../api/mongoc_topology_description_t.txt | 43 ++ .../mongoc_topology_description_destroy.txt | 22 + ...ongoc_topology_description_get_servers.txt | 28 + ...pology_description_has_readable_server.txt | 36 ++ ...pology_description_has_writable_server.txt | 34 + .../mongoc_topology_description_new_copy.txt | 31 + .../mongoc_topology_description_type.txt | 30 + .../api/mongoc_transaction_opt_t.txt | 67 ++ .../mongoc_transaction_opts_clone.txt | 28 + .../mongoc_transaction_opts_destroy.txt | 22 + ...ransaction_opts_get_max_commit_time_ms.txt | 22 + ...ngoc_transaction_opts_get_read_concern.txt | 27 + ...mongoc_transaction_opts_get_read_prefs.txt | 27 + ...goc_transaction_opts_get_write_concern.txt | 27 + .../mongoc_transaction_opts_new.txt | 22 + ...ransaction_opts_set_max_commit_time_ms.txt | 24 + ...ngoc_transaction_opts_set_read_concern.txt | 24 + ...mongoc_transaction_opts_set_read_prefs.txt | 24 + ...goc_transaction_opts_set_write_concern.txt | 24 + .../api/mongoc_transaction_state_t.txt | 34 + .../libmongoc/api/mongoc_update_flags_t.txt | 36 ++ source/libmongoc/api/mongoc_uri_t.txt | 605 ++++++++++++++++++ .../api/mongoc_uri_t/mongoc_uri_copy.txt | 30 + .../api/mongoc_uri_t/mongoc_uri_destroy.txt | 23 + .../mongoc_uri_get_auth_mechanism.txt | 30 + .../mongoc_uri_get_auth_source.txt | 30 + .../mongoc_uri_get_compressors.txt | 42 ++ .../mongoc_uri_t/mongoc_uri_get_database.txt | 28 + .../api/mongoc_uri_t/mongoc_uri_get_hosts.txt | 27 + .../mongoc_uri_get_mechanism_properties.txt | 59 ++ .../mongoc_uri_get_option_as_bool.txt | 27 + .../mongoc_uri_get_option_as_int32.txt | 44 ++ .../mongoc_uri_get_option_as_int64.txt | 41 ++ .../mongoc_uri_get_option_as_utf8.txt | 27 + .../mongoc_uri_t/mongoc_uri_get_options.txt | 28 + .../mongoc_uri_t/mongoc_uri_get_password.txt | 28 + .../mongoc_uri_get_read_concern.txt | 28 + .../mongoc_uri_get_read_prefs.txt | 37 ++ .../mongoc_uri_get_read_prefs_t.txt | 28 + .../mongoc_uri_get_replica_set.txt | 28 + .../mongoc_uri_t/mongoc_uri_get_service.txt | 32 + .../mongoc_uri_get_srv_hostname.txt | 27 + .../mongoc_uri_get_srv_service_name.txt | 27 + .../api/mongoc_uri_t/mongoc_uri_get_ssl.txt | 39 ++ .../mongoc_uri_t/mongoc_uri_get_string.txt | 28 + .../api/mongoc_uri_t/mongoc_uri_get_tls.txt | 30 + .../mongoc_uri_t/mongoc_uri_get_username.txt | 28 + .../mongoc_uri_get_write_concern.txt | 28 + .../mongoc_uri_t/mongoc_uri_has_option.txt | 24 + .../api/mongoc_uri_t/mongoc_uri_new.txt | 33 + .../mongoc_uri_new_for_host_port.txt | 31 + .../mongoc_uri_new_with_error.txt | 58 ++ .../mongoc_uri_option_is_bool.txt | 23 + .../mongoc_uri_option_is_int32.txt | 30 + .../mongoc_uri_option_is_int64.txt | 30 + .../mongoc_uri_option_is_utf8.txt | 23 + .../mongoc_uri_set_auth_mechanism.txt | 33 + .../mongoc_uri_set_auth_source.txt | 33 + .../mongoc_uri_set_compressors.txt | 47 ++ .../mongoc_uri_t/mongoc_uri_set_database.txt | 31 + .../mongoc_uri_set_mechanism_properties.txt | 53 ++ .../mongoc_uri_set_option_as_bool.txt | 36 ++ .../mongoc_uri_set_option_as_int32.txt | 42 ++ .../mongoc_uri_set_option_as_int64.txt | 45 ++ .../mongoc_uri_set_option_as_utf8.txt | 36 ++ .../mongoc_uri_t/mongoc_uri_set_password.txt | 30 + .../mongoc_uri_set_read_concern.txt | 25 + .../mongoc_uri_set_read_prefs_t.txt | 25 + .../mongoc_uri_t/mongoc_uri_set_username.txt | 29 + .../mongoc_uri_set_write_concern.txt | 25 + .../api/mongoc_uri_t/mongoc_uri_unescape.txt | 30 + source/libmongoc/api/mongoc_version.txt | 55 ++ .../mongoc_version/mongoc_check_version.txt | 28 + .../mongoc_get_major_version.txt | 18 + .../mongoc_get_micro_version.txt | 18 + .../mongoc_get_minor_version.txt | 18 + .../api/mongoc_version/mongoc_get_version.txt | 18 + .../libmongoc/api/mongoc_write_concern_t.txt | 109 ++++ .../mongoc_write_concern_append.txt | 36 ++ .../mongoc_write_concern_copy.txt | 31 + .../mongoc_write_concern_destroy.txt | 24 + .../mongoc_write_concern_get_fsync.txt | 35 + .../mongoc_write_concern_get_journal.txt | 29 + .../mongoc_write_concern_get_w.txt | 29 + .../mongoc_write_concern_get_wmajority.txt | 30 + .../mongoc_write_concern_get_wtag.txt | 28 + .../mongoc_write_concern_get_wtimeout.txt | 35 + ...ongoc_write_concern_get_wtimeout_int64.txt | 34 + .../mongoc_write_concern_is_acknowledged.txt | 27 + .../mongoc_write_concern_is_default.txt | 25 + .../mongoc_write_concern_is_valid.txt | 24 + .../mongoc_write_concern_journal_is_set.txt | 25 + .../mongoc_write_concern_new.txt | 20 + .../mongoc_write_concern_set_fsync.txt | 36 ++ .../mongoc_write_concern_set_journal.txt | 30 + .../mongoc_write_concern_set_w.txt | 30 + .../mongoc_write_concern_set_wmajority.txt | 32 + .../mongoc_write_concern_set_wtag.txt | 30 + .../mongoc_write_concern_set_wtimeout.txt | 34 + ...ongoc_write_concern_set_wtimeout_int64.txt | 35 + 820 files changed, 34478 insertions(+), 2 deletions(-) create mode 100644 source/libbson/api.txt create mode 100644 source/libbson/api/bson_array_builder_t.txt create mode 100644 source/libbson/api/bson_context_t.txt create mode 100644 source/libbson/api/bson_context_t/bson_context_destroy.txt create mode 100644 source/libbson/api/bson_context_t/bson_context_get_default.txt create mode 100644 source/libbson/api/bson_context_t/bson_context_new.txt create mode 100644 source/libbson/api/bson_decimal128_t.txt create mode 100644 source/libbson/api/bson_decimal128_t/bson_decimal128_from_string.txt create mode 100644 source/libbson/api/bson_decimal128_t/bson_decimal128_from_string_w_len.txt create mode 100644 source/libbson/api/bson_decimal128_t/bson_decimal128_to_string.txt create mode 100644 source/libbson/api/bson_error_t.txt create mode 100644 source/libbson/api/bson_error_t/bson_set_error.txt create mode 100644 source/libbson/api/bson_error_t/bson_strerror_r.txt create mode 100644 source/libbson/api/bson_get_monotonic_time.txt create mode 100644 source/libbson/api/bson_iter_t.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_array.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_as_bool.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_as_double.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_as_int64.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_binary.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_bool.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_code.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_codewscope.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_date_time.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_dbpointer.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_decimal128.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_document.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_double.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_dup_utf8.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_find.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_find_case.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_find_descendant.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_find_w_len.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init_find.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init_find_case.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init_find_w_len.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init_from_data.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_init_from_data_at_offset.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_int32.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_int64.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_key.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_key_len.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_next.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_offset.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_oid.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_bool.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_date_time.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_decimal128.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_double.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_int32.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_int64.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_oid.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_overwrite_timestamp.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_recurse.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_regex.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_symbol.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_time_t.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_timestamp.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_timeval.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_type.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_utf8.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_value.txt create mode 100644 source/libbson/api/bson_iter_t/bson_iter_visit_all.txt create mode 100644 source/libbson/api/bson_json_reader_t.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_data_reader_ingest.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_data_reader_new.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_reader_destroy.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_reader_new.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_fd.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_reader_new_from_file.txt create mode 100644 source/libbson/api/bson_json_reader_t/bson_json_reader_read.txt create mode 100644 source/libbson/api/bson_memory.txt create mode 100644 source/libbson/api/bson_memory/bson_aligned_alloc.txt create mode 100644 source/libbson/api/bson_memory/bson_aligned_alloc0.txt create mode 100644 source/libbson/api/bson_memory/bson_free.txt create mode 100644 source/libbson/api/bson_memory/bson_malloc.txt create mode 100644 source/libbson/api/bson_memory/bson_malloc0.txt create mode 100644 source/libbson/api/bson_memory/bson_mem_restore_vtable.txt create mode 100644 source/libbson/api/bson_memory/bson_mem_set_vtable.txt create mode 100644 source/libbson/api/bson_memory/bson_realloc.txt create mode 100644 source/libbson/api/bson_memory/bson_realloc_ctx.txt create mode 100644 source/libbson/api/bson_memory/bson_realloc_func.txt create mode 100644 source/libbson/api/bson_memory/bson_zero_free.txt create mode 100644 source/libbson/api/bson_oid_t.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_compare.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_compare_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_copy.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_copy_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_equal.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_equal_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_get_time_t.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_get_time_t_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_hash.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_hash_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_init.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_init_from_data.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_init_from_string.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_init_from_string_unsafe.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_init_sequence.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_is_valid.txt create mode 100644 source/libbson/api/bson_oid_t/bson_oid_to_string.txt create mode 100644 source/libbson/api/bson_reader_t.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_destroy.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_destroy_func_t.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_new_from_data.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_new_from_fd.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_new_from_file.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_new_from_handle.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_read.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_read_func_t.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_reset.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_set_destroy_func.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_set_read_func.txt create mode 100644 source/libbson/api/bson_reader_t/bson_reader_tell.txt create mode 100644 source/libbson/api/bson_string_t.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_append.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_append_c.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_append_printf.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_append_unichar.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_free.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_new.txt create mode 100644 source/libbson/api/bson_string_t/bson_string_truncate.txt create mode 100644 source/libbson/api/bson_subtype_t.txt create mode 100644 source/libbson/api/bson_t.txt create mode 100644 source/libbson/api/bson_t/bson_append_array.txt create mode 100644 source/libbson/api/bson_t/bson_append_array_begin.txt create mode 100644 source/libbson/api/bson_t/bson_append_array_end.txt create mode 100644 source/libbson/api/bson_t/bson_append_binary.txt create mode 100644 source/libbson/api/bson_t/bson_append_bool.txt create mode 100644 source/libbson/api/bson_t/bson_append_code.txt create mode 100644 source/libbson/api/bson_t/bson_append_code_with_scope.txt create mode 100644 source/libbson/api/bson_t/bson_append_date_time.txt create mode 100644 source/libbson/api/bson_t/bson_append_dbpointer.txt create mode 100644 source/libbson/api/bson_t/bson_append_decimal128.txt create mode 100644 source/libbson/api/bson_t/bson_append_document.txt create mode 100644 source/libbson/api/bson_t/bson_append_document_begin.txt create mode 100644 source/libbson/api/bson_t/bson_append_document_end.txt create mode 100644 source/libbson/api/bson_t/bson_append_double.txt create mode 100644 source/libbson/api/bson_t/bson_append_int32.txt create mode 100644 source/libbson/api/bson_t/bson_append_int64.txt create mode 100644 source/libbson/api/bson_t/bson_append_iter.txt create mode 100644 source/libbson/api/bson_t/bson_append_maxkey.txt create mode 100644 source/libbson/api/bson_t/bson_append_minkey.txt create mode 100644 source/libbson/api/bson_t/bson_append_now_utc.txt create mode 100644 source/libbson/api/bson_t/bson_append_null.txt create mode 100644 source/libbson/api/bson_t/bson_append_oid.txt create mode 100644 source/libbson/api/bson_t/bson_append_regex.txt create mode 100644 source/libbson/api/bson_t/bson_append_regex_w_len.txt create mode 100644 source/libbson/api/bson_t/bson_append_symbol.txt create mode 100644 source/libbson/api/bson_t/bson_append_time_t.txt create mode 100644 source/libbson/api/bson_t/bson_append_timestamp.txt create mode 100644 source/libbson/api/bson_t/bson_append_timeval.txt create mode 100644 source/libbson/api/bson_t/bson_append_undefined.txt create mode 100644 source/libbson/api/bson_t/bson_append_utf8.txt create mode 100644 source/libbson/api/bson_t/bson_append_value.txt create mode 100644 source/libbson/api/bson_t/bson_array_as_canonical_extended_json.txt create mode 100644 source/libbson/api/bson_t/bson_array_as_json.txt create mode 100644 source/libbson/api/bson_t/bson_array_as_relaxed_extended_json.txt create mode 100644 source/libbson/api/bson_t/bson_as_canonical_extended_json.txt create mode 100644 source/libbson/api/bson_t/bson_as_json.txt create mode 100644 source/libbson/api/bson_t/bson_as_json_with_opts.txt create mode 100644 source/libbson/api/bson_t/bson_as_relaxed_extended_json.txt create mode 100644 source/libbson/api/bson_t/bson_compare.txt create mode 100644 source/libbson/api/bson_t/bson_concat.txt create mode 100644 source/libbson/api/bson_t/bson_copy.txt create mode 100644 source/libbson/api/bson_t/bson_copy_to.txt create mode 100644 source/libbson/api/bson_t/bson_copy_to_excluding.txt create mode 100644 source/libbson/api/bson_t/bson_copy_to_excluding_noinit.txt create mode 100644 source/libbson/api/bson_t/bson_copy_to_excluding_noinit_va.txt create mode 100644 source/libbson/api/bson_t/bson_count_keys.txt create mode 100644 source/libbson/api/bson_t/bson_destroy.txt create mode 100644 source/libbson/api/bson_t/bson_destroy_with_steal.txt create mode 100644 source/libbson/api/bson_t/bson_equal.txt create mode 100644 source/libbson/api/bson_t/bson_get_data.txt create mode 100644 source/libbson/api/bson_t/bson_has_field.txt create mode 100644 source/libbson/api/bson_t/bson_init.txt create mode 100644 source/libbson/api/bson_t/bson_init_from_json.txt create mode 100644 source/libbson/api/bson_t/bson_init_static.txt create mode 100644 source/libbson/api/bson_t/bson_json_mode_t.txt create mode 100644 source/libbson/api/bson_t/bson_json_opts_destroy.txt create mode 100644 source/libbson/api/bson_t/bson_json_opts_new.txt create mode 100644 source/libbson/api/bson_t/bson_json_opts_set_outermost_array.txt create mode 100644 source/libbson/api/bson_t/bson_json_opts_t.txt create mode 100644 source/libbson/api/bson_t/bson_new.txt create mode 100644 source/libbson/api/bson_t/bson_new_from_buffer.txt create mode 100644 source/libbson/api/bson_t/bson_new_from_data.txt create mode 100644 source/libbson/api/bson_t/bson_new_from_json.txt create mode 100644 source/libbson/api/bson_t/bson_reinit.txt create mode 100644 source/libbson/api/bson_t/bson_reserve_buffer.txt create mode 100644 source/libbson/api/bson_t/bson_sized_new.txt create mode 100644 source/libbson/api/bson_t/bson_steal.txt create mode 100644 source/libbson/api/bson_t/bson_validate.txt create mode 100644 source/libbson/api/bson_t/bson_validate_with_error.txt create mode 100644 source/libbson/api/bson_type_t.txt create mode 100644 source/libbson/api/bson_unichar_t.txt create mode 100644 source/libbson/api/bson_value_t.txt create mode 100644 source/libbson/api/bson_value_t/bson_value_copy.txt create mode 100644 source/libbson/api/bson_value_t/bson_value_destroy.txt create mode 100644 source/libbson/api/bson_visitor_t.txt create mode 100644 source/libbson/api/bson_writer_t.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_begin.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_destroy.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_end.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_get_length.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_new.txt create mode 100644 source/libbson/api/bson_writer_t/bson_writer_rollback.txt create mode 100644 source/libbson/api/character_and_string_routines.txt create mode 100644 source/libbson/api/character_string_routines/bson_ascii_strtoll.txt create mode 100644 source/libbson/api/character_string_routines/bson_isspace.txt create mode 100644 source/libbson/api/character_string_routines/bson_snprintf.txt create mode 100644 source/libbson/api/character_string_routines/bson_strcasecmp.txt create mode 100644 source/libbson/api/character_string_routines/bson_strdup.txt create mode 100644 source/libbson/api/character_string_routines/bson_strdup_printf.txt create mode 100644 source/libbson/api/character_string_routines/bson_strdupv_printf.txt create mode 100644 source/libbson/api/character_string_routines/bson_strfreev.txt create mode 100644 source/libbson/api/character_string_routines/bson_strncpy.txt create mode 100644 source/libbson/api/character_string_routines/bson_strndup.txt create mode 100644 source/libbson/api/character_string_routines/bson_strnlen.txt create mode 100644 source/libbson/api/character_string_routines/bson_uint32_to_string.txt create mode 100644 source/libbson/api/character_string_routines/bson_utf8_escape_for_json.txt create mode 100644 source/libbson/api/character_string_routines/bson_utf8_from_unichar.txt create mode 100644 source/libbson/api/character_string_routines/bson_utf8_get_char.txt create mode 100644 source/libbson/api/character_string_routines/bson_utf8_next_char.txt create mode 100644 source/libbson/api/character_string_routines/bson_utf8_validate.txt create mode 100644 source/libbson/api/character_string_routines/bson_vsnprintf.txt create mode 100644 source/libbson/api/version.txt create mode 100644 source/libbson/api/version/bson_check_version.txt create mode 100644 source/libbson/api/version/bson_get_major_version.txt create mode 100644 source/libbson/api/version/bson_get_micro_version.txt create mode 100644 source/libbson/api/version/bson_get_minor_version.txt create mode 100644 source/libbson/api/version/bson_get_version.txt create mode 100644 source/libmongoc/api.txt create mode 100644 source/libmongoc/api/errors.txt create mode 100644 source/libmongoc/api/errors/mongoc_error_has_label.txt create mode 100644 source/libmongoc/api/gridfs.txt create mode 100644 source/libmongoc/api/init-cleanup.txt create mode 100644 source/libmongoc/api/init-cleanup/mongoc_cleanup.txt create mode 100644 source/libmongoc/api/init-cleanup/mongoc_init.txt create mode 100644 source/libmongoc/api/lifecycle.txt create mode 100644 source/libmongoc/api/logging.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_auto_encryption.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_bypass_query_analysis.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_encrypted_fields_map.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_extra.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_client_pool.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_keyvault_namespace.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_credential_provider_callback.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_kms_providers.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_schema_map.txt create mode 100644 source/libmongoc/api/mongoc_auto_encryption_opts_t/mongoc_auto_encryption_opts_set_tls_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_delete_one.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_destroy.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_execute.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_hint.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_insert_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_many_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_remove_one_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_replace_one_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_bypass_document_validation.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_client_session.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_comment.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_hint.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_set_let.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_many_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one.txt create mode 100644 source/libmongoc/api/mongoc_bulk_operation_t/mongoc_bulk_operation_update_one_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_change_stream_t.txt create mode 100644 source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_destroy.txt create mode 100644 source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_error_document.txt create mode 100644 source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_get_resume_token.txt create mode 100644 source/libmongoc/api/mongoc_change_stream_t/mongoc_change_stream_next.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/.DS_Store create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_add_key_alt_name.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_datakey.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_create_encrypted_collection.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keyaltnames.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_keymaterial.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_set_masterkey.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_datakey_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_decrypt.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_delete_key.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_expression.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_algorithm.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_contention_factor.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyaltname.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_keyid.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_query_type.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_set_range_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_max.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_min.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_precision.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_set_sparsity.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_encrypt_range_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_crypt_shared_version.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_key_by_alt_name.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_get_keys.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_client.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_keyvault_namespace.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_credential_provider_callback.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_kms_providers.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_set_tls_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_remove_key_alt_name.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_get_bulk_write_result.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_new.txt create mode 100644 source/libmongoc/api/mongoc_client_encryption_t/mongoc_client_encryption_rewrap_many_datakey_result_t.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_enable_auto_encryption.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_max_size.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_min_size.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_new_with_error.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_pop.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_push.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_apm_callbacks.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_appname.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_error_api.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_server_api.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_set_ssl_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_pool_t/mongoc_client_pool_try_pop.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_abort_transaction.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_cluster_time.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_advance_operation_time.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_append.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_commit_transaction.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_client.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_cluster_time.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_dirty.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_lsid.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_operation_time.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_server_id.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_get_transaction_state.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_in_transaction.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_start_transaction.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction.txt create mode 100644 source/libmongoc/api/mongoc_client_session_t/mongoc_client_session_with_transaction_cb_t.txt create mode 100644 source/libmongoc/api/mongoc_client_t.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_command.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_command_simple_with_server_id.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_destroy.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_enable_auto_encryption.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_find_databases_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_collection.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_crypt_shared_version.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_database.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_database_names_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_default_database.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_gridfs.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_handshake_description.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_description.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_descriptions.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_server_status.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_uri.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_new.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_new_from_uri_with_error.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_read_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_read_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_reset.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_select_server.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_apm_callbacks.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_appname.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_error_api.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_server_api.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_ssl_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_stream_initiator.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_set_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_start_session.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_watch.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_client_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_client_t/mongoc_handshake_data_append.txt create mode 100644 source/libmongoc/api/mongoc_collection_t.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_aggregate.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_command.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_simple.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_copy.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_count.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_documents.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_count_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_bulk_operation_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_index_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_create_indexes_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_many.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_delete_one.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_destroy.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_index_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_drop_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_ensure_index.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_estimated_document_count.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find_and_modify.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find_and_modify_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find_indexes.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find_indexes_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_find_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_get_last_error.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_get_name.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_get_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_get_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_insert.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_insert_bulk.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_insert_many.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_insert_one.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_keys_to_index_string.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_read_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_read_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_remove.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_rename.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_rename_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_replace_one.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_save.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_set_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_set_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_set_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_stats.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_update.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_update_many.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_update_one.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_validate.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_watch.txt create mode 100644 source/libmongoc/api/mongoc_collection_t/mongoc_collection_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_clone.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_current.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_destroy.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_error.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_error_document.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_batch_size.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_hint.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_host.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_id.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_limit.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_get_max_await_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_is_alive.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_more.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_new_from_command_reply.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_new_from_command_reply_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_next.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_set_batch_size.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_set_hint.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_set_limit.txt create mode 100644 source/libmongoc/api/mongoc_cursor_t/mongoc_cursor_set_max_await_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_database_t.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_add_user.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_aggregate.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_command.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_command_simple.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_copy.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_create_collection.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_destroy.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_drop.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_drop_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_find_collections.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_find_collections_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_collection.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_collection_names.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_collection_names_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_name.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_has_collection.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_read_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_read_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_remove_all_users.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_remove_user.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_set_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_set_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_set_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_watch.txt create mode 100644 source/libmongoc/api/mongoc_database_t/mongoc_database_write_command_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_delete_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_append.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_bypass_document_validation.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_fields.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_flags.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_max_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_sort.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_get_update.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_bypass_document_validation.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_fields.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_flags.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_max_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_sort.txt create mode 100644 source/libmongoc/api/mongoc_find_and_modify_opts_t/mongoc_find_and_modify_opts_set_update.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_abort_upload.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_delete_by_id.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_destroy.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_download_to_stream.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_find.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_new.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_open_download_stream.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_open_upload_stream.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_open_upload_stream_with_id.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_stream_error.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_t.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_upload_from_stream.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_bucket_upload_from_stream_with_id.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_create_file.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_create_file_from_stream.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_destroy.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_drop.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_destroy.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_error.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_aliases.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_chunk_size.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_content_type.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_filename.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_id.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_length.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_md5.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_metadata.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_get_upload_date.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_list_destroy.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_list_error.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_list_next.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_list_t.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_opt_t.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_readv.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_remove.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_save.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_seek.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_aliases.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_content_type.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_filename.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_id.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_md5.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_set_metadata.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_t.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_tell.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_file_writev.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_find.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_find_one.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_find_one_by_filename.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_find_one_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_find_with_opts.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_get_chunks.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_get_files.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_gridfs_remove_by_filename.txt create mode 100644 source/libmongoc/api/mongoc_gridfs_t/mongoc_stream_gridfs_new.txt create mode 100644 source/libmongoc/api/mongoc_handshake_data_append.textClipping create mode 100644 source/libmongoc/api/mongoc_host_list_t.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_geo_get_default.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_geo_init.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_geo_t.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_get_default.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_init.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_wt_get_default.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_wt_init.txt create mode 100644 source/libmongoc/api/mongoc_index_opt_t/mongoc_index_opt_wt_t.txt create mode 100644 source/libmongoc/api/mongoc_insert_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_iovec_t.txt create mode 100644 source/libmongoc/api/mongoc_optional_t.txt create mode 100644 source/libmongoc/api/mongoc_optional_t/mongoc_optional_copy.txt create mode 100644 source/libmongoc/api/mongoc_optional_t/mongoc_optional_init.txt create mode 100644 source/libmongoc/api/mongoc_optional_t/mongoc_optional_is_set.txt create mode 100644 source/libmongoc/api/mongoc_optional_t/mongoc_optional_set_value.txt create mode 100644 source/libmongoc/api/mongoc_optional_t/mongoc_optional_value.txt create mode 100644 source/libmongoc/api/mongoc_query_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_rand.txt create mode 100644 source/libmongoc/api/mongoc_rand/mongoc_rand_add.txt create mode 100644 source/libmongoc/api/mongoc_rand/mongoc_rand_seed.txt create mode 100644 source/libmongoc/api/mongoc_rand/mongoc_rand_status.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_append.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_copy.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_destroy.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_get_level.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_is_default.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_new.txt create mode 100644 source/libmongoc/api/mongoc_read_concern_t/mongoc_read_concern_set_level.txt create mode 100644 source/libmongoc/api/mongoc_read_mode_t.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_add_tag.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_copy.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_destroy.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_get_hedge.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_get_max_staleness_seconds.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_get_mode.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_get_tags.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_is_valid.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_new.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_set_hedge.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_set_max_staleness_seconds.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_set_mode.txt create mode 100644 source/libmongoc/api/mongoc_read_prefs_t/mongoc_read_prefs_set_tags.txt create mode 100644 source/libmongoc/api/mongoc_remove_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_reply_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_copy.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_deprecation_errors.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_destroy.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_get_deprecation_errors.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_get_strict.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_get_version.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_new.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_strict.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_version_from_string.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_version_t.txt create mode 100644 source/libmongoc/api/mongoc_server_api_t/mongoc_server_api_version_to_string.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/.DS_Store create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_destroy.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_hello_response.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_host.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_id.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_ismaster.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_last_update_time.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_new_copy.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_round_trip_time.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_description_type.txt create mode 100644 source/libmongoc/api/mongoc_server_description_t/mongoc_server_descriptions_destroy_all.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_clone.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_get_causal_consistency.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_get_default_transaction_opts.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_get_snapshot.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_get_transaction_opts.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_set_causal_consistency.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_set_default_transaction_opts.txt create mode 100644 source/libmongoc/api/mongoc_session_opt_t/mongoc_session_opts_set_snapshot.txt create mode 100644 source/libmongoc/api/mongoc_socket_t.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_accept.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_bind.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_close.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_connect.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_destroy.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_errno.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_getnameinfo.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_getsockname.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_listen.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_new.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_recv.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_send.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_sendv.txt create mode 100644 source/libmongoc/api/mongoc_socket_t/mongoc_socket_setsockopt.txt create mode 100644 source/libmongoc/api/mongoc_ssl_opt_get_default.txt create mode 100644 source/libmongoc/api/mongoc_ssl_opt_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_buffered_new.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_buffered_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_close.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_cork.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_destroy.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_file_get_fd.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_file_new.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_file_new_for_path.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_file_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_flush.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_get_base_stream.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_read.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_readv.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_setsockopt.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_should_retry.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_socket_get_socket.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_socket_new.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_socket_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_timed_out.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_tls_t.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_uncork.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_write.txt create mode 100644 source/libmongoc/api/mongoc_stream_t/mongoc_stream_writev.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_destroy.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_get_servers.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_has_readable_server.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_has_writable_server.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_new_copy.txt create mode 100644 source/libmongoc/api/mongoc_topology_description_t/mongoc_topology_description_type.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_clone.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_destroy.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_get_max_commit_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_get_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_get_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_new.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_set_max_commit_time_ms.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_set_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_set_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_transaction_opt_t/mongoc_transaction_opts_set_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_transaction_state_t.txt create mode 100644 source/libmongoc/api/mongoc_update_flags_t.txt create mode 100644 source/libmongoc/api/mongoc_uri_t.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_copy.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_destroy.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_auth_mechanism.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_auth_source.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_compressors.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_database.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_hosts.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_mechanism_properties.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_option_as_bool.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_option_as_int32.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_option_as_int64.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_option_as_utf8.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_options.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_password.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_read_prefs.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_read_prefs_t.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_replica_set.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_service.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_srv_hostname.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_srv_service_name.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_ssl.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_string.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_tls.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_username.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_get_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_has_option.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_new.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_new_for_host_port.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_new_with_error.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_option_is_bool.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_option_is_int32.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_option_is_int64.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_option_is_utf8.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_auth_mechanism.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_auth_source.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_compressors.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_database.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_mechanism_properties.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_option_as_bool.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_option_as_int32.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_option_as_int64.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_option_as_utf8.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_password.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_read_concern.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_read_prefs_t.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_username.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_set_write_concern.txt create mode 100644 source/libmongoc/api/mongoc_uri_t/mongoc_uri_unescape.txt create mode 100644 source/libmongoc/api/mongoc_version.txt create mode 100644 source/libmongoc/api/mongoc_version/mongoc_check_version.txt create mode 100644 source/libmongoc/api/mongoc_version/mongoc_get_major_version.txt create mode 100644 source/libmongoc/api/mongoc_version/mongoc_get_micro_version.txt create mode 100644 source/libmongoc/api/mongoc_version/mongoc_get_minor_version.txt create mode 100644 source/libmongoc/api/mongoc_version/mongoc_get_version.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_append.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_copy.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_destroy.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_fsync.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_journal.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_w.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_wmajority.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_wtag.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_wtimeout.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_get_wtimeout_int64.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_is_acknowledged.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_is_default.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_is_valid.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_journal_is_set.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_new.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_fsync.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_journal.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_w.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_wmajority.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_wtag.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_wtimeout.txt create mode 100644 source/libmongoc/api/mongoc_write_concern_t/mongoc_write_concern_set_wtimeout_int64.txt diff --git a/source/libbson.txt b/source/libbson.txt index f1b74ed0..591eb034 100644 --- a/source/libbson.txt +++ b/source/libbson.txt @@ -22,7 +22,6 @@ 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..d6e2af0a --- /dev/null +++ b/source/libbson/api.txt @@ -0,0 +1,49 @@ +============= +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/libmongoc.txt b/source/libmongoc.txt index fb50aa26..9964d9dd 100644 --- a/source/libmongoc.txt +++ b/source/libmongoc.txt @@ -25,7 +25,6 @@ libmongoc /libmongoc/guides /libmongoc/api /libmongoc/application-performance-monitoring - API Documentation Introduction ------------ diff --git a/source/libmongoc/api.txt b/source/libmongoc/api.txt new file mode 100644 index 00000000..a276440b --- /dev/null +++ b/source/libmongoc/api.txt @@ -0,0 +1,97 @@ +.. _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 0000000000000000000000000000000000000000..ca429368568c34bf7c6cdd536d91ba0e5caf0757 GIT binary patch literal 14340 zcmeHO-HsDC6h5st;53S*l)azwda4v1jc`*2$z)*wW1L{N;Q;w$Gm(5y|d8+qogKB_bDakY4@> zw{g)0wF{r~I8)YfC&Td#4%9D;?8{?0kb&el-v6=&h{WH)ab5O++{QnakqmL?7_A{4 z$dSC1LtKya&HCLOclmUJ_m5>0Z%^d-;rL*%JwDh52Z(3=XVAB&T2PDQN*qJ!gU1k@ zcC^-)U0l8NbCuu0Y186*OWUdd(kV$GNgzoeN#FyN0Bs-2g^Px!bCN)kK$5^a2~a3IyF>P2TpXM`J67a7S!SB>b-73dj*{us-NN;{S?%EniU~NWpS9n=7V-P%vjND9 zmZMe2NQ~?%jty<2wQ)Gb%!`UssjtkqJi+*QR*aPaXqi9uju%=S2Z_nbo-YGE50Y}! z8qGBbjo%Jzj)UjHLcLx|W)J$o=n(1*lTjb(oXVj~=^30rQhaix?{T(`G4uM+JG=fF zK#SyHjqw?LvNKrgr~>nl*2h7yxfF>VqxFQt^=WXs_H9Am4G(Pq4^ebwr7temJOwE5qOkTTmpn|}_3^p#8fF^A`@ zmeof0Xl3Y1&tO~e?n16?Aw44YvE35y=*?&=ZR9_!40(fXP!GaJ_5I3F1?HbxdK=Ma z5r_i6&9z9U57h9c(+4JjkI~+*B1Tmo7Ml@(@qFgh=ZH$gUWtxbbzj!{_xU_6m#e!U zz{ElW*f@GFL-;M_9s$4hLqt?cL1VL+=+L!ZmAAkh0W)(h)W0PH)Z#`!7{Lr3>u`?I zv0=`Y*U8-wCT^?zUvF*#T|Xdw||1(4UU5njasyrIB7N-T3GJKLtJ_B zs2#SY(heTqI+Y&}t?)ZMI;urt#&wGS&+LOu@jqsSo$U#DK`H*n989Gx32c}j-ns~S zKfM3HE%xbmlLV3k-UA6_oqNCBy9*%2-nui8xYw?W<5wIkd~eDM3hKHQ4^+3};euQ7 tZt26~gl9cgL8peIhO+WafM-0B6#v67cVh|vzni>1a*F>ki2tYY|G%1*pRE7@ literal 0 HcmV?d00001 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`` + - | ``$