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

       Returns a description constructed from the initial handshake response to a server.

DESCRIPTION

       mongoc_client_get_handshake_description()  <> is distinct from mongoc_client_get_server_description() <>.
       mongoc_client_get_server_description() <> returns a server description constructed from monitoring, which
       may differ from the server description constructed from the connection handshake.

       mongoc_client_get_handshake_description() <> will attempt to establish a connection to the  server  if  a
       connection  was  not  already  established.  It  will perform the MongoDB handshake and authentication if
       required.

       Use this function only for building a language driver that wraps the C Driver. When writing  applications
       in C, higher-level functions automatically select a suitable server.

   Single-threaded client behavior
       Single-threaded  clients  only  have one active connection to each server. The one connection is used for
       both  monitoring  and   application   operations.   However,   the   server   description   returned   by
       mongoc_client_get_handshake_description()  <>  may  still  differ from the server description returned by
       mongoc_client_get_server_description() <>. Notably, if connected to a load balanced cluster,  the  server
       description  returned by mongoc_client_get_server_description() <> will describe the load balancer server
       (mongoc_server_description_type() <> will return "LoadBalancer"). And the server description returned  by
       mongoc_client_get_handshake_description() <> will describe the backing server.

PARAMETERS

       • client: A mongoc_client_t <>.

       • server_id:   The   ID   of   the   server.  This  can  be  obtained  from  the  server  description  of
         mongoc_client_select_server() <>.

       • opts: Unused. Pass NULL.

       • error: An optional location for a bson_error_t <> or NULL.

RETURNS

       A mongoc_server_description_t <> that must be freed with  mongoc_server_description_destroy()  <>.  If  a
       connection has not been successfully established to a server, returns NULL and error is filled out.

SEE ALSO

       • mongoc_client_select_server() <> To select a server from read preferences.

       • 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

Copyright

       2009-present, MongoDB, Inc.

2.2.1                                             Dec 11, 2025        MONGOC_CLIENT_GET_HANDSHAKE_DESCRIPTION(3)