plucky (3) mongoc_collection_command.3.gz

WARNING:
Deprecated since version 1.29.0: This function is deprecated and should not be used in new code. Use mongoc_collection_command_simple() instead.
SYNOPSIS
mongoc_cursor_t * mongoc_collection_command (mongoc_collection_t *collection, mongoc_query_flags_t flags, uint32_t skip, uint32_t limit, uint32_t batch_size, const bson_t *command, const bson_t *fields, const mongoc_read_prefs_t *read_prefs); This function is not considered a retryable read operation.
PARAMETERS
• collection: A mongoc_collection_t. • flags: Unused. • skip: Unused. • limit: Unused. • batch_size: Unused. • command: A bson_t containing the command to execute. • fields: Unused. • read_prefs: An optional mongoc_read_prefs_t. Otherwise, the command uses mode MONGOC_READ_PRIMARY.
MIGRATING
mongoc_collection_command() is deprecated. The following example uses mongoc_collection_command(): Before const bson_t *reply; bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}"); mongoc_cursor_t *cursor = mongoc_collection_command (coll, MONGOC_QUERY_NONE /* unused */, 0 /* unused */, 0 /* unused */, 0 /* unused */, cmd, NULL /* unused */, NULL /* read prefs */); // Expect cursor to return exactly one document for the command reply. EXPECT (mongoc_cursor_next (cursor, &reply)); bson_error_t error; if (mongoc_cursor_error (cursor, &error)) { FAIL ("Expected no error, got: %s\n", error.message); } // Expect successful reply to contain "ok": 1 bson_iter_t iter; EXPECT (bson_iter_init_find (&iter, reply, "ok") && bson_iter_as_int64 (&iter) == 1); // Expect cursor to return no other documents. EXPECT (!mongoc_cursor_next (cursor, &reply)); mongoc_cursor_destroy (cursor); bson_destroy (cmd); The above code block may be rewritten to use mongoc_collection_command_simple() instead, as shown below: After bson_t reply; bson_error_t error; bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}"); if (!mongoc_collection_command_simple (coll, cmd, NULL /* read prefs */, &reply, &error)) { FAIL ("Expected no error, got: %s\n", error.message); } // Expect successful reply to contain "ok": 1 bson_iter_t iter; EXPECT (bson_iter_init_find (&iter, &reply, "ok") && bson_iter_as_int64 (&iter) == 1); bson_destroy (&reply); bson_destroy (cmd);
RETURNS
This function returns a newly allocated mongoc_cursor_t that should be freed with mongoc_cursor_destroy() when no longer in use. The returned mongoc_cursor_t is never NULL, even on error. The user must call mongoc_cursor_next() on the returned mongoc_cursor_t to execute the initial command. Cursor errors can be checked with mongoc_cursor_error_document(). It always fills out the bson_error_t if an error occurred, and optionally includes a server reply document if the error occurred server-side. WARNING: Failure to handle the result of this function is a programming error.
AUTHOR
MongoDB, Inc
COPYRIGHT
2009-present, MongoDB, Inc.