1MONGOC_HANDSHAKE_DATA_APPEND(3) libmongoc MONGOC_HANDSHAKE_DATA_APPEND(3)
2
3
4
6 bool
7 mongoc_handshake_data_append (const char *driver_name,
8 const char *driver_version,
9 const char *platform);
10
11 Appends the given strings to the handshake data for the underlying C
12 Driver.
13
15 This function is intended for use by drivers which wrap the C Driver.
16 Calling this function will store the given strings as handshake data
17 about the system and driver by appending them to the handshake data for
18 the underlying C Driver. These values, along with other handshake data
19 collected during mongoc_init will be sent to the server as part of the
20 initial connection handshake in the "client" document. This function
21 must not be called more than once, or after server monitoring begins.
22 For a single-threaded mongoc_client_t, server monitoring begins on the
23 first operation requiring a server. For a mongoc_client_pool_t, server
24 monitoring begins on the first call to :symbol:`mongoc_client_pool_pop.
25
26 The passed in strings are copied, and don't have to remain valid after
27 the call to mongoc_handshake_data_append(). The driver may store trun‐
28 cated versions of the passed in strings.
29
30 NOTE:
31 This function allocates memory, and therefore caution should be used
32 when using this in conjunction with bson_mem_set_vtable(). If this
33 function is called before bson_mem_set_vtable(), then
34 bson_mem_restore_vtable() must be called before calling
35 mongoc_cleanup(). Failure to do so will result in memory being freed
36 by the wrong allocator.
37
39 • driver_name: An optional string storing the name of the wrapping
40 driver
41
42 • driver_version: An optional string storing the version of the wrap‐
43 ping driver.
44
45 • platform: An optional string storing any information about the cur‐
46 rent platform, for example configure options or compile flags.
47
49 true if the given fields are set successfully. Otherwise, it returns
50 false and logs an error.
51
52 The default handshake data the driver sends with "hello" looks some‐
53 thing like:
54
55 client: {
56 driver: {
57 name: "mongoc",
58 version: "1.5.0"
59 },
60 os: {...},
61 platform: "CC=gcc CFLAGS=-Wall -pedantic"
62 }
63
64 If we call mongoc_handshake_data_append() ("phongo", "1.1.8", "CC=clang
65 / ") and it returns true, the driver sends handshake data like:
66
67 client: {
68 driver: {
69 name: "mongoc / phongo",
70 version: "1.5.0 / 1.1.8"
71 },
72 os: {...},
73 platform: "CC=clang / gcc CFLAGS=-Wall -pedantic"
74 }
75
77 MongoDB, Inc
78
80 2017-present, MongoDB, Inc
81
82
83
84
851.25.1 Nov 08, 2023 MONGOC_HANDSHAKE_DATA_APPEND(3)