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

       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

       2017-present, MongoDB, Inc

1.26.0                                            Mar 31, 2024        MONGOC_CLIENT_GET_HANDSHAKE_DESCRIPTION(3)