mongoc_oidc_callback_params_t¶

Synopsis¶

typedef struct _mongoc_oidc_callback_params_t mongoc_oidc_callback_params_t;

Represents the in/out parameters of a mongoc_oidc_callback_t.

The parameters will be passed to the mongoc_oidc_callback_fn_t stored in an mongoc_oidc_callback_t object when it is invoked by an mongoc_client_t or mongoc_client_pool_t object.

Functions¶

Parameters¶

The list of currently supported parameters are:

Parameter	Versions	Description
`version`	1	The current OIDC callback API version number.
`user_data`	1	A pointer to data provided by the user.
`timeout`	1	The timestamp after which the callback function must report a timeout.
`username`	1	The username specified by the URI of the associated client object.
`cancel_with_timeout`	1	An out parameter indicating cancellation of the callback function due to a timeout instead of an error.

The “Version” column indicates the OIDC callback API versions for which the parameter is applicable.

Version¶

The version parameter is used to communicate backward compatible changes to the OIDC callback API (i.e. the addition of a new parameter).

This parameter may be used to detect when existing usage of mongoc_oidc_callback_t or a relevant callback function may need to be reviewed.

For example, users may add the following check to their callback function:

mongoc_oidc_credential_t *
example_callback_fn (mongoc_oidc_callback_params_t *params)
{
   // A runtime message that new features are available in the OIDC Callback API.
   if (mongoc_oidc_callback_params_get_version (params) > 1) {
      printf ("OIDC Callback API has been updated to a new version!");
   }

   // ...
}

User Data¶

The user_data parameter may be used to pass additional arguments to the callback function or to return additional values out of the callback function.

This parameter must be set in advance via mongoc_oidc_callback_set_user_data() before the mongoc_oidc_callback_t object is associated with a mongoc_client_t or mongoc_client_pool_t object.

Warning

The lifetime of the object pointed to by user_data is managed the user, not by mongoc_oidc_callback_t!

typedef struct {
   int counter;
   const char *error_message;
} user_data_t;

mongoc_oidc_credential_t *
example_callback_fn (mongoc_oidc_callback_params_t *params)
{
   user_data_t *user_data = (user_data_t *) mongoc_oidc_callback_params_get_user_data (params);

   user_data->counter += 1;

   // ...

   if (/* ... */) {
      user_data->error_message = "OIDC callback failed due to ...";
      return NULL;
   }

   // ...
}

void
example (void)
{
   mongoc_client_t *client = /* ... */;
   bson_error_t error;

   {
      user_data_t *user_data = malloc (sizeof (*user_data));
      *user_data = (user_data_t){.counter = 0, .error_message = NULL};
      mongoc_oidc_callback_t *callback = mongoc_oidc_callback_new_with_user_data (&example_callback_fn, (void *) user_data);
      mongoc_client_set_oidc_callback (client, callback);
      mongoc_oidc_callback_destroy (callback);
   }

   // ... client operations ...

   {
      const mongoc_oidc_callback_t *callback = mongoc_client_get_oidc_callback (client);
      user_data_t *user_data = (user_data_t *) mongoc_oidc_callback_get_user_data (callback);

      if (error.code != 0) {
         printf ("client error message: %s\n", error.message);
      }

      if (user_data->error_message) {
         printf ("custom error message: %s\n", user_data->error_message);
      }

      printf ("The callback function was invoked %d times!", user_data->counter);

      free (user_data);
   }

   mongoc_client_destroy (client);
}

Timeout¶

The timeout parameter is used to determine when the callback function should report cancellation due to a timeout.

When System Clock is greater than timeout, the callback function must invoke mongoc_oidc_callback_params_cancel_with_timeout() and return NULL.

Username¶

The username parameter is the value of the username component of the URI of the associated mongoc_client_t or mongoc_client_pool_t object from which the callback function is invoked.

Cancel With Timeout¶

The cancel_with_timeout out parameter indicates cancellation of the callback function due to a timeout instead of an error.

Important

The callback function MUST return NULL, otherwise the invocation will be interpreted as a success even when cancel_with_timeout is set.

mongoc_oidc_credential_t *
example_callback_fn (mongoc_oidc_callback_params_t *params) {
   const int64_t *timeout = mongoc_oidc_callback_params_get_timeout (params);

   // NULL means "infinite" timeout.
   if (timeout && bson_get_monotonic_time () > *timeout) {
      return mongoc_oidc_callback_params_cancel_with_timeout (params);
   }

   // ...
}

Error Handling¶

A NULL return value (without setting cancel_with_timeout) indicates failure to provide an access token due to an error.

Important

The callback function MUST return NULL, otherwise the invocation will be interpreted as a success.

mongoc_oidc_credential_t *
example_callback_fn (mongoc_oidc_callback_params_t *params) {
   // ...

   if (/* ... */) {
      // The OIDC callback function could not provide an access token due to an error.
      return NULL;
   }

   // ...
}