Update versioned API getters (#765)

* Make mongoc_optional_t method args const

* Add const modifier to mongoc_server_api_t getters

* Fix wrong name for mongoc_server_api_t getter

* Add getter to retrieve version from mongoc_server_api_t

* Add documentation for mongoc_server_api_t getters

* Add documentation for mongoc_optional_t

* Fix CR feedback

Author: alcaeus

src/libmongoc/doc/api.rst

@@ -38,6 +38,7 @@ API Reference
    mongoc_insert_flags_t
    mongoc_iovec_t
    mongoc_matcher_t
+   mongoc_optional_t
    mongoc_query_flags_t
    mongoc_rand
    mongoc_read_concern_t

src/libmongoc/doc/mongoc_optional_copy.rst

@@ -0,0 +1,20 @@
+:man_page: mongoc_optional_copy
+
+mongoc_optional_copy()
+======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_optional_copy (const mongoc_optional_t *source, mongoc_optional_t *copy);
+
+Creates a deep copy of ``source`` into ``copy``.
+
+Parameters
+----------
+
+* ``source``: A :symbol:`mongoc_optional_t`.
+* ``copy``: An empty :symbol:`mongoc_optional_t`. Values will be overwritten.

src/libmongoc/doc/mongoc_optional_init.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_optional_init
+
+mongoc_optional_init()
+======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_optional_init (mongoc_optional_t *opt);
+
+Initializes values for a :symbol:`mongoc_optional_t`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.

src/libmongoc/doc/mongoc_optional_is_set.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_optional_is_set
+
+mongoc_optional_is_set()
+========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_optional_is_set (const mongoc_optional_t *opt);
+
+Returns whether a value for a :symbol:`mongoc_optional_t` was set.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.
+
+Returns
+-------
+
+Returns ``true`` if a value was set, or ``false`` otherwise.

src/libmongoc/doc/mongoc_optional_set_value.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_optional_set_value
+
+mongoc_optional_set_value()
+===========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_optional_set_value (mongoc_optional_t *opt);
+
+Sets a value on a :symbol:`mongoc_optional_t`. Once a value has been set, it cannot be unset, i.e. `mongoc_optional_is_set` will always return ``true`` after calling `mongoc_optional_set_value`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.

src/libmongoc/doc/mongoc_optional_t.rst

@@ -0,0 +1,28 @@
+:man_page: mongoc_optional_t
+
+mongoc_optional_t
+=================
+
+A struct to store optional boolean values.
+
+Synopsis
+--------
+
+Used to specify optional boolean flags, which may remain unset.
+
+This is used within :symbol:`mongoc_server_api_t` to track whether a flag was explicitly set.
+
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_optional_copy
+    mongoc_optional_init
+    mongoc_optional_is_set
+    mongoc_optional_set_value
+    mongoc_optional_value

src/libmongoc/doc/mongoc_optional_value.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_optional_value
+
+mongoc_optional_value()
+=======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_optional_value (const mongoc_optional_t *opt);
+
+Returns the value for a :symbol:`mongoc_optional_t`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.
+
+Returns
+-------
+
+Returns the value that was set on the :symbol:`mongoc_optional_t`. If no value was set, ``false`` is returned.

src/libmongoc/doc/mongoc_server_api_get_deprecation_errors.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_server_api_get_deprecation_errors
+
+mongoc_server_api_get_deprecation_errors()
+==========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const mongoc_optional_t *
+  mongoc_server_api_get_deprecation_errors (const mongoc_server_api_t *api);
+
+Returns the value of the deprecation_errors flag for the :symbol:`mongoc_server_api_t`.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+
+Returns
+-------
+
+Returns a :symbol:`mongoc_optional_t` indicating whether the deprecation_errors flag was set.

src/libmongoc/doc/mongoc_server_api_get_strict.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_server_api_get_strict
+
+mongoc_server_api_get_strict()
+==============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const mongoc_optional_t *
+  mongoc_server_api_get_strict (const mongoc_server_api_t *api);
+
+Returns the value of the strict flag for the :symbol:`mongoc_server_api_t`.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+
+Returns
+-------
+
+Returns a :symbol:`mongoc_optional_t` indicating whether the strict flag was set.

src/libmongoc/doc/mongoc_server_api_get_version.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_server_api_get_version
+
+mongoc_server_api_get_version()
+===============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_server_api_version_t
+  mongoc_server_api_get_version (const mongoc_server_api_t *api);
+
+Fetch the declared API version as from a :symbol:`mongoc_server_api_t`.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+
+Returns
+-------
+
+Returns a :symbol:`mongoc_server_api_version_t` with the API version declare in the :symbol:`mongoc_server_api_t`.

src/libmongoc/doc/mongoc_server_api_t.rst

@@ -26,5 +26,8 @@ A :symbol:`mongoc_server_api_t` can be set on a client, and will then be sent to
     mongoc_server_api_copy
     mongoc_server_api_deprecation_errors
     mongoc_server_api_destroy
+    mongoc_server_api_get_deprecation_errors
+    mongoc_server_api_get_strict
+    mongoc_server_api_get_version
     mongoc_server_api_new
     mongoc_server_api_strict

src/libmongoc/src/mongoc/mongoc-optional.c

@@ -24,14 +24,14 @@ mongoc_optional_init (mongoc_optional_t *opt)
 }
 
 bool
-mongoc_optional_is_set (mongoc_optional_t *opt)
+mongoc_optional_is_set (const mongoc_optional_t *opt)
 {
    BSON_ASSERT (opt);
    return opt->is_set;
 }
 
 bool
-mongoc_optional_value (mongoc_optional_t *opt)
+mongoc_optional_value (const mongoc_optional_t *opt)
 {
    BSON_ASSERT (opt);
    return opt->value;

src/libmongoc/src/mongoc/mongoc-optional.h

@@ -34,10 +34,10 @@ MONGOC_EXPORT (void)
 mongoc_optional_init (mongoc_optional_t *opt);
 
 MONGOC_EXPORT (bool)
-mongoc_optional_is_set (mongoc_optional_t *opt);
+mongoc_optional_is_set (const mongoc_optional_t *opt);
 
 MONGOC_EXPORT (bool)
-mongoc_optional_value (mongoc_optional_t *opt);
+mongoc_optional_value (const mongoc_optional_t *opt);
 
 MONGOC_EXPORT (void)
 mongoc_optional_set_value (mongoc_optional_t *opt, bool val);

src/libmongoc/src/mongoc/mongoc-server-api.c

@@ -97,15 +97,22 @@ mongoc_server_api_deprecation_errors (mongoc_server_api_t *api,
 }
 
 const mongoc_optional_t *
-mongoc_server_api_get_deprecation_errors (mongoc_server_api_t *api)
+mongoc_server_api_get_deprecation_errors (const mongoc_server_api_t *api)
 {
    BSON_ASSERT (api);
    return &api->deprecation_errors;
 }
 
 const mongoc_optional_t *
-mongo_server_api_get_strict (mongoc_server_api_t *api)
+mongoc_server_api_get_strict (const mongoc_server_api_t *api)
 {
    BSON_ASSERT (api);
    return &api->strict;
 }
+
+mongoc_server_api_version_t
+mongoc_server_api_get_version (const mongoc_server_api_t *api)
+{
+   BSON_ASSERT (api);
+   return api->version;
+}

src/libmongoc/src/mongoc/mongoc-server-api.h

@@ -54,10 +54,13 @@ mongoc_server_api_deprecation_errors (mongoc_server_api_t *api,
                                       bool deprecation_errors);
 
 MONGOC_EXPORT (const mongoc_optional_t *)
-mongoc_server_api_get_deprecation_errors (mongoc_server_api_t *api);
+mongoc_server_api_get_deprecation_errors (const mongoc_server_api_t *api);
 
 MONGOC_EXPORT (const mongoc_optional_t *)
-mongo_server_api_get_strict (mongoc_server_api_t *api);
+mongoc_server_api_get_strict (const mongoc_server_api_t *api);
+
+MONGOC_EXPORT (mongoc_server_api_version_t)
+mongoc_server_api_get_version (const mongoc_server_api_t *api);
 
 BSON_END_DECLS