1MONGOC_CURSOR_ERROR_DOCUMENT(3)    libmongoc   MONGOC_CURSOR_ERROR_DOCUMENT(3)
2
3
4

NAME

6       mongoc_cursor_error_document - mongoc_cursor_error_document()
7

SYNOPSIS

9          bool
10          mongoc_cursor_error_document (mongoc_cursor_t *cursor,
11                                        bson_error_t *error,
12                                        const bson_t **reply);
13

PARAMETERS

15       • cursor: A mongoc_cursor_t.
16
17       • error: An optional location for a bson_error_t or NULL.
18
19       • reply: A location for a bson_t.
20

DESCRIPTION

22       This  function  checks  to see if an error has occurred while iterating
23       the cursor.
24
25       If an error occurred client-side, for example if there  was  a  network
26       error  or  timeout,  or the cursor was created with invalid parameters,
27       then reply is set to an empty  BSON  document.  If  an  error  occurred
28       server-side,  reply is set to the server's reply document with informa‐
29       tion about the error.
30

ERRORS

32       Errors are propagated via the error and reply parameters.
33

RETURNS

35       False if no error has occurred, otherwise true and error is set.
36
37       If the function returns true and reply is not NULL, then reply  is  set
38       to  a pointer to a BSON document, which is either empty or the server's
39       error response. The document is invalid after the cursor is freed  with
40       mongoc_cursor_destroy().
41

EXAMPLE

43       This example shows the difference between a client-side and server-side
44       error. If the client cannot connect to the server, for example, the er‐
45       ror message includes "No suitable servers found" and reply is set to an
46       empty BSON document.
47
48       On the other hand, if the client connects to  the  server  successfully
49       and  attempts to execute an invalid query, the error message comes from
50       the server and reply is set to the server's reply document, with fields
51       errmsg and code.
52
53          void
54          run_query (const char *uri_str, const bson_t *query)
55          {
56             mongoc_client_t *client;
57             mongoc_collection_t *collection;
58             mongoc_cursor_t *cursor;
59             const bson_t *doc;
60             bson_error_t error;
61             const bson_t *reply;
62             char *str;
63
64             client = mongoc_client_new (uri_str);
65
66             mongoc_client_set_error_api (client, 2);
67
68             collection = mongoc_client_get_collection (client, "db", "collection");
69             cursor = mongoc_collection_find_with_opts (
70                collection,
71                query,
72                NULL,  /* additional options */
73                NULL); /* read prefs, NULL for default */
74
75             /* this loop is never run: mongoc_cursor_next immediately returns false */
76             while (mongoc_cursor_next (cursor, &doc)) {
77             }
78
79             if (mongoc_cursor_error_document (cursor, &error, &reply)) {
80                str = bson_as_json (reply, NULL);
81                fprintf (stderr, "Cursor Failure: %s\nReply: %s\n", error.message, str);
82                bson_free (str);
83             }
84
85             mongoc_cursor_destroy (cursor);
86             mongoc_collection_destroy (collection);
87             mongoc_client_destroy (client);
88          }
89
90          int
91          main (int argc, char *argv[])
92          {
93             bson_t *good_query;
94             bson_t *bad_query;
95
96             mongoc_init ();
97
98             /* find documents matching the query {"x": 1} */
99             good_query = BCON_NEW ("x", BCON_INT64 (1));
100
101             /* Cause a network error. This will print an error and empty reply document:
102              *
103              * Cursor Failure: No suitable servers found (`serverSelectionTryOnce` set):
104              *     [Failed to resolve 'fake-domain']
105              *
106              * Reply: { }
107              *
108              */
109             run_query ("mongodb://fake-domain/?appname=cursor-example", good_query);
110
111             /* invalid: {"x": {"$badOperator": 1}} */
112             bad_query = BCON_NEW ("x", "{", "$badOperator", BCON_INT64 (1), "}");
113
114             /* Cause a server error. This will print an error and server reply document:
115              *
116              * Cursor Failure: unknown operator: $badOperator
117              *
118              * Reply:
119              * {"ok": 0.0,
120              *  "errmsg":"unknown operator: $badOperator",
121              *  "code": 2,
122              *  "codeName":"BadValue"
123              * }
124              *
125              */
126             run_query ("mongodb://localhost/?appname=cursor-example", bad_query);
127
128             bson_destroy (good_query);
129             bson_destroy (bad_query);
130
131             mongoc_cleanup ();
132
133             return 0;
134          }
135

AUTHOR

137       MongoDB, Inc
138

140       2017-present, MongoDB, Inc
141
142
143
144
1451.20.0                           Nov 18, 2021  MONGOC_CURSOR_ERROR_DOCUMENT(3)
Impressum