MONGOC_OIDC_CALLBACK_PARAMS_T(3)

Hey bestie 💖 welcome to MONGOC_OIDC_CALLBACK_PARAMS_T(3) from libmongoc — the manual page for the in/out parameter struct that OIDC callbacks pass around like it’s the group chat. ✨

✨ SYNOPSIS ✨

typedef struct _mongoc_oidc_callback_params_t mongoc_oidc_callback_params_t;

Okay so this typedef is literally the in/out parameters of a mongoc_oidc_callback_t.

These parameters get 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. No cap, that’s the whole flow. 🫶

🎀 PARAMETERS 🎀

The list of currently supported parameters are:

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

The Versions column tells you the OIDC callback API versions for which the parameter is applicable — and every parameter above is sitting pretty at version 1. 👑

🌸 Version 🌸

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

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. It’s giving “sneaky little side channel” energy. 😌

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 by the user, not by mongoc_oidc_callback_t! Do not forget this one, bestie. 💀

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);
      BSON_ASSERT (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. Clock says time’s up, so behave accordingly. ⏳

👑 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. Main character username energy. 🌟

💅 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. Do not let this one slide, fr fr. 🚨

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. This is not a drill. 💅

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;
   }

   // ...
}

🔗 SEE ALSO 🔗

• mongoc_oidc_callback_t
• mongoc_oidc_callback_fn_t

✍️ AUTHOR ✍️

MongoDB, Inc

©️ COPYRIGHT ©️

2009-present, MongoDB, Inc.

---

That’s the whole vibe, bestie 💅✨ This page is from libmongoc version 2.5.6, dated Oct 09, 2026. Now go slay those OIDC callbacks! 🎀🦋🌸