NAME

       mongoc_client_encryption_create_encrypted_collection                                     -
       mongoc_client_encryption_create_encrypted_collection()

SYNOPSIS

          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  Queryable   Encryption   enabled.   Requires   a   valid
       mongoc_client_encryption_t object to operate.

       New in version 1.24.0.

       SEE ALSO:
          This function is a convenience API wrapping mongoc_database_create_collection().

PARAMETERS

       • enc:  The  mongoc_client_encryption_t  to  be  used  to configure encryption for the new
         collection.

       • database: The 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 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: mongoc_client_encryption_datakey_opts_set_masterkey())

       • error: Optional output parameter pointing to storage for a  bson_error_t.  If  an  error
         occurs, will be initialized with error information.

RETURNS

       If  successful,  this  function  returns  a new 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
       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 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.

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc

1.24.3                                    MONGOC0CLIENT_ENCRYPTION_CREATE_ENCRYPTED_COLLECTION(3)