1MONGOC_CURSOR_T(3)                 libmongoc                MONGOC_CURSOR_T(3)
2
3
4

NAME

6       mongoc_cursor_t - mongoc_cursor_t
7
8       Client-side cursor abstraction
9

SYNOPSIS

11          typedef struct _mongoc_cursor_t mongoc_cursor_t;
12
13       mongoc_cursor_t provides access to a MongoDB query cursor.  It wraps up
14       the wire protocol negotiation required to initiate a query and retrieve
15       an unknown number of documents.
16
17       Common cursor operations include:
18
19       • Determine   which   host   we've   connected   to   with  mongoc_cur‐
20         sor_get_host().
21
22       • Retrieve more records with repeated calls to mongoc_cursor_next().
23
24       • Clone a query to repeat execution at a later point  with  mongoc_cur‐
25         sor_clone().
26
27       • Test for errors with mongoc_cursor_error().
28
29       Cursors are lazy, meaning that no connection is established and no net‐
30       work traffic occurs until the first call to mongoc_cursor_next().
31

THREAD SAFETY

33       mongoc_cursor_t is NOT thread safe. It may only be used from within the
34       thread in which it was created.
35

EXAMPLE

37       Query MongoDB and iterate results
38
39          /* gcc example-client.c -o example-client $(pkg-config --cflags --libs
40           * libmongoc-1.0) */
41
42          /* ./example-client [CONNECTION_STRING [COLLECTION_NAME]] */
43
44          #include <mongoc/mongoc.h>
45          #include <stdio.h>
46          #include <stdlib.h>
47
48          int
49          main (int argc, char *argv[])
50          {
51             mongoc_client_t *client;
52             mongoc_collection_t *collection;
53             mongoc_cursor_t *cursor;
54             bson_error_t error;
55             const bson_t *doc;
56             const char *collection_name = "test";
57             bson_t query;
58             char *str;
59             const char *uri_string = "mongodb://127.0.0.1/?appname=client-example";
60             mongoc_uri_t *uri;
61
62             mongoc_init ();
63             if (argc > 1) {
64                uri_string = argv[1];
65             }
66
67             if (argc > 2) {
68                collection_name = argv[2];
69             }
70
71             uri = mongoc_uri_new_with_error (uri_string, &error);
72             if (!uri) {
73                fprintf (stderr,
74                         "failed to parse URI: %s\n"
75                         "error message:       %s\n",
76                         uri_string,
77                         error.message);
78                return EXIT_FAILURE;
79             }
80
81             client = mongoc_client_new_from_uri (uri);
82             if (!client) {
83                return EXIT_FAILURE;
84             }
85
86             mongoc_client_set_error_api (client, 2);
87
88             bson_init (&query);
89             collection = mongoc_client_get_collection (client, "test", collection_name);
90             cursor = mongoc_collection_find_with_opts (
91                collection,
92                &query,
93                NULL,  /* additional options */
94                NULL); /* read prefs, NULL for default */
95
96             while (mongoc_cursor_next (cursor, &doc)) {
97                str = bson_as_canonical_extended_json (doc, NULL);
98                fprintf (stdout, "%s\n", str);
99                bson_free (str);
100             }
101
102             if (mongoc_cursor_error (cursor, &error)) {
103                fprintf (stderr, "Cursor Failure: %s\n", error.message);
104                return EXIT_FAILURE;
105             }
106
107             bson_destroy (&query);
108             mongoc_cursor_destroy (cursor);
109             mongoc_collection_destroy (collection);
110             mongoc_uri_destroy (uri);
111             mongoc_client_destroy (client);
112             mongoc_cleanup ();
113
114             return EXIT_SUCCESS;
115          }
116
117

AUTHOR

119       MongoDB, Inc
120

122       2017-present, MongoDB, Inc
123
124
125
126
1271.20.0                           Nov 18, 2021               MONGOC_CURSOR_T(3)
Impressum