NAME

       mongoc_client_get_handshake_description - mongoc_client_get_handshake_description()

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.21.0                                            Feb 09, 2022        MONGOC_CLIENT_GET_HANDSHAKE_DESCRIPTION(3)