.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MONGOC_HANDSHAKE_DATA_APPEND" "3" "May 07, 2024" "1.27.1" "libmongoc"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_handshake_data_append (const char *driver_name,
                              const char *driver_version,
                              const char *platform);
.EE
.UNINDENT
.UNINDENT
.sp
Appends the given strings to the handshake data for the underlying C Driver.
.SH DESCRIPTION
.sp
This function is intended for use by drivers which wrap the C Driver.
Calling this function will store the given strings as handshake data about
the system and driver by appending them to the handshake data for the
underlying C Driver. These values, along with other handshake data collected
during mongoc_init will be sent to the server as part of the initial
connection handshake in the \(dqclient\(dq document. This function must not be
called more than once, or after server monitoring begins. For a single\-threaded
\fI\%mongoc_client_t\fP, server monitoring begins on the first operation
requiring a server. For a \fI\%mongoc_client_pool_t\fP, server monitoring
begins on the first call to \fI:symbol:\(gamongoc_client_pool_pop\fP\&.
.sp
The passed in strings are copied, and don\(aqt have to remain valid after the
call to \fI\%mongoc_handshake_data_append()\fP\&. The driver may store truncated
versions of the passed in strings.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This function allocates memory, and therefore caution should be used when
using this in conjunction with \fI\%bson_mem_set_vtable()\fP\&. If this function is
called before \fI\%bson_mem_set_vtable()\fP, then \fI\%bson_mem_restore_vtable()\fP must be
called before calling \fI\%mongoc_cleanup()\fP\&. Failure to do so will result in
memory being freed by the wrong allocator.
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBdriver_name\fP: An optional string storing the name of the wrapping driver
.IP \(bu 2
\fBdriver_version\fP: An optional string storing the version of the wrapping driver.
.IP \(bu 2
\fBplatform\fP: An optional string storing any information about the current platform, for example configure options or compile flags.
.UNINDENT
.SH RETURNS
.sp
\fBtrue\fP if the given fields are set successfully. Otherwise, it returns \fBfalse\fP and logs an error.
.sp
The default handshake data the driver sends with \(dqhello\(dq looks something
like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
client: {
  driver: {
    name: \(dqmongoc\(dq,
    version: \(dq1.5.0\(dq
  },
  os: {...},
  platform: \(dqCC=gcc CFLAGS=\-Wall \-pedantic\(dq
}
.EE
.UNINDENT
.UNINDENT
.sp
If we call
\fI\%mongoc_handshake_data_append()\fP (\(dqphongo\(dq, \(dq1.1.8\(dq, \(dqCC=clang / \(dq)
and it returns true, the driver sends handshake data like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
client: {
  driver: {
    name: \(dqmongoc / phongo\(dq,
    version: \(dq1.5.0 / 1.1.8\(dq
  },
  os: {...},
  platform: \(dqCC=clang / gcc CFLAGS=\-Wall \-pedantic\(dq
}
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.