MongoDBCDriver  0.7.1
Classes | Defines | Typedefs | Enumerations | Functions
mongo.h File Reference

Main MongoDB Declarations. More...

#include "bson.h"

Go to the source code of this file.

Classes

struct  mongo_header
struct  mongo_message
struct  mongo_reply_fields
struct  mongo_reply
struct  mongo_host_port
struct  mongo_write_concern
struct  mongo_replica_set
struct  mongo
struct  mongo_cursor

Defines

#define MONGO_MAJOR   0
#define MONGO_MINOR   7
#define MONGO_PATCH   0
#define MONGO_OK   0
#define MONGO_ERROR   -1
#define MONGO_DEFAULT_PORT   27017
#define MONGO_DEFAULT_MAX_BSON_SIZE   4 * 1024 * 1024
#define MONGO_ERR_LEN   128

Typedefs

typedef enum mongo_error_t mongo_error_t
typedef enum mongo_cursor_error_t mongo_cursor_error_t
typedef struct mongo_host_port mongo_host_port
typedef struct mongo_write_concern mongo_write_concern
typedef struct mongo mongo

Enumerations

enum  mongo_error_t {
  MONGO_CONN_SUCCESS = 0, MONGO_CONN_NO_SOCKET, MONGO_CONN_FAIL, MONGO_CONN_ADDR_FAIL,
  MONGO_CONN_NOT_MASTER, MONGO_CONN_BAD_SET_NAME, MONGO_CONN_NO_PRIMARY, MONGO_IO_ERROR,
  MONGO_SOCKET_ERROR, MONGO_READ_SIZE_ERROR, MONGO_COMMAND_FAILED, MONGO_WRITE_ERROR,
  MONGO_NS_INVALID, MONGO_BSON_INVALID, MONGO_BSON_NOT_FINISHED, MONGO_BSON_TOO_LARGE,
  MONGO_WRITE_CONCERN_INVALID
}
enum  mongo_cursor_error_t {
  MONGO_CURSOR_EXHAUSTED, MONGO_CURSOR_INVALID, MONGO_CURSOR_PENDING, MONGO_CURSOR_QUERY_FAIL,
  MONGO_CURSOR_BSON_ERROR
}
enum  mongo_cursor_flags { MONGO_CURSOR_MUST_FREE = 1, MONGO_CURSOR_QUERY_SENT = ( 1<<1 ) }
enum  mongo_index_opts { MONGO_INDEX_UNIQUE = ( 1<<0 ), MONGO_INDEX_DROP_DUPS = ( 1<<2 ), MONGO_INDEX_BACKGROUND = ( 1<<3 ), MONGO_INDEX_SPARSE = ( 1<<4 ) }
enum  mongo_update_opts { MONGO_UPDATE_UPSERT = 0x1, MONGO_UPDATE_MULTI = 0x2, MONGO_UPDATE_BASIC = 0x4 }
enum  mongo_insert_opts { MONGO_CONTINUE_ON_ERROR = 0x1 }
enum  mongo_cursor_opts {
  MONGO_TAILABLE = ( 1<<1 ), MONGO_SLAVE_OK = ( 1<<2 ), MONGO_NO_CURSOR_TIMEOUT = ( 1<<4 ), MONGO_AWAIT_DATA = ( 1<<5 ),
  MONGO_EXHAUST = ( 1<<6 ), MONGO_PARTIAL = ( 1<<7 )
}
enum  mongo_operations {
  MONGO_OP_MSG = 1000, MONGO_OP_UPDATE = 2001, MONGO_OP_INSERT = 2002, MONGO_OP_QUERY = 2004,
  MONGO_OP_GET_MORE = 2005, MONGO_OP_DELETE = 2006, MONGO_OP_KILL_CURSORS = 2007
}

Functions

MONGO_EXPORT void mongo_init_sockets (void)
 Initialize sockets for Windows.
MONGO_EXPORT void mongo_init (mongo *conn)
 Initialize a new mongo connection object.
MONGO_EXPORT int mongo_client (mongo *conn, const char *host, int port)
 Connect to a single MongoDB server.
MONGO_EXPORT int mongo_connect (mongo *conn, const char *host, int port)
 DEPRECATED - use mongo_client.
MONGO_EXPORT void mongo_replica_set_init (mongo *conn, const char *name)
 Set up this connection object for connecting to a replica set.
MONGO_EXPORT void mongo_replset_init (mongo *conn, const char *name)
 DEPRECATED - use mongo_replica_set_init.
MONGO_EXPORT void mongo_replica_set_add_seed (mongo *conn, const char *host, int port)
 Add a seed node to the replica set connection object.
MONGO_EXPORT void mongo_replset_add_seed (mongo *conn, const char *host, int port)
 DEPRECATED - use mongo_replica_set_add_seed.
void mongo_parse_host (const char *host_string, mongo_host_port *host_port)
 Utility function for converting a host-port string to a mongo_host_port.
MONGO_EXPORT int mongo_validate_ns (mongo *conn, const char *ns)
 Utility function for validation database and collection names.
MONGO_EXPORT int mongo_replica_set_client (mongo *conn)
 Connect to a replica set.
MONGO_EXPORT int mongo_replset_connect (mongo *conn)
 DEPRECATED - use mongo_replica_set_client.
MONGO_EXPORT int mongo_set_op_timeout (mongo *conn, int millis)
 Set a timeout for operations on this connection.
MONGO_EXPORT int mongo_check_connection (mongo *conn)
 Ensure that this connection is healthy by performing a round-trip to the server.
MONGO_EXPORT int mongo_reconnect (mongo *conn)
 Try reconnecting to the server using the existing connection settings.
MONGO_EXPORT void mongo_disconnect (mongo *conn)
 Close the current connection to the server.
MONGO_EXPORT void mongo_destroy (mongo *conn)
 Close any existing connection to the server and free all allocated memory associated with the conn object.
MONGO_EXPORT void mongo_set_write_concern (mongo *conn, mongo_write_concern *write_concern)
 Specify the write concern object that this connection should use by default for all writes (inserts, updates, and deletes).
MONGO_EXPORT int mongo_insert (mongo *conn, const char *ns, const bson *data, mongo_write_concern *custom_write_concern)
 Insert a BSON document into a MongoDB server.
MONGO_EXPORT int mongo_insert_batch (mongo *conn, const char *ns, const bson **data, int num, mongo_write_concern *custom_write_concern, int flags)
 Insert a batch of BSON documents into a MongoDB server.
MONGO_EXPORT int mongo_update (mongo *conn, const char *ns, const bson *cond, const bson *op, int flags, mongo_write_concern *custom_write_concern)
 Update a document in a MongoDB server.
MONGO_EXPORT int mongo_remove (mongo *conn, const char *ns, const bson *cond, mongo_write_concern *custom_write_concern)
 Remove a document from a MongoDB server.
MONGO_EXPORT void mongo_write_concern_init (mongo_write_concern *write_concern)
 Initialize a mongo_write_concern object.
MONGO_EXPORT int mongo_write_concern_finish (mongo_write_concern *write_concern)
 Finish this write concern object by serializing the literal getlasterror command that will be sent to the server.
MONGO_EXPORT void mongo_write_concern_destroy (mongo_write_concern *write_concern)
 Free the write_concern object (specifically, the BSON that it owns).
MONGO_EXPORT mongo_cursormongo_find (mongo *conn, const char *ns, const bson *query, const bson *fields, int limit, int skip, int options)
 Find documents in a MongoDB server.
MONGO_EXPORT void mongo_cursor_init (mongo_cursor *cursor, mongo *conn, const char *ns)
 Initalize a new cursor object.
MONGO_EXPORT void mongo_cursor_set_query (mongo_cursor *cursor, const bson *query)
 Set the bson object specifying this cursor's query spec.
MONGO_EXPORT void mongo_cursor_set_fields (mongo_cursor *cursor, const bson *fields)
 Set the fields to return for this cursor.
MONGO_EXPORT void mongo_cursor_set_skip (mongo_cursor *cursor, int skip)
 Set the number of documents to skip.
MONGO_EXPORT void mongo_cursor_set_limit (mongo_cursor *cursor, int limit)
 Set the number of documents to return.
MONGO_EXPORT void mongo_cursor_set_options (mongo_cursor *cursor, int options)
 Set any of the available query options (e.g., MONGO_TAILABLE).
MONGO_EXPORT const char * mongo_cursor_data (mongo_cursor *cursor)
 Return the current BSON object data as a const char*.
MONGO_EXPORT const bsonmongo_cursor_bson (mongo_cursor *cursor)
 Return the current BSON object data as a const char*.
MONGO_EXPORT int mongo_cursor_next (mongo_cursor *cursor)
 Iterate the cursor, returning the next item.
MONGO_EXPORT int mongo_cursor_destroy (mongo_cursor *cursor)
 Destroy a cursor object.
MONGO_EXPORT int mongo_find_one (mongo *conn, const char *ns, const bson *query, const bson *fields, bson *out)
 Find a single document in a MongoDB server.
MONGO_EXPORT double mongo_count (mongo *conn, const char *db, const char *coll, const bson *query)
 Count the number of documents in a collection matching a query.
MONGO_EXPORT int mongo_create_index (mongo *conn, const char *ns, const bson *key, int options, bson *out)
 Create a compound index.
MONGO_EXPORT int mongo_create_capped_collection (mongo *conn, const char *db, const char *collection, int size, int max, bson *out)
 Create a capped collection.
MONGO_EXPORT bson_bool_t mongo_create_simple_index (mongo *conn, const char *ns, const char *field, int options, bson *out)
 Create an index with a single key.
MONGO_EXPORT int mongo_run_command (mongo *conn, const char *db, const bson *command, bson *out)
 Run a command on a MongoDB server.
MONGO_EXPORT int mongo_simple_int_command (mongo *conn, const char *db, const char *cmd, int arg, bson *out)
 Run a command that accepts a simple string key and integer value.
MONGO_EXPORT int mongo_simple_str_command (mongo *conn, const char *db, const char *cmd, const char *arg, bson *out)
 Run a command that accepts a simple string key and value.
MONGO_EXPORT int mongo_cmd_drop_db (mongo *conn, const char *db)
 Drop a database.
MONGO_EXPORT int mongo_cmd_drop_collection (mongo *conn, const char *db, const char *collection, bson *out)
 Drop a collection.
MONGO_EXPORT int mongo_cmd_add_user (mongo *conn, const char *db, const char *user, const char *pass)
 Add a database user.
MONGO_EXPORT int mongo_cmd_authenticate (mongo *conn, const char *db, const char *user, const char *pass)
 Authenticate a user.
MONGO_EXPORT bson_bool_t mongo_cmd_ismaster (mongo *conn, bson *out)
 Check if the current server is a master.
MONGO_EXPORT int mongo_cmd_get_last_error (mongo *conn, const char *db, bson *out)
 Get the error for the last command with the current connection.
MONGO_EXPORT int mongo_cmd_get_prev_error (mongo *conn, const char *db, bson *out)
 Get the most recent error with the current connection.
MONGO_EXPORT void mongo_cmd_reset_error (mongo *conn, const char *db)
 Reset the error state for the connection.
MONGO_EXPORT mongomongo_create (void)
MONGO_EXPORT void mongo_dispose (mongo *conn)
MONGO_EXPORT int mongo_get_err (mongo *conn)
MONGO_EXPORT int mongo_is_connected (mongo *conn)
MONGO_EXPORT int mongo_get_op_timeout (mongo *conn)
MONGO_EXPORT const char * mongo_get_primary (mongo *conn)
MONGO_EXPORT int mongo_get_socket (mongo *conn)
MONGO_EXPORT int mongo_get_host_count (mongo *conn)
MONGO_EXPORT const char * mongo_get_host (mongo *conn, int i)
MONGO_EXPORT mongo_cursormongo_cursor_create (void)
MONGO_EXPORT void mongo_cursor_dispose (mongo_cursor *cursor)
MONGO_EXPORT int mongo_get_server_err (mongo *conn)
MONGO_EXPORT const char * mongo_get_server_err_string (mongo *conn)
MONGO_EXPORT void __mongo_set_error (mongo *conn, mongo_error_t err, const char *errstr, int errorcode)
 Set an error on a mongo connection object.
MONGO_EXPORT void mongo_clear_errors (mongo *conn)
 Clear all errors stored on a mongo connection object.

Detailed Description

Main MongoDB Declarations.


Enumeration Type Documentation

Enumerator:
MONGO_CURSOR_EXHAUSTED 

The cursor has no more results.

MONGO_CURSOR_INVALID 

The cursor has timed out or is not recognized.

MONGO_CURSOR_PENDING 

Tailable cursor still alive but no data.

MONGO_CURSOR_QUERY_FAIL 

The server returned an '$err' object, indicating query failure.

See conn->lasterrcode and conn->lasterrstr for details.

MONGO_CURSOR_BSON_ERROR 

Something is wrong with the BSON provided.

See conn->err for details.

Enumerator:
MONGO_CURSOR_MUST_FREE 

mongo_cursor_destroy should free cursor.

MONGO_CURSOR_QUERY_SENT 

Initial query has been sent.

Enumerator:
MONGO_TAILABLE 

Create a tailable cursor.

MONGO_SLAVE_OK 

Allow queries on a non-primary node.

MONGO_NO_CURSOR_TIMEOUT 

Disable cursor timeouts.

MONGO_AWAIT_DATA 

Momentarily block for more data.

MONGO_EXHAUST 

Stream in multiple 'more' packages.

MONGO_PARTIAL 

Allow reads even if a shard is down.

Enumerator:
MONGO_CONN_SUCCESS 

Connection success!

MONGO_CONN_NO_SOCKET 

Could not create a socket.

MONGO_CONN_FAIL 

An error occured while calling connect().

MONGO_CONN_ADDR_FAIL 

An error occured while calling getaddrinfo().

MONGO_CONN_NOT_MASTER 

Warning: connected to a non-master node (read-only).

MONGO_CONN_BAD_SET_NAME 

Given rs name doesn't match this replica set.

MONGO_CONN_NO_PRIMARY 

Can't find primary in replica set.

Connection closed.

MONGO_IO_ERROR 

An error occurred while reading or writing on the socket.

MONGO_SOCKET_ERROR 

Other socket error.

MONGO_READ_SIZE_ERROR 

The response is not the expected length.

MONGO_COMMAND_FAILED 

The command returned with 'ok' value of 0.

MONGO_WRITE_ERROR 

Write with given write_concern returned an error.

MONGO_NS_INVALID 

The name for the ns (database or collection) is invalid.

MONGO_BSON_INVALID 

BSON not valid for the specified op.

MONGO_BSON_NOT_FINISHED 

BSON object has not been finished.

MONGO_BSON_TOO_LARGE 

BSON object exceeds max BSON size.

MONGO_WRITE_CONCERN_INVALID 

Supplied write concern object is invalid.


Function Documentation

MONGO_EXPORT void __mongo_set_error ( mongo conn,
mongo_error_t  err,
const char *  errstr,
int  errorcode 
)

Set an error on a mongo connection object.

Mostly for internal use.

Parameters:
conna mongo connection object.
erra driver error code of mongo_error_t.
errstra string version of the error.
errorcodeCurrently errno or WSAGetLastError().
MONGO_EXPORT int mongo_check_connection ( mongo conn)

Ensure that this connection is healthy by performing a round-trip to the server.

Parameters:
conna mongo connection
Returns:
MONGO_OK if connected; otherwise, MONGO_ERROR.
MONGO_EXPORT void mongo_clear_errors ( mongo conn)

Clear all errors stored on a mongo connection object.

Parameters:
conna mongo connection object.
MONGO_EXPORT int mongo_client ( mongo conn,
const char *  host,
int  port 
)

Connect to a single MongoDB server.

Parameters:
conna mongo object.
hosta numerical network address or a network hostname.
portthe port to connect to.
Returns:
MONGO_OK or MONGO_ERROR on failure. On failure, a constant of type mongo_error_t will be set on the conn->err field.
MONGO_EXPORT int mongo_cmd_add_user ( mongo conn,
const char *  db,
const char *  user,
const char *  pass 
)

Add a database user.

Parameters:
conna mongo object.
dbthe database in which to add the user.
userthe user name
passthe user password
Returns:
MONGO_OK or MONGO_ERROR.
MONGO_EXPORT int mongo_cmd_authenticate ( mongo conn,
const char *  db,
const char *  user,
const char *  pass 
)

Authenticate a user.

Parameters:
conna mongo object.
dbthe database to authenticate against.
userthe user name to authenticate.
passthe user's password.
Returns:
MONGO_OK on sucess and MONGO_ERROR on failure.
MONGO_EXPORT int mongo_cmd_drop_collection ( mongo conn,
const char *  db,
const char *  collection,
bson out 
)

Drop a collection.

Parameters:
conna mongo object.
dbthe name of the database.
collectionthe name of the collection to drop.
outa BSON document containing the result of the command.
Returns:
true if the collection drop was successful.
MONGO_EXPORT int mongo_cmd_drop_db ( mongo conn,
const char *  db 
)

Drop a database.

Parameters:
conna mongo object.
dbthe name of the database to drop.
Returns:
MONGO_OK or an error code.
MONGO_EXPORT int mongo_cmd_get_last_error ( mongo conn,
const char *  db,
bson out 
)

Get the error for the last command with the current connection.

Parameters:
conna mongo object.
dbthe name of the database.
outa BSON object containing the error details.
Returns:
MONGO_OK if no error and MONGO_ERROR on error. On error, check the values of conn->lasterrcode and conn->lasterrstr for the error status.
MONGO_EXPORT int mongo_cmd_get_prev_error ( mongo conn,
const char *  db,
bson out 
)

Get the most recent error with the current connection.

Parameters:
conna mongo object.
dbthe name of the database.
outa BSON object containing the error details.
Returns:
MONGO_OK if no error and MONGO_ERROR on error. On error, check the values of conn->lasterrcode and conn->lasterrstr for the error status.
MONGO_EXPORT bson_bool_t mongo_cmd_ismaster ( mongo conn,
bson out 
)

Check if the current server is a master.

Parameters:
conna mongo object.
outa BSON result of the command.
Returns:
true if the server is a master.
MONGO_EXPORT void mongo_cmd_reset_error ( mongo conn,
const char *  db 
)

Reset the error state for the connection.

Parameters:
conna mongo object.
dbthe name of the database.
MONGO_EXPORT int mongo_connect ( mongo conn,
const char *  host,
int  port 
)

DEPRECATED - use mongo_client.

Connect to a single MongoDB server.

Parameters:
conna mongo object.
hosta numerical network address or a network hostname.
portthe port to connect to.
Returns:
MONGO_OK or MONGO_ERROR on failure. On failure, a constant of type mongo_error_t will be set on the conn->err field.
MONGO_EXPORT double mongo_count ( mongo conn,
const char *  db,
const char *  coll,
const bson query 
)

Count the number of documents in a collection matching a query.

Parameters:
conna mongo object.
dbthe db name.
collthe collection name.
querythe BSON query.
Returns:
the number of matching documents. If the command fails, MONGO_ERROR is returned.
MONGO_EXPORT int mongo_create_capped_collection ( mongo conn,
const char *  db,
const char *  collection,
int  size,
int  max,
bson out 
)

Create a capped collection.

Parameters:
conna mongo object.
nsthe namespace (e.g., "dbname.collectioname")
sizethe size of the capped collection in bytes.
maxthe max number of documents this collection is allowed to contain. If zero, this argument will be ignored and the server will use the collection's size to age document out. If using this option, ensure that the total size can contain this number of documents.
MONGO_EXPORT int mongo_create_index ( mongo conn,
const char *  ns,
const bson key,
int  options,
bson out 
)

Create a compound index.

Parameters:
conna mongo object.
nsthe namespace.
datathe bson index data.
optionsa bitfield for setting index options. Possibilities include MONGO_INDEX_UNIQUE, MONGO_INDEX_DROP_DUPS, MONGO_INDEX_BACKGROUND, and MONGO_INDEX_SPARSE.
outa bson document containing errors, if any.
Returns:
MONGO_OK if index is created successfully; otherwise, MONGO_ERROR.
MONGO_EXPORT bson_bool_t mongo_create_simple_index ( mongo conn,
const char *  ns,
const char *  field,
int  options,
bson out 
)

Create an index with a single key.

Parameters:
conna mongo object.
nsthe namespace.
fieldthe index key.
optionsindex options.
outa BSON document containing errors, if any.
Returns:
true if the index was created.
MONGO_EXPORT const bson* mongo_cursor_bson ( mongo_cursor cursor)

Return the current BSON object data as a const char*.

This is useful for creating bson iterators with bson_iterator_init.

Parameters:
cursor
MONGO_EXPORT const char* mongo_cursor_data ( mongo_cursor cursor)

Return the current BSON object data as a const char*.

This is useful for creating bson iterators with bson_iterator_init.

Parameters:
cursor
MONGO_EXPORT int mongo_cursor_destroy ( mongo_cursor cursor)

Destroy a cursor object.

When finished with a cursor, you must pass it to this function.

Parameters:
cursorthe cursor to destroy.
Returns:
MONGO_OK or an error code. On error, check cursor->conn->err for errors.
MONGO_EXPORT void mongo_cursor_init ( mongo_cursor cursor,
mongo conn,
const char *  ns 
)

Initalize a new cursor object.

Parameters:
cursor
nsthe namespace, represented as the the database name and collection name separated by a dot. e.g., "test.users"
MONGO_EXPORT int mongo_cursor_next ( mongo_cursor cursor)

Iterate the cursor, returning the next item.

When successful, the returned object will be stored in cursor->current;

Parameters:
cursor
Returns:
MONGO_OK. On error, returns MONGO_ERROR and sets cursor->err with a value of mongo_error_t.
MONGO_EXPORT void mongo_cursor_set_fields ( mongo_cursor cursor,
const bson fields 
)

Set the fields to return for this cursor.

If you want to return all fields, you need not set this value.

Parameters:
cursor
fieldsa bson object representing the fields to return. See http://www.mongodb.org/display/DOCS/Retrieving+a+Subset+of+Fields.
MONGO_EXPORT void mongo_cursor_set_limit ( mongo_cursor cursor,
int  limit 
)

Set the number of documents to return.

Parameters:
cursor
limit
MONGO_EXPORT void mongo_cursor_set_options ( mongo_cursor cursor,
int  options 
)

Set any of the available query options (e.g., MONGO_TAILABLE).

Parameters:
cursor
optionsa bitfield storing query options. See mongo_cursor_bitfield_t for available constants.
MONGO_EXPORT void mongo_cursor_set_query ( mongo_cursor cursor,
const bson query 
)

Set the bson object specifying this cursor's query spec.

If your query is the empty bson object "{}", then you need not set this value.

Parameters:
cursor
querya bson object representing the query spec. This may be either a simple query spec or a complex spec storing values for $query, $orderby, $hint, and/or $explain. See http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol for details.
MONGO_EXPORT void mongo_cursor_set_skip ( mongo_cursor cursor,
int  skip 
)

Set the number of documents to skip.

Parameters:
cursor
skip
MONGO_EXPORT void mongo_destroy ( mongo conn)

Close any existing connection to the server and free all allocated memory associated with the conn object.

You must always call this function when finished with the connection object.

Parameters:
conna mongo object.
MONGO_EXPORT void mongo_disconnect ( mongo conn)

Close the current connection to the server.

After calling this function, you may call mongo_reconnect with the same connection object.

Parameters:
conna mongo object.
MONGO_EXPORT mongo_cursor* mongo_find ( mongo conn,
const char *  ns,
const bson query,
const bson fields,
int  limit,
int  skip,
int  options 
)

Find documents in a MongoDB server.

Parameters:
conna mongo object.
nsthe namespace.
querythe bson query.
fieldsa bson document of fields to be returned.
limitthe maximum number of documents to retrun.
skipthe number of documents to skip.
optionsA bitfield containing cursor options.
Returns:
A cursor object allocated on the heap or NULL if an error has occurred. For finer-grained error checking, use the cursor builder API instead.
MONGO_EXPORT int mongo_find_one ( mongo conn,
const char *  ns,
const bson query,
const bson fields,
bson out 
)

Find a single document in a MongoDB server.

Parameters:
conna mongo object.
nsthe namespace.
querythe bson query.
fieldsa bson document of the fields to be returned.
outa bson document in which to put the query result.
MONGO_EXPORT void mongo_init ( mongo conn)

Initialize a new mongo connection object.

You must initialize each mongo object using this function.

Note:
When finished, you must pass this object to mongo_destroy( ).
Parameters:
conna mongo connection object allocated on the stack or heap.
MONGO_EXPORT int mongo_insert ( mongo conn,
const char *  ns,
const bson data,
mongo_write_concern custom_write_concern 
)

Insert a BSON document into a MongoDB server.

This function will fail if the supplied BSON struct is not UTF-8 or if the keys are invalid for insert (contain '.' or start with '$').

The default write concern set on the conn object will be used.

Parameters:
conna mongo object.
nsthe namespace.
datathe bson data.
custom_write_concerna write concern object that will override any write concern set on the conn object.
Returns:
MONGO_OK or MONGO_ERROR. If the conn->err field is MONGO_BSON_INVALID, check the err field on the bson struct for the reason.
MONGO_EXPORT int mongo_insert_batch ( mongo conn,
const char *  ns,
const bson **  data,
int  num,
mongo_write_concern custom_write_concern,
int  flags 
)

Insert a batch of BSON documents into a MongoDB server.

This function will fail if any of the documents to be inserted is invalid.

The default write concern set on the conn object will be used.

Parameters:
conna mongo object.
nsthe namespace.
datathe bson data.
numthe number of documents in data.
custom_write_concerna write concern object that will override any write concern set on the conn object.
flagsflags on this batch insert. Currently, this value may be 0 or MONGO_CONTINUE_ON_ERROR, which will cause the batch insert to continue even if a given insert in the batch fails.
Returns:
MONGO_OK or MONGO_ERROR.
void mongo_parse_host ( const char *  host_string,
mongo_host_port host_port 
)

Utility function for converting a host-port string to a mongo_host_port.

Parameters:
host_stringa string containing either a host or a host and port separated by a colon.
host_portthe mongo_host_port object to write the result to.
MONGO_EXPORT int mongo_reconnect ( mongo conn)

Try reconnecting to the server using the existing connection settings.

This function will disconnect the current socket. If you've authenticated, you'll need to re-authenticate after calling this function.

Parameters:
conna mongo object.
Returns:
MONGO_OK or MONGO_ERROR and set the conn->err field.
MONGO_EXPORT int mongo_remove ( mongo conn,
const char *  ns,
const bson cond,
mongo_write_concern custom_write_concern 
)

Remove a document from a MongoDB server.

The default write concern set on the conn object will be used.

Parameters:
conna mongo object.
nsthe namespace.
condthe bson query.
custom_write_concerna write concern object that will override any write concern set on the conn object.
Returns:
MONGO_OK or MONGO_ERROR with error stored in conn object.
MONGO_EXPORT void mongo_replica_set_add_seed ( mongo conn,
const char *  host,
int  port 
)

Add a seed node to the replica set connection object.

You must specify at least one seed node before connecting to a replica set.

Parameters:
conna mongo object.
hosta numerical network address or a network hostname.
portthe port to connect to.
MONGO_EXPORT int mongo_replica_set_client ( mongo conn)

Connect to a replica set.

Before passing a connection object to this function, you must already have called mongo_set_replica_set and mongo_replica_set_add_seed.

Parameters:
conna mongo object.
Returns:
MONGO_OK or MONGO_ERROR on failure. On failure, a constant of type mongo_conn_return_t will be set on the conn->err field.
MONGO_EXPORT void mongo_replica_set_init ( mongo conn,
const char *  name 
)

Set up this connection object for connecting to a replica set.

To connect, pass the object to mongo_replica_set_connect().

Parameters:
conna mongo object.
namethe name of the replica set to connect to.
MONGO_EXPORT void mongo_replset_add_seed ( mongo conn,
const char *  host,
int  port 
)

DEPRECATED - use mongo_replica_set_add_seed.

Add a seed node to the replica set connection object.

You must specify at least one seed node before connecting to a replica set.

Parameters:
conna mongo object.
hosta numerical network address or a network hostname.
portthe port to connect to.
MONGO_EXPORT int mongo_replset_connect ( mongo conn)

DEPRECATED - use mongo_replica_set_client.

Connect to a replica set.

Before passing a connection object to this function, you must already have called mongo_set_replset and mongo_replset_add_seed.

Parameters:
conna mongo object.
Returns:
MONGO_OK or MONGO_ERROR on failure. On failure, a constant of type mongo_conn_return_t will be set on the conn->err field.
MONGO_EXPORT void mongo_replset_init ( mongo conn,
const char *  name 
)

DEPRECATED - use mongo_replica_set_init.

Set up this connection object for connecting to a replica set. To connect, pass the object to mongo_replset_connect().

Parameters:
conna mongo object.
namethe name of the replica set to connect to.
MONGO_EXPORT int mongo_run_command ( mongo conn,
const char *  db,
const bson command,
bson out 
)

Run a command on a MongoDB server.

Parameters:
conna mongo object.
dbthe name of the database.
commandthe BSON command to run.
outthe BSON result of the command.
Returns:
MONGO_OK if the command ran without error.
MONGO_EXPORT int mongo_set_op_timeout ( mongo conn,
int  millis 
)

Set a timeout for operations on this connection.

This is a platform-specific feature, and only work on *nix system. You must also compile for linux to support this.

Parameters:
conna mongo object.
millistimeout time in milliseconds.
Returns:
MONGO_OK. On error, return MONGO_ERROR and set the conn->err field.
MONGO_EXPORT void mongo_set_write_concern ( mongo conn,
mongo_write_concern write_concern 
)

Specify the write concern object that this connection should use by default for all writes (inserts, updates, and deletes).

This value can be overridden by passing a write_concern object to any write function.

Parameters:
conna mongo object.
write_concernpointer to a write concern object.
MONGO_EXPORT int mongo_simple_int_command ( mongo conn,
const char *  db,
const char *  cmd,
int  arg,
bson out 
)

Run a command that accepts a simple string key and integer value.

Parameters:
conna mongo object.
dbthe name of the database.
cmdthe command to run.
argthe integer argument to the command.
outthe BSON result of the command.
Returns:
MONGO_OK or an error code.
MONGO_EXPORT int mongo_simple_str_command ( mongo conn,
const char *  db,
const char *  cmd,
const char *  arg,
bson out 
)

Run a command that accepts a simple string key and value.

Parameters:
conna mongo object.
dbthe name of the database.
cmdthe command to run.
argthe string argument to the command.
outthe BSON result of the command.
Returns:
true if the command ran without error.
MONGO_EXPORT int mongo_update ( mongo conn,
const char *  ns,
const bson cond,
const bson op,
int  flags,
mongo_write_concern custom_write_concern 
)

Update a document in a MongoDB server.

The default write concern set on the conn object will be used.

Parameters:
conna mongo object.
nsthe namespace.
condthe bson update query.
opthe bson update data.
flagsflags for the update.
custom_write_concerna write concern object that will override any write concern set on the conn object.
Returns:
MONGO_OK or MONGO_ERROR with error stored in conn object.
MONGO_EXPORT int mongo_validate_ns ( mongo conn,
const char *  ns 
)

Utility function for validation database and collection names.

Parameters:
conna mongo object.
Returns:
MONGO_OK or MONGO_ERROR on failure. On failure, a constant of type mongo_conn_return_t will be set on the conn->err field.
MONGO_EXPORT int mongo_write_concern_finish ( mongo_write_concern write_concern)

Finish this write concern object by serializing the literal getlasterror command that will be sent to the server.

You must call mongo_write_concern_destroy() to free the serialized BSON.

MONGO_EXPORT void mongo_write_concern_init ( mongo_write_concern write_concern)

Initialize a mongo_write_concern object.

Effectively zeroes out the struct.