MONGOC_CLIENT...KE_DESCRIPTION(3)

💅 MONGOC_CLIENT...KE_DESCRIPTION(3) ✨

okay so this is a page straight out of libmongoc, bestie — the C driver manual, no cap. sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ SYNOPSIS ✨

mongoc_server_description_t *
mongoc_client_get_handshake_description (mongoc_client_t *client,
                                         uint32_t server_id,
                                         bson_t *opts,
                                         bson_error_t *error);

so this one hands you back a description that's built from the initial handshake response to a server. that's the whole vibe of it 🫶

---

🌸 DESCRIPTION 🌸

mongoc_client_get_handshake_description() is not the same thing as mongoc_client_get_server_description(), and the way people mix them up is giving "read the docs" energy 😭. mongoc_client_get_server_description() gives you a server description built from monitoring, and that one may genuinely differ from the server description you get from the connection handshake. different sources, different tea ☕

mongoc_client_get_handshake_description() will try to establish a connection to the server if one wasn't already established. and yes, it does the MongoDB handshake and authentication too if those are required. it's doing the full routine, not just showing up 💅

bestie, listen: use this function only when you're building a language driver that wraps the C Driver. if you're writing applications in C, the higher-level functions automatically select a suitable server for you — let them cook 👑

🦋 Single-threaded client behavior 🦋

single-threaded clients only have one active connection to each server. that one connection is used for both monitoring and application operations — sharing is caring, i guess 🙈

but even so, the server description returned by mongoc_client_get_handshake_description() may still differ from the one returned by mongoc_client_get_server_description(). literally still different. and the notable case is when you're connected to a load balanced cluster:

• the server description from mongoc_client_get_server_description() describes the load balancer server — mongoc_server_description_type() will return "LoadBalancer"
• the server description from mongoc_client_get_handshake_description() describes the backing server

so like… same cluster, different main characters 💀

---

🎀 PARAMETERS 🎀

• client — a mongoc_client_t. your client, your girlie, your whole world.
• server_id — the ID of the server. you can get this from the server description of mongoc_client_select_server(). it's giving "go ask the source" ✨
• opts — unused. pass NULL. that's it. that's the whole assignment 🫶
• error — an optional location for a bson_error_t, or NULL if you're feeling brave (or just don't want the error report).

---

🔥 RETURNS 🔥

a mongoc_server_description_t — and you must free it with mongoc_server_description_destroy(). do not leave it hanging, that's not the vibe 🌈

if a connection has not been successfully established to a server, it returns NULL and error gets filled out. so check your error, bestie, fr fr 😭

---

💖 SEE ALSO 💖

• mongoc_client_select_server() — to select a server from read preferences, iykyk
• mongoc_client_get_server_description() — to obtain the server description from monitoring for a server
• mongoc_server_description_type() — to obtain the type of server from a server description

---

👑 AUTHOR 👑

MongoDB, Inc — the icons themselves.

⭐ COPYRIGHT ⭐

2009-present, MongoDB, Inc.

---

and that's the whole page, bestie 🧚💜 sign-off time: this was libmongoc, version 2.5.6, dated Oct 09, 2026 — slay, ate, periodt 🎀✨