MongoDBCDriver  0.7.1
bson.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 BSON_H_
00022 #define BSON_H_
00023 
00024 #include <time.h>
00025 #include <string.h>
00026 #include <stdio.h>
00027 #include <stdlib.h>
00028 #include <stdarg.h>
00029 
00030 #ifdef __GNUC__
00031 #define MONGO_INLINE static __inline__
00032 #define MONGO_EXPORT
00033 #else
00034 #define MONGO_INLINE static
00035 #ifdef MONGO_STATIC_BUILD
00036 #define MONGO_EXPORT
00037 #elif defined(MONGO_DLL_BUILD)
00038 #define MONGO_EXPORT __declspec(dllexport)
00039 #else
00040 #define MONGO_EXPORT __declspec(dllimport)
00041 #endif
00042 #endif
00043 
00044 #ifdef __cplusplus
00045 #define MONGO_EXTERN_C_START extern "C" {
00046 #define MONGO_EXTERN_C_END }
00047 #else
00048 #define MONGO_EXTERN_C_START
00049 #define MONGO_EXTERN_C_END
00050 #endif
00051 
00052 #if defined(MONGO_HAVE_STDINT) || __STDC_VERSION__ >= 199901L
00053 #include <stdint.h>
00054 #elif defined(MONGO_HAVE_UNISTD)
00055 #include <unistd.h>
00056 #elif defined(MONGO_USE__INT64)
00057 typedef __int64 int64_t;
00058 typedef unsigned __int64 uint64_t;
00059 #elif defined(MONGO_USE_LONG_LONG_INT)
00060 typedef long long int int64_t;
00061 typedef unsigned long long int uint64_t;
00062 #else
00063 #error Must compile with c99 or define MONGO_HAVE_STDINT, MONGO_HAVE_UNISTD, MONGO_USE__INT64, or MONGO_USE_LONG_LONG_INT.
00064 #endif
00065 
00066 #ifdef MONGO_BIG_ENDIAN
00067 #define bson_little_endian64(out, in) ( bson_swap_endian64(out, in) )
00068 #define bson_little_endian32(out, in) ( bson_swap_endian32(out, in) )
00069 #define bson_big_endian64(out, in) ( memcpy(out, in, 8) )
00070 #define bson_big_endian32(out, in) ( memcpy(out, in, 4) )
00071 #else
00072 #define bson_little_endian64(out, in) ( memcpy(out, in, 8) )
00073 #define bson_little_endian32(out, in) ( memcpy(out, in, 4) )
00074 #define bson_big_endian64(out, in) ( bson_swap_endian64(out, in) )
00075 #define bson_big_endian32(out, in) ( bson_swap_endian32(out, in) )
00076 #endif
00077 
00078 MONGO_EXTERN_C_START
00079 
00080 #define BSON_OK 0
00081 #define BSON_ERROR -1
00082 
00083 enum bson_error_t {
00084     BSON_SIZE_OVERFLOW = 1 
00085 };
00086 
00087 enum bson_validity_t {
00088     BSON_VALID = 0,                 
00089     BSON_NOT_UTF8 = ( 1<<1 ),       
00090     BSON_FIELD_HAS_DOT = ( 1<<2 ),  
00091     BSON_FIELD_INIT_DOLLAR = ( 1<<3 ), 
00092     BSON_ALREADY_FINISHED = ( 1<<4 )  
00093 };
00094 
00095 enum bson_binary_subtype_t {
00096     BSON_BIN_BINARY = 0,
00097     BSON_BIN_FUNC = 1,
00098     BSON_BIN_BINARY_OLD = 2,
00099     BSON_BIN_UUID = 3,
00100     BSON_BIN_MD5 = 5,
00101     BSON_BIN_USER = 128
00102 };
00103 
00104 typedef enum {
00105     BSON_EOO = 0,
00106     BSON_DOUBLE = 1,
00107     BSON_STRING = 2,
00108     BSON_OBJECT = 3,
00109     BSON_ARRAY = 4,
00110     BSON_BINDATA = 5,
00111     BSON_UNDEFINED = 6,
00112     BSON_OID = 7,
00113     BSON_BOOL = 8,
00114     BSON_DATE = 9,
00115     BSON_NULL = 10,
00116     BSON_REGEX = 11,
00117     BSON_DBREF = 12, 
00118     BSON_CODE = 13,
00119     BSON_SYMBOL = 14,
00120     BSON_CODEWSCOPE = 15,
00121     BSON_INT = 16,
00122     BSON_TIMESTAMP = 17,
00123     BSON_LONG = 18
00124 } bson_type;
00125 
00126 typedef int bson_bool_t;
00127 
00128 typedef struct {
00129     const char *cur;
00130     bson_bool_t first;
00131 } bson_iterator;
00132 
00133 typedef struct {
00134     char *data;    
00135     char *cur;     
00136     int dataSize;  
00137     bson_bool_t finished; 
00138     int stack[32];        
00139     int stackPos;         
00140     int err; 
00141     char *errstr; 
00142 } bson;
00143 
00144 #pragma pack(1)
00145 typedef union {
00146     char bytes[12];
00147     int ints[3];
00148 } bson_oid_t;
00149 #pragma pack()
00150 
00151 typedef int64_t bson_date_t; /* milliseconds since epoch UTC */
00152 
00153 typedef struct {
00154     int i; /* increment */
00155     int t; /* time in seconds */
00156 } bson_timestamp_t;
00157 
00158 /* ----------------------------
00159    READING
00160    ------------------------------ */
00161 
00162 MONGO_EXPORT bson* bson_create( void );
00163 MONGO_EXPORT void  bson_dispose(bson* b);
00164 
00172 MONGO_EXPORT int bson_size( const bson *b );
00173 MONGO_EXPORT int bson_buffer_size( const bson *b );
00174 
00180 MONGO_EXPORT void bson_print( const bson *b );
00181 
00187 MONGO_EXPORT const char *bson_data( const bson *b );
00188 
00195 MONGO_EXPORT void bson_print_raw( const char *bson , int depth );
00196 
00206 MONGO_EXPORT bson_type bson_find( bson_iterator *it, const bson *obj, const char *name );
00207 
00208 
00209 MONGO_EXPORT bson_iterator* bson_iterator_create( void );
00210 MONGO_EXPORT void bson_iterator_dispose(bson_iterator*);
00217 MONGO_EXPORT void bson_iterator_init( bson_iterator *i , const bson *b );
00218 
00226 MONGO_EXPORT void bson_iterator_from_buffer( bson_iterator *i, const char *buffer );
00227 
00228 /* more returns true for eoo. best to loop with bson_iterator_next(&it) */
00236 MONGO_EXPORT bson_bool_t bson_iterator_more( const bson_iterator *i );
00237 
00245 MONGO_EXPORT bson_type bson_iterator_next( bson_iterator *i );
00246 
00254 MONGO_EXPORT bson_type bson_iterator_type( const bson_iterator *i );
00255 
00263 MONGO_EXPORT const char *bson_iterator_key( const bson_iterator *i );
00264 
00272 MONGO_EXPORT const char *bson_iterator_value( const bson_iterator *i );
00273 
00274 /* these convert to the right type (return 0 if non-numeric) */
00283 MONGO_EXPORT double bson_iterator_double( const bson_iterator *i );
00284 
00292 MONGO_EXPORT int bson_iterator_int( const bson_iterator *i );
00293 
00301 MONGO_EXPORT int64_t bson_iterator_long( const bson_iterator *i );
00302 
00303 /* return the bson timestamp as a whole or in parts */
00312 MONGO_EXPORT bson_timestamp_t bson_iterator_timestamp( const bson_iterator *i );
00313 MONGO_EXPORT int bson_iterator_timestamp_time( const bson_iterator *i );
00314 MONGO_EXPORT int bson_iterator_timestamp_increment( const bson_iterator *i );
00315 
00324 /* false: boolean false, 0 in any type, or null */
00325 /* true: anything else (even empty strings and objects) */
00326 MONGO_EXPORT bson_bool_t bson_iterator_bool( const bson_iterator *i );
00327 
00336 /* these assume you are using the right type */
00337 double bson_iterator_double_raw( const bson_iterator *i );
00338 
00347 int bson_iterator_int_raw( const bson_iterator *i );
00348 
00357 int64_t bson_iterator_long_raw( const bson_iterator *i );
00358 
00367 bson_bool_t bson_iterator_bool_raw( const bson_iterator *i );
00368 
00377 MONGO_EXPORT bson_oid_t *bson_iterator_oid( const bson_iterator *i );
00378 
00387 /* these can also be used with bson_code and bson_symbol*/
00388 MONGO_EXPORT const char *bson_iterator_string( const bson_iterator *i );
00389 
00398 int bson_iterator_string_len( const bson_iterator *i );
00399 
00409 /* works with bson_code, bson_codewscope, and BSON_STRING */
00410 /* returns NULL for everything else */
00411 MONGO_EXPORT const char *bson_iterator_code( const bson_iterator *i );
00412 
00419 /* calls bson_empty on scope if not a bson_codewscope */
00420 MONGO_EXPORT void bson_iterator_code_scope( const bson_iterator *i, bson *scope );
00421 
00430 /* both of these only work with bson_date */
00431 MONGO_EXPORT bson_date_t bson_iterator_date( const bson_iterator *i );
00432 
00441 MONGO_EXPORT time_t bson_iterator_time_t( const bson_iterator *i );
00442 
00451 MONGO_EXPORT int bson_iterator_bin_len( const bson_iterator *i );
00452 
00461 MONGO_EXPORT char bson_iterator_bin_type( const bson_iterator *i );
00462 
00471 MONGO_EXPORT const char *bson_iterator_bin_data( const bson_iterator *i );
00472 
00481 MONGO_EXPORT const char *bson_iterator_regex( const bson_iterator *i );
00482 
00491 MONGO_EXPORT const char *bson_iterator_regex_opts( const bson_iterator *i );
00492 
00493 /* these work with BSON_OBJECT and BSON_ARRAY */
00501 MONGO_EXPORT void bson_iterator_subobject( const bson_iterator *i, bson *sub );
00502 
00509 MONGO_EXPORT void bson_iterator_subiterator( const bson_iterator *i, bson_iterator *sub );
00510 
00511 /* str must be at least 24 hex chars + null byte */
00518 MONGO_EXPORT void bson_oid_from_string( bson_oid_t *oid, const char *str );
00519 
00526 MONGO_EXPORT void bson_oid_to_string( const bson_oid_t *oid, char *str );
00527 
00533 MONGO_EXPORT void bson_oid_gen( bson_oid_t *oid );
00534 
00541 MONGO_EXPORT void bson_set_oid_fuzz( int ( *func )( void ) );
00542 
00550 MONGO_EXPORT void bson_set_oid_inc( int ( *func )( void ) );
00551 
00557 MONGO_EXPORT time_t bson_oid_generated_time( bson_oid_t *oid ); /* Gives the time the OID was created */
00558 
00559 /* ----------------------------
00560    BUILDING
00561    ------------------------------ */
00562 
00571 MONGO_EXPORT void bson_init( bson *b );
00572 
00582 int bson_init_data( bson *b , char *data );
00583 int bson_init_finished_data( bson *b, char *data ) ;
00584 
00594 void bson_init_size( bson *b, int size );
00595 
00605 int bson_ensure_space( bson *b, const int bytesNeeded );
00606 
00615 MONGO_EXPORT int bson_finish( bson *b );
00616 
00623 MONGO_EXPORT void bson_destroy( bson *b );
00624 
00632 /* returns pointer to static empty bson object */
00633 MONGO_EXPORT bson *bson_empty( bson *obj );
00634 
00643 MONGO_EXPORT int bson_copy( bson *out, const bson *in ); /* puts data in new buffer. NOOP if out==NULL */
00644 
00654 MONGO_EXPORT int bson_append_oid( bson *b, const char *name, const bson_oid_t *oid );
00655 
00664 MONGO_EXPORT int bson_append_new_oid( bson *b, const char *name );
00665 
00675 MONGO_EXPORT int bson_append_int( bson *b, const char *name, const int i );
00676 
00686 MONGO_EXPORT int bson_append_long( bson *b, const char *name, const int64_t i );
00687 
00697 MONGO_EXPORT int bson_append_double( bson *b, const char *name, const double d );
00698 
00708 MONGO_EXPORT int bson_append_string( bson *b, const char *name, const char *str );
00709 
00720 MONGO_EXPORT int bson_append_string_n( bson *b, const char *name, const char *str, int len );
00721 
00731 MONGO_EXPORT int bson_append_symbol( bson *b, const char *name, const char *str );
00732 
00743 MONGO_EXPORT int bson_append_symbol_n( bson *b, const char *name, const char *str, int len );
00744 
00755 MONGO_EXPORT int bson_append_code( bson *b, const char *name, const char *str );
00756 
00767 MONGO_EXPORT int bson_append_code_n( bson *b, const char *name, const char *str, int len );
00768 
00779 MONGO_EXPORT int bson_append_code_w_scope( bson *b, const char *name, const char *code, const bson *scope );
00780 
00792 MONGO_EXPORT int bson_append_code_w_scope_n( bson *b, const char *name, const char *code, int size, const bson *scope );
00793 
00805 MONGO_EXPORT int bson_append_binary( bson *b, const char *name, char type, const char *str, int len );
00806 
00816 MONGO_EXPORT int bson_append_bool( bson *b, const char *name, const bson_bool_t v );
00817 
00826 MONGO_EXPORT int bson_append_null( bson *b, const char *name );
00827 
00836 MONGO_EXPORT int bson_append_undefined( bson *b, const char *name );
00837 
00848 MONGO_EXPORT int bson_append_regex( bson *b, const char *name, const char *pattern, const char *opts );
00849 
00859 MONGO_EXPORT int bson_append_bson( bson *b, const char *name, const bson *bson );
00860 
00870 MONGO_EXPORT int bson_append_element( bson *b, const char *name_or_null, const bson_iterator *elem );
00871 
00881 MONGO_EXPORT int bson_append_timestamp( bson *b, const char *name, bson_timestamp_t *ts );
00882 MONGO_EXPORT int bson_append_timestamp2( bson *b, const char *name, int time, int increment );
00883 
00884 /* these both append a bson_date */
00894 MONGO_EXPORT int bson_append_date( bson *b, const char *name, bson_date_t millis );
00895 
00905 MONGO_EXPORT int bson_append_time_t( bson *b, const char *name, time_t secs );
00906 
00915 MONGO_EXPORT int bson_append_start_object( bson *b, const char *name );
00916 
00925 MONGO_EXPORT int bson_append_start_array( bson *b, const char *name );
00926 
00934 MONGO_EXPORT int bson_append_finish_object( bson *b );
00935 
00944 MONGO_EXPORT int bson_append_finish_array( bson *b );
00945 
00946 void bson_numstr( char *str, int i );
00947 
00948 void bson_incnumstr( char *str );
00949 
00950 /* Error handling and standard library function over-riding. */
00951 /* -------------------------------------------------------- */
00952 
00953 /* bson_err_handlers shouldn't return!!! */
00954 typedef void( *bson_err_handler )( const char *errmsg );
00955 
00956 typedef int (*bson_printf_func)( const char *, ... );
00957 typedef int (*bson_fprintf_func)( FILE *, const char *, ... );
00958 typedef int (*bson_sprintf_func)( char *, const char *, ... );
00959 
00960 extern void *( *bson_malloc_func )( size_t );
00961 extern void *( *bson_realloc_func )( void *, size_t );
00962 extern void ( *bson_free_func )( void * );
00963 
00964 extern bson_printf_func bson_printf;
00965 extern bson_fprintf_func bson_fprintf;
00966 extern bson_sprintf_func bson_sprintf;
00967 extern bson_printf_func bson_errprintf;
00968 
00969 MONGO_EXPORT void bson_free( void *ptr );
00970 
00980 MONGO_EXPORT void *bson_malloc( int size );
00981 
00993 void *bson_realloc( void *ptr, int size );
00994 
01002 MONGO_EXPORT bson_err_handler set_bson_err_handler( bson_err_handler func );
01003 
01004 /* does nothing if ok != 0 */
01010 void bson_fatal( int ok );
01011 
01018 void bson_fatal_msg( int ok, const char *msg );
01019 
01025 void bson_builder_error( bson *b );
01026 
01032 MONGO_EXPORT double bson_int64_to_double( int64_t i64 );
01033 
01034 MONGO_EXPORT void bson_swap_endian32( void *outp, const void *inp );
01035 MONGO_EXPORT void bson_swap_endian64( void *outp, const void *inp );
01036 
01037 MONGO_EXTERN_C_END
01038 #endif