rpm  5.4.15
bson.h
Go to the documentation of this file.
1 
6 /* Copyright 2009-2012 10gen Inc.
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 
21 #ifndef H_BSON
22 #define H_BSON
23 
24 #include <stdint.h>
25 #include <stdio.h>
26 #include <time.h>
27 
28 #ifdef __GNUC__
29 #define MONGO_INLINE static __inline__
30 #define MONGO_EXPORT
31 #elif defined(__sun) && defined(__SUNPRO_C)
32 /* Solaris with Sun/Oracle Studio */
33 #define MONGO_INLINE static inline
34 #define MONGO_EXPORT
35 #else
36 #define MONGO_INLINE static
37 #ifdef MONGO_STATIC_BUILD
38 #define MONGO_EXPORT
39 #elif defined(MONGO_DLL_BUILD)
40 #define MONGO_EXPORT __declspec(dllexport)
41 #else
42 #define MONGO_EXPORT __declspec(dllimport)
43 #endif
44 #endif
45 
46 #ifdef __cplusplus
47 #define MONGO_EXTERN_C_START extern "C" {
48 #define MONGO_EXTERN_C_END }
49 #else
50 #define MONGO_EXTERN_C_START
51 #define MONGO_EXTERN_C_END
52 #endif
53 
55 
56 #define BSON_OK 0
57 #define BSON_ERROR -1
58 
60  BSON_SIZE_OVERFLOW = (1 << 0),
61  BSON_ALREADY_FINISHED = (1 << 4),
62  BSON_NOT_IN_SUBOBJECT = (1 << 5),
64 };
65 
67  BSON_VALID = 0,
68  BSON_NOT_UTF8 = (1 << 1),
69  BSON_FIELD_HAS_DOT = (1 << 2),
71 };
72 
80 };
81 
82 typedef enum {
83  BSON_EOO = 0,
90  BSON_OID = 7,
91  BSON_BOOL = 8,
92  BSON_DATE = 9,
93  BSON_NULL = 10,
94  BSON_REGEX = 11,
95  BSON_DBREF = 12,
96  BSON_CODE = 13,
99  BSON_INT = 16,
101  BSON_LONG = 18,
102  BSON_MAXKEY = 127,
104 } bson_type;
105 
106 typedef int bson_bool_t;
107 
108 typedef struct {
109  const char *cur;
110  bson_bool_t first;
111 } bson_iterator;
112 
113 typedef struct {
114  char *data;
115  char *cur;
116  int dataSize;
117  bson_bool_t finished;
118  bson_bool_t ownsData;
119  int err;
120  int stackSize;
121  int stackPos;
122  size_t* stackPtr;
123  size_t stack[32];
125 } bson;
126 
127 #pragma pack(1)
128 typedef union {
129  char bytes[12];
130  int ints[3];
131 } bson_oid_t;
132 #pragma pack()
133 
134 typedef int64_t bson_date_t; /* milliseconds since epoch UTC */
135 
136 typedef struct {
137  int i; /* increment */
138  int t; /* time in seconds */
140 
141 extern void bson_little_endian64(void* outp, const void* inp);
142 extern void bson_little_endian32(void* outp, const void* inp);
143 extern void bson_big_endian64(void* outp, const void* inp);
144 extern void bson_big_endian32(void* outp, const void* inp);
145 
146 /* ----------------------------
147  READING
148  ------------------------------ */
149 
160 MONGO_EXPORT void bson_init_zero( bson *b );
161 
171 MONGO_EXPORT bson* bson_alloc( void );
172 
178 MONGO_EXPORT void bson_dealloc( bson* b );
179 
193 int bson_init_finished_data( bson *b, char *data, bson_bool_t ownsData );
194 
207 int bson_init_finished_data_with_copy( bson *b, const char *data );
208 
216 MONGO_EXPORT int bson_size( const bson *b );
217 
225 MONGO_EXPORT size_t bson_buffer_size( const bson *b );
226 
232 MONGO_EXPORT void bson_print( const bson *b );
233 
239 MONGO_EXPORT const char *bson_data( const bson *b );
240 
250 MONGO_EXPORT int bson_has_data( const bson *b );
251 
258 MONGO_EXPORT void bson_print_raw( const char *bson , int depth );
259 
269 MONGO_EXPORT bson_type bson_find( bson_iterator *it, const bson *obj, const char *name );
270 
271 
272 MONGO_EXPORT bson_iterator* bson_iterator_alloc( void );
273 MONGO_EXPORT void bson_iterator_dealloc(bson_iterator*);
280 MONGO_EXPORT void bson_iterator_init( bson_iterator *i , const bson *b );
281 
289 MONGO_EXPORT void bson_iterator_from_buffer( bson_iterator *i, const char *buffer );
290 
291 /* more returns true for eoo. best to loop with bson_iterator_next(&it) */
299 MONGO_EXPORT bson_bool_t bson_iterator_more( const bson_iterator *i );
300 
308 MONGO_EXPORT bson_type bson_iterator_next( bson_iterator *i );
309 
317 MONGO_EXPORT bson_type bson_iterator_type( const bson_iterator *i );
318 
326 MONGO_EXPORT const char *bson_iterator_key( const bson_iterator *i );
327 
335 MONGO_EXPORT const char *bson_iterator_value( const bson_iterator *i );
336 
337 /* these convert to the right type (return 0 if non-numeric) */
346 MONGO_EXPORT double bson_iterator_double( const bson_iterator *i );
347 
355 MONGO_EXPORT int bson_iterator_int( const bson_iterator *i );
356 
364 MONGO_EXPORT int64_t bson_iterator_long( const bson_iterator *i );
365 
366 /* return the bson timestamp as a whole or in parts */
375 MONGO_EXPORT bson_timestamp_t bson_iterator_timestamp( const bson_iterator *i );
376 MONGO_EXPORT int bson_iterator_timestamp_time( const bson_iterator *i );
377 MONGO_EXPORT int bson_iterator_timestamp_increment( const bson_iterator *i );
378 
387 /* false: boolean false, 0 in any type, or null */
388 /* true: anything else (even empty strings and objects) */
389 MONGO_EXPORT bson_bool_t bson_iterator_bool( const bson_iterator *i );
390 
399 /* these assume you are using the right type */
400 double bson_iterator_double_raw( const bson_iterator *i );
401 
411 
420 int64_t bson_iterator_long_raw( const bson_iterator *i );
421 
430 bson_bool_t bson_iterator_bool_raw( const bson_iterator *i );
431 
440 MONGO_EXPORT bson_oid_t *bson_iterator_oid( const bson_iterator *i );
441 
450 /* these can also be used with bson_code and bson_symbol*/
451 MONGO_EXPORT const char *bson_iterator_string( const bson_iterator *i );
452 
462 
472 /* works with bson_code, bson_codewscope, and BSON_STRING */
473 /* returns NULL for everything else */
474 MONGO_EXPORT const char *bson_iterator_code( const bson_iterator *i );
475 
491 MONGO_EXPORT void bson_iterator_code_scope_init( const bson_iterator *i, bson *scope, bson_bool_t copyData );
492 
501 /* both of these only work with bson_date */
502 MONGO_EXPORT bson_date_t bson_iterator_date( const bson_iterator *i );
503 
512 MONGO_EXPORT time_t bson_iterator_time_t( const bson_iterator *i );
513 
522 MONGO_EXPORT int bson_iterator_bin_len( const bson_iterator *i );
523 
532 MONGO_EXPORT char bson_iterator_bin_type( const bson_iterator *i );
533 
542 MONGO_EXPORT const char *bson_iterator_bin_data( const bson_iterator *i );
543 
552 MONGO_EXPORT const char *bson_iterator_regex( const bson_iterator *i );
553 
562 MONGO_EXPORT const char *bson_iterator_regex_opts( const bson_iterator *i );
563 
564 /* these work with BSON_OBJECT and BSON_ARRAY */
576 MONGO_EXPORT void bson_iterator_subobject_init( const bson_iterator *i, bson *sub, bson_bool_t copyData );
577 
584 MONGO_EXPORT void bson_iterator_subiterator( const bson_iterator *i, bson_iterator *sub );
585 
586 /* str must be at least 24 hex chars + null byte */
593 MONGO_EXPORT void bson_oid_from_string( bson_oid_t *oid, const char *str );
594 
601 MONGO_EXPORT void bson_oid_to_string( const bson_oid_t *oid, char *str );
602 
608 MONGO_EXPORT void bson_oid_gen( bson_oid_t *oid );
609 
616 MONGO_EXPORT void bson_set_oid_fuzz( int ( *func )( void ) );
617 
625 MONGO_EXPORT void bson_set_oid_inc( int ( *func )( void ) );
626 
632 MONGO_EXPORT time_t bson_oid_generated_time( bson_oid_t *oid ); /* Gives the time the OID was created */
633 
634 /* ----------------------------
635  BUILDING
636  ------------------------------ */
637 
649 MONGO_EXPORT int bson_init( bson *b );
650 
663 int bson_init_size( bson *b, int size );
664 
684 int bson_init_unfinished_data( bson *b, char *data, int dataSize, bson_bool_t ownsData );
685 
695 int bson_ensure_space( bson *b, const size_t bytesNeeded );
696 
705 MONGO_EXPORT int bson_finish( bson *b );
706 
713 MONGO_EXPORT void bson_destroy( bson *b );
714 
726 MONGO_EXPORT bson_bool_t bson_init_empty( bson *obj );
727 
736 MONGO_EXPORT const bson *bson_shared_empty( void );
737 
746 MONGO_EXPORT int bson_copy( bson *out, const bson *in ); /* puts data in new buffer. NOOP if out==NULL */
747 
757 MONGO_EXPORT int bson_append_oid( bson *b, const char *name, const bson_oid_t *oid );
758 
767 MONGO_EXPORT int bson_append_new_oid( bson *b, const char *name );
768 
778 MONGO_EXPORT int bson_append_int( bson *b, const char *name, const int i );
779 
789 MONGO_EXPORT int bson_append_long( bson *b, const char *name, const int64_t i );
790 
800 MONGO_EXPORT int bson_append_double( bson *b, const char *name, const double d );
801 
811 MONGO_EXPORT int bson_append_string( bson *b, const char *name, const char *str );
812 
823 MONGO_EXPORT int bson_append_string_n( bson *b, const char *name, const char *str, size_t len );
824 
834 MONGO_EXPORT int bson_append_symbol( bson *b, const char *name, const char *str );
835 
846 MONGO_EXPORT int bson_append_symbol_n( bson *b, const char *name, const char *str, size_t len );
847 
858 MONGO_EXPORT int bson_append_code( bson *b, const char *name, const char *str );
859 
870 MONGO_EXPORT int bson_append_code_n( bson *b, const char *name, const char *str, size_t len );
871 
882 MONGO_EXPORT int bson_append_code_w_scope( bson *b, const char *name, const char *code, const bson *scope );
883 
895 MONGO_EXPORT int bson_append_code_w_scope_n( bson *b, const char *name, const char *code, size_t size, const bson *scope );
896 
908 MONGO_EXPORT int bson_append_binary( bson *b, const char *name, char type, const char *str, size_t len );
909 
919 MONGO_EXPORT int bson_append_bool( bson *b, const char *name, const bson_bool_t v );
920 
929 MONGO_EXPORT int bson_append_null( bson *b, const char *name );
930 
939 MONGO_EXPORT int bson_append_undefined( bson *b, const char *name );
940 
949 MONGO_EXPORT int bson_append_maxkey( bson *b, const char *name );
950 
959 MONGO_EXPORT int bson_append_minkey( bson *b, const char *name );
960 
971 MONGO_EXPORT int bson_append_regex( bson *b, const char *name, const char *pattern, const char *opts );
972 
982 MONGO_EXPORT int bson_append_bson( bson *b, const char *name, const bson *bson );
983 
993 MONGO_EXPORT int bson_append_element( bson *b, const char *name_or_null, const bson_iterator *elem );
994 
1004 MONGO_EXPORT int bson_append_timestamp( bson *b, const char *name, bson_timestamp_t *ts );
1005 MONGO_EXPORT int bson_append_timestamp2( bson *b, const char *name, int time, int increment );
1006 
1007 /* these both append a bson_date */
1017 MONGO_EXPORT int bson_append_date( bson *b, const char *name, bson_date_t millis );
1018 
1028 MONGO_EXPORT int bson_append_time_t( bson *b, const char *name, time_t secs );
1029 
1038 MONGO_EXPORT int bson_append_start_object( bson *b, const char *name );
1039 
1048 MONGO_EXPORT int bson_append_start_array( bson *b, const char *name );
1049 
1057 MONGO_EXPORT int bson_append_finish_object( bson *b );
1058 
1067 MONGO_EXPORT int bson_append_finish_array( bson *b );
1068 
1069 void bson_numstr( char *str, int i );
1070 
1071 void bson_incnumstr( char *str );
1072 
1073 /* Error handling and standard library function over-riding. */
1074 /* -------------------------------------------------------- */
1075 
1076 /* bson_err_handlers shouldn't return!!! */
1077 typedef void( *bson_err_handler )( const char *errmsg );
1078 
1079 typedef int (*bson_printf_func)( const char *, ... );
1080 typedef int (*bson_fprintf_func)( FILE *, const char *, ... );
1081 typedef int (*bson_sprintf_func)( char *, const char *, ... );
1082 
1083 extern void *( *bson_malloc_func )( size_t );
1084 extern void *( *bson_realloc_func )( void *, size_t );
1085 extern void ( *bson_free_func )( void * );
1086 
1091 
1092 MONGO_EXPORT void bson_free( void *ptr );
1093 
1103 MONGO_EXPORT void *bson_malloc( size_t size );
1104 
1116 void *bson_realloc( void *ptr, size_t size );
1117 
1125 MONGO_EXPORT bson_err_handler set_bson_err_handler( bson_err_handler func );
1126 
1127 /* does nothing if ok != 0 */
1133 void bson_fatal( int ok );
1134 
1141 void bson_fatal_msg( int ok, const char *msg );
1142 
1148 void bson_builder_error( bson *b );
1149 
1155 MONGO_EXPORT double bson_int64_to_double( int64_t i64 );
1156 
1157 MONGO_EXPORT void bson_swap_endian32( void *outp, const void *inp );
1158 MONGO_EXPORT void bson_swap_endian64( void *outp, const void *inp );
1159 
1161 
1162 #endif /* H_BSON */
const bson * b
Definition: bson.h:280
const char const double d
Definition: bson.h:800
void bson_builder_error(bson *b)
Invoke the error handler, but do not exit.
Definition: bson.c:1433
const char const char size_t len
Definition: bson.h:823
const char bson_timestamp_t * ts
Definition: bson.h:1004
bson_fprintf_func bson_fprintf
Definition: bson.c:372
A key or a string is not valid UTF-8.
Definition: bson.h:68
int err
Bitfield representing errors or warnings on this buffer.
Definition: bson.h:119
#define MONGO_EXTERN_C_END
Definition: bson.h:51
Definition: bson.h:91
const bson * obj
Definition: bson.h:269
Definition: bson.h:93
const char int time
Definition: bson.h:1005
Definition: bson.h:90
Trying to expand a BSON object which does not own its data block.
Definition: bson.h:63
double bson_iterator_double_raw(const bson_iterator *i)
Get the double value of the BSON object currently pointed to by the iterator.
Definition: bson.c:744
void * bson_realloc(void *ptr, size_t size)
Changes the size of allocated memory and checks return value, exiting fatally if realloc() fails...
Definition: bson.c:1408
int bson_init_finished_data_with_copy(bson *b, const char *data)
Initialize a BSON object for reading and copy finalized BSON data from the provided char*...
Definition: bson.c:417
BSON is valid and UTF-8 compliant.
Definition: bson.h:67
void bson_numstr(char *str, int i)
Definition: bson.c:1459
const char bson_date_t millis
Definition: bson.h:1017
bson bson_bool_t copyData
Definition: bson.h:491
#define MONGO_EXTERN_C_START
Definition: bson.h:50
const char * buffer
Definition: bson.h:289
int dataSize
The number of bytes allocated to char *data.
Definition: bson.h:116
bson_sprintf_func bson_sprintf
Definition: bson.c:373
Definition: bson.h:92
char * data
Pointer to a block of data in this BSON object.
Definition: bson.h:114
Trying bson_append_finish_object() and not in sub.
Definition: bson.h:62
bson * sub
Definition: bson.h:576
#define MONGO_EXPORT
Definition: bson.h:42
int bson_init_size(bson *b, int size)
Initialize a BSON object for building and allocate a data buffer of a given size. ...
Definition: bson.c:941
const char * str
Definition: bson.h:593
void bson_little_endian32(void *outp, const void *inp)
Definition: bson.c:55
const char const bson_bool_t v
Definition: bson.h:919
bson_error_t
Definition: bson.h:59
const void * inp
Definition: bson.h:1157
const char const bson_oid_t * oid
Definition: bson.h:757
const char const bson * data
Definition: mongo.h:463
bson_bool_t ownsData
Whether destroying this object will deallocate its data block.
Definition: bson.h:118
int(* bson_printf_func)(const char *,...)
Definition: bson.h:1079
int(* bson_fprintf_func)(FILE *, const char *,...)
Definition: bson.h:1080
Definition: bson.h:113
void bson_big_endian64(void *outp, const void *inp)
Definition: bson.c:71
const char time_t secs
Definition: bson.h:1028
bson_validity_t
Definition: bson.h:66
bson_bool_t bson_iterator_bool_raw(const bson_iterator *i)
Get the bson_bool_t value of the BSON object currently pointed to by the iterator.
Definition: bson.c:756
int stackPos
Index of current stack position.
Definition: bson.h:121
int bson_iterator_string_len(const bson_iterator *i)
Get the string length of the BSON object currently pointed to by the iterator.
Definition: bson.c:853
int depth
Definition: bson.h:258
void(* bson_free_func)(void *)
Definition: bson.c:366
const char * name_or_null
Definition: bson.h:993
Definition: bson.h:96
Warning: key starts with '$' character.
Definition: bson.h:70
bson_binary_subtype_t
Definition: bson.h:73
bson_bool_t first
Definition: bson.h:110
const char const char const char * opts
Definition: bson.h:971
int stackSize
Number of elements in the current stack.
Definition: bson.h:120
const char const int i
Definition: bson.h:778
bson_bool_t finished
When finished, the BSON object can no longer be modified.
Definition: bson.h:117
const char int int increment
Definition: bson.h:1005
const char const bson const bson bson * out
Definition: mongo.h:678
void bson_little_endian64(void *outp, const void *inp)
Definition: bson.c:34
bson_printf_func bson_printf
Definition: bson.c:370
void bson_fatal(int ok)
Exit fatally.
Definition: bson.c:1438
const char const char size_t size
Definition: bson.h:895
int64_t bson_iterator_long_raw(const bson_iterator *i)
Get the long value of the BSON object currently pointed to by the iterator.
Definition: bson.c:750
bson_type
Definition: bson.h:82
int bson_bool_t
Definition: bson.h:106
int bson_iterator_int_raw(const bson_iterator *i)
Get the int value of the BSON object currently pointed to by the iterator.
Definition: bson.c:738
void(* bson_err_handler)(const char *errmsg)
Definition: bson.h:1077
const bson * in
Definition: bson.h:746
void bson_big_endian32(void *outp, const void *inp)
Definition: bson.c:92
int bson_init_unfinished_data(bson *b, char *data, int dataSize, bson_bool_t ownsData)
Initialize a BSON object for building, using the provided char* of the given size.
Definition: bson.c:955
void bson_fatal_msg(int ok, const char *msg)
Exit fatally with an error message.
Definition: bson.c:1442
Definition: bson.h:99
Deprecated.
Definition: bson.h:95
const char const bson * bson
Definition: bson.h:982
const char char type
Definition: bson.h:908
const char * cur
Definition: bson.h:109
Definition: bson.h:83
const bson const char * name
Definition: bson.h:269
bson_printf_func bson_errprintf
Definition: bson.c:376
const char const char * code
Definition: bson.h:882
bson * scope
Definition: bson.h:491
Warning: key contains '.
Definition: bson.h:69
const char const char * pattern
Definition: bson.h:971
int bson_init_finished_data(bson *b, char *data, bson_bool_t ownsData)
Initialize a BSON object for reading and set its data pointer to the provided char*.
Definition: bson.c:408
int64_t bson_date_t
Definition: bson.h:134
Trying to create a BSON object larger than INT_MAX.
Definition: bson.h:60
int(* bson_sprintf_func)(char *, const char *,...)
Definition: bson.h:1081
void bson_incnumstr(char *str)
size_t * stackPtr
Pointer to the current stack.
Definition: bson.h:122
int bson_ensure_space(bson *b, const size_t bytesNeeded)
Grow a bson object.
Definition: bson.c:1020
const char const bson_iterator * elem
Definition: bson.h:993
char * cur
Pointer to the current position.
Definition: bson.h:115
Trying to modify a finished BSON object.
Definition: bson.h:61