plucky (3) mongoc_client_command.3.gz

WARNING:

          Deprecated  since version 1.29.0: This function is deprecated and should not be used in new code.  Use
          mongoc_client_command_simple() instead.

SYNOPSIS

          mongoc_cursor_t *
          mongoc_client_command (mongoc_client_t *client,
                                 const char *db_name,
                                 mongoc_query_flags_t flags,
                                 uint32_t skip,
                                 uint32_t limit,
                                 uint32_t batch_size,
                                 const bson_t *query,
                                 const bson_t *fields,
                                 const mongoc_read_prefs_t *read_prefs);

       This function is not considered a retryable read operation.

DESCRIPTION

       This function creates a cursor which will execute the command when mongoc_cursor_next() is called on  it.
       The  client's  read  preference,  read  concern,  and  write  concern are not applied to the command, and
       mongoc_cursor_next() will not check the server response for  a  write  concern  error  or  write  concern
       timeout.

       If  mongoc_cursor_next()  returns  false,  then  retrieve  error  details  with  mongoc_cursor_error() or
       mongoc_cursor_error_document().

PARAMETERS

       • client: A mongoc_client_t.

       • db_name: The name of the database to run the command on.

       • flags: Unused.

       • skip: Unused.

       • limit: Unused.

       • batch_size: Unused.

       • query: A bson_t containing the command specification.

       • fields: Unused.

       • read_prefs: An optional mongoc_read_prefs_t. Otherwise, the command uses mode MONGOC_READ_PRIMARY.

MIGRATING

       mongoc_client_command() is deprecated.

       The following example uses mongoc_client_command():

       Before

          const bson_t *reply;
          bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
          mongoc_cursor_t *cursor = mongoc_client_command (client,
                                                           "db",
                                                           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_client_command_simple() instead, as shown below:

       After

          bson_t reply;
          bson_error_t error;
          bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
          if (!mongoc_client_command_simple (client, "db", 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

       A mongoc_cursor_t.

       The cursor should be freed with mongoc_cursor_destroy().

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2009-present, MongoDB, Inc.