MongoDBCDriver  0.7.1
mongo.h
Go to the documentation of this file.
00001 
00006 /*    Copyright 2009-2012 10gen Inc.
00007  *
00008  *    Licensed under the Apache License, Version 2.0 (the "License");
00009  *    you may not use this file except in compliance with the License.
00010  *    You may obtain a copy of the License at
00011  *
00012  *    http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  *    Unless required by applicable law or agreed to in writing, software
00015  *    distributed under the License is distributed on an "AS IS" BASIS,
00016  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  *    See the License for the specific language governing permissions and
00018  *    limitations under the License.
00019  */
00020 
00021 #ifndef MONGO_H_
00022 #define MONGO_H_
00023 
00024 #include "bson.h"
00025 
00026 MONGO_EXTERN_C_START
00027 
00028 #define MONGO_MAJOR 0
00029 #define MONGO_MINOR 7
00030 #define MONGO_PATCH 0
00031 
00032 #define MONGO_OK 0
00033 #define MONGO_ERROR -1
00034 
00035 #define MONGO_DEFAULT_PORT 27017
00036 
00037 #define MONGO_DEFAULT_MAX_BSON_SIZE 4 * 1024 * 1024
00038 
00039 #define MONGO_ERR_LEN 128
00040 
00041 typedef enum mongo_error_t {
00042     MONGO_CONN_SUCCESS = 0,  
00043     MONGO_CONN_NO_SOCKET,    
00044     MONGO_CONN_FAIL,         
00045     MONGO_CONN_ADDR_FAIL,    
00046     MONGO_CONN_NOT_MASTER,   
00047     MONGO_CONN_BAD_SET_NAME, 
00048     MONGO_CONN_NO_PRIMARY,   
00050     MONGO_IO_ERROR,          
00051     MONGO_SOCKET_ERROR,      
00052     MONGO_READ_SIZE_ERROR,   
00053     MONGO_COMMAND_FAILED,    
00054     MONGO_WRITE_ERROR,       
00055     MONGO_NS_INVALID,        
00056     MONGO_BSON_INVALID,      
00057     MONGO_BSON_NOT_FINISHED, 
00058     MONGO_BSON_TOO_LARGE,    
00059     MONGO_WRITE_CONCERN_INVALID 
00060 } mongo_error_t;
00061 
00062 typedef enum mongo_cursor_error_t {
00063     MONGO_CURSOR_EXHAUSTED,  
00064     MONGO_CURSOR_INVALID,    
00065     MONGO_CURSOR_PENDING,    
00066     MONGO_CURSOR_QUERY_FAIL, 
00068     MONGO_CURSOR_BSON_ERROR  
00070 } mongo_cursor_error_t;
00071 
00072 enum mongo_cursor_flags {
00073     MONGO_CURSOR_MUST_FREE = 1,      
00074     MONGO_CURSOR_QUERY_SENT = ( 1<<1 ) 
00075 };
00076 
00077 enum mongo_index_opts {
00078     MONGO_INDEX_UNIQUE = ( 1<<0 ),
00079     MONGO_INDEX_DROP_DUPS = ( 1<<2 ),
00080     MONGO_INDEX_BACKGROUND = ( 1<<3 ),
00081     MONGO_INDEX_SPARSE = ( 1<<4 )
00082 };
00083 
00084 enum mongo_update_opts {
00085     MONGO_UPDATE_UPSERT = 0x1,
00086     MONGO_UPDATE_MULTI = 0x2,
00087     MONGO_UPDATE_BASIC = 0x4
00088 };
00089 
00090 enum mongo_insert_opts {
00091     MONGO_CONTINUE_ON_ERROR = 0x1
00092 };
00093 
00094 enum mongo_cursor_opts {
00095     MONGO_TAILABLE = ( 1<<1 ),        
00096     MONGO_SLAVE_OK = ( 1<<2 ),        
00097     MONGO_NO_CURSOR_TIMEOUT = ( 1<<4 ), 
00098     MONGO_AWAIT_DATA = ( 1<<5 ),      
00099     MONGO_EXHAUST = ( 1<<6 ),         
00100     MONGO_PARTIAL = ( 1<<7 )          
00101 };
00102 
00103 enum mongo_operations {
00104     MONGO_OP_MSG = 1000,
00105     MONGO_OP_UPDATE = 2001,
00106     MONGO_OP_INSERT = 2002,
00107     MONGO_OP_QUERY = 2004,
00108     MONGO_OP_GET_MORE = 2005,
00109     MONGO_OP_DELETE = 2006,
00110     MONGO_OP_KILL_CURSORS = 2007
00111 };
00112 
00113 #pragma pack(1)
00114 typedef struct {
00115     int len;
00116     int id;
00117     int responseTo;
00118     int op;
00119 } mongo_header;
00120 
00121 typedef struct {
00122     mongo_header head;
00123     char data;
00124 } mongo_message;
00125 
00126 typedef struct {
00127     int flag; /* FIX THIS COMMENT non-zero on failure */
00128     int64_t cursorID;
00129     int start;
00130     int num;
00131 } mongo_reply_fields;
00132 
00133 typedef struct {
00134     mongo_header head;
00135     mongo_reply_fields fields;
00136     char objs;
00137 } mongo_reply;
00138 #pragma pack()
00139 
00140 typedef struct mongo_host_port {
00141     char host[255];
00142     int port;
00143     struct mongo_host_port *next;
00144 } mongo_host_port;
00145 
00146 typedef struct mongo_write_concern {
00147     int w;            
00148     int wtimeout;     
00149     int j;            
00150     int fsync;        
00151     const char *mode; 
00153     bson *cmd; 
00154 } mongo_write_concern;
00155 
00156 typedef struct {
00157     mongo_host_port *seeds;        
00158     mongo_host_port *hosts;        
00159     char *name;                    
00160     bson_bool_t primary_connected; 
00161 } mongo_replica_set;
00162 
00163 typedef struct mongo {
00164     mongo_host_port *primary;  
00165     mongo_replica_set *replica_set;    
00166     int sock;                  
00167     int flags;                 
00168     int conn_timeout_ms;       
00169     int op_timeout_ms;         
00170     int max_bson_size;         
00171     bson_bool_t connected;     
00172     mongo_write_concern *write_concern; 
00174     mongo_error_t err;          
00175     int errcode;                
00176     char errstr[MONGO_ERR_LEN]; 
00177     int lasterrcode;            
00178     char lasterrstr[MONGO_ERR_LEN]; 
00179 } mongo;
00180 
00181 typedef struct {
00182     mongo_reply *reply;  
00183     mongo *conn;       
00184     const char *ns;    
00185     int flags;         
00186     int seen;          
00187     bson current;      
00188     mongo_cursor_error_t err; 
00189     const bson *query; 
00190     const bson *fields;
00191     int options;       
00192     int limit;         
00193     int skip;          
00194 } mongo_cursor;
00195 
00196 /*********************************************************************
00197 Connection API
00198 **********************************************************************/
00199 
00202 MONGO_EXPORT void mongo_init_sockets( void );
00203 
00214 MONGO_EXPORT void mongo_init( mongo *conn );
00215 
00226 MONGO_EXPORT int mongo_client( mongo *conn , const char *host, int port );
00227 
00239 MONGO_EXPORT int mongo_connect( mongo *conn , const char *host, int port );
00240 
00248 MONGO_EXPORT void mongo_replica_set_init( mongo *conn, const char *name );
00249 
00258 MONGO_EXPORT void mongo_replset_init( mongo *conn, const char *name );
00259 
00269 MONGO_EXPORT void mongo_replica_set_add_seed( mongo *conn, const char *host, int port );
00270 
00281 MONGO_EXPORT void mongo_replset_add_seed( mongo *conn, const char *host, int port );
00282 
00290 void mongo_parse_host( const char *host_string, mongo_host_port *host_port );
00291 
00301 MONGO_EXPORT int mongo_validate_ns( mongo *conn, const char *ns );
00302 
00314 MONGO_EXPORT int mongo_replica_set_client( mongo *conn );
00315 
00328 MONGO_EXPORT int mongo_replset_connect( mongo *conn );
00329 
00340 MONGO_EXPORT int mongo_set_op_timeout( mongo *conn, int millis );
00341 
00350 MONGO_EXPORT int mongo_check_connection( mongo *conn );
00351 
00363 MONGO_EXPORT int mongo_reconnect( mongo *conn );
00364 
00372 MONGO_EXPORT void mongo_disconnect( mongo *conn );
00373 
00382 MONGO_EXPORT void mongo_destroy( mongo *conn );
00383 
00393 MONGO_EXPORT void mongo_set_write_concern( mongo *conn,
00394         mongo_write_concern *write_concern );
00395 
00396 
00397 /*********************************************************************
00398 CRUD API
00399 **********************************************************************/
00400 
00418 MONGO_EXPORT int mongo_insert( mongo *conn, const char *ns, const bson *data,
00419                                mongo_write_concern *custom_write_concern );
00420 
00440 MONGO_EXPORT int mongo_insert_batch( mongo *conn, const char *ns,
00441                                      const bson **data, int num, mongo_write_concern *custom_write_concern,
00442                                      int flags );
00443 
00460 MONGO_EXPORT int mongo_update( mongo *conn, const char *ns, const bson *cond,
00461                                const bson *op, int flags, mongo_write_concern *custom_write_concern );
00462 
00476 MONGO_EXPORT int mongo_remove( mongo *conn, const char *ns, const bson *cond,
00477                                mongo_write_concern *custom_write_concern );
00478 
00479 
00480 /*********************************************************************
00481 Write Concern API
00482 **********************************************************************/
00483 
00488 MONGO_EXPORT void mongo_write_concern_init( mongo_write_concern *write_concern );
00489 
00497 MONGO_EXPORT int mongo_write_concern_finish( mongo_write_concern *write_concern );
00498 
00503 MONGO_EXPORT void mongo_write_concern_destroy( mongo_write_concern *write_concern );
00504 
00505 /*********************************************************************
00506 Cursor API
00507 **********************************************************************/
00508 
00524 MONGO_EXPORT mongo_cursor *mongo_find( mongo *conn, const char *ns, const bson *query,
00525                                        const bson *fields, int limit, int skip, int options );
00526 
00534 MONGO_EXPORT void mongo_cursor_init( mongo_cursor *cursor, mongo *conn, const char *ns );
00535 
00547 MONGO_EXPORT void mongo_cursor_set_query( mongo_cursor *cursor, const bson *query );
00548 
00557 MONGO_EXPORT void mongo_cursor_set_fields( mongo_cursor *cursor, const bson *fields );
00558 
00565 MONGO_EXPORT void mongo_cursor_set_skip( mongo_cursor *cursor, int skip );
00566 
00573 MONGO_EXPORT void mongo_cursor_set_limit( mongo_cursor *cursor, int limit );
00574 
00582 MONGO_EXPORT void mongo_cursor_set_options( mongo_cursor *cursor, int options );
00583 
00590 MONGO_EXPORT const char *mongo_cursor_data( mongo_cursor *cursor );
00591 
00598 MONGO_EXPORT const bson *mongo_cursor_bson( mongo_cursor *cursor );
00599 
00609 MONGO_EXPORT int mongo_cursor_next( mongo_cursor *cursor );
00610 
00620 MONGO_EXPORT int mongo_cursor_destroy( mongo_cursor *cursor );
00621 
00632 /* out can be NULL if you don't care about results. useful for commands */
00633 MONGO_EXPORT int mongo_find_one( mongo *conn, const char *ns, const bson *query,
00634                                  const bson *fields, bson *out );
00635 
00636 
00637 /*********************************************************************
00638 Command API and Helpers
00639 **********************************************************************/
00640 
00652 MONGO_EXPORT double mongo_count( mongo *conn, const char *db, const char *coll,
00653                                  const bson *query );
00654 
00668 MONGO_EXPORT int mongo_create_index( mongo *conn, const char *ns,
00669                                      const bson *key, int options, bson *out );
00670 
00683 MONGO_EXPORT int mongo_create_capped_collection( mongo *conn, const char *db,
00684         const char *collection, int size, int max, bson *out );
00685 
00697 MONGO_EXPORT bson_bool_t mongo_create_simple_index( mongo *conn, const char *ns,
00698         const char *field, int options, bson *out );
00699 
00710 MONGO_EXPORT int mongo_run_command( mongo *conn, const char *db,
00711                                     const bson *command, bson *out );
00712 
00725 MONGO_EXPORT int mongo_simple_int_command( mongo *conn, const char *db,
00726         const char *cmd, int arg, bson *out );
00727 
00740 MONGO_EXPORT int mongo_simple_str_command( mongo *conn, const char *db,
00741         const char *cmd, const char *arg, bson *out );
00742 
00751 MONGO_EXPORT int mongo_cmd_drop_db( mongo *conn, const char *db );
00752 
00763 MONGO_EXPORT int mongo_cmd_drop_collection( mongo *conn, const char *db,
00764         const char *collection, bson *out );
00765 
00776 MONGO_EXPORT int mongo_cmd_add_user( mongo *conn, const char *db,
00777                                      const char *user, const char *pass );
00778 
00789 MONGO_EXPORT int mongo_cmd_authenticate( mongo *conn, const char *db,
00790         const char *user, const char *pass );
00791 
00800 /* return value is master status */
00801 MONGO_EXPORT bson_bool_t mongo_cmd_ismaster( mongo *conn, bson *out );
00802 
00813 MONGO_EXPORT int mongo_cmd_get_last_error( mongo *conn, const char *db, bson *out );
00814 
00825 MONGO_EXPORT int mongo_cmd_get_prev_error( mongo *conn, const char *db, bson *out );
00826 
00833 MONGO_EXPORT void mongo_cmd_reset_error( mongo *conn, const char *db );
00834 
00835 
00836 /*********************************************************************
00837 Utility API
00838 **********************************************************************/
00839 
00840 MONGO_EXPORT mongo* mongo_create( void );
00841 MONGO_EXPORT void mongo_dispose(mongo* conn);
00842 MONGO_EXPORT int mongo_get_err(mongo* conn);
00843 MONGO_EXPORT int mongo_is_connected(mongo* conn);
00844 MONGO_EXPORT int mongo_get_op_timeout(mongo* conn);
00845 MONGO_EXPORT const char* mongo_get_primary(mongo* conn);
00846 MONGO_EXPORT int mongo_get_socket(mongo* conn) ;
00847 MONGO_EXPORT int mongo_get_host_count(mongo* conn);
00848 MONGO_EXPORT const char* mongo_get_host(mongo* conn, int i);
00849 MONGO_EXPORT mongo_cursor* mongo_cursor_create( void );
00850 MONGO_EXPORT void mongo_cursor_dispose(mongo_cursor* cursor);
00851 MONGO_EXPORT int  mongo_get_server_err(mongo* conn);
00852 MONGO_EXPORT const char*  mongo_get_server_err_string(mongo* conn);
00853 
00862 MONGO_EXPORT void __mongo_set_error( mongo *conn, mongo_error_t err,
00863                                      const char *errstr, int errorcode );
00869 MONGO_EXPORT void mongo_clear_errors( mongo *conn );
00870 
00871 MONGO_EXTERN_C_END
00872 
00873 #endif