src/bson/bson.h

   1 /**
   2  * @file bson.h
   3  * @brief BSON Declarations
   4  */
   5
   6 /*    Copyright 2009-2012 10gen Inc.
   7  *    Copyright (C) 2012-2015 Softmotions Ltd <info@softmotions.com>
   8  *
   9  *    Licensed under the Apache License, Version 2.0 (the "License");
  10  *    you may not use this file except in compliance with the License.
  11  *    You may obtain a copy of the License at
  12  *
  13  *    http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *    Unless required by applicable law or agreed to in writing, software
  16  *    distributed under the License is distributed on an "AS IS" BASIS,
  17  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  *    See the License for the specific language governing permissions and
  19  *    limitations under the License.
  20  */
  21
  22 #ifndef BSON_H_
  23 #define BSON_H_
  24
  25 #include "basedefs.h"
  26 #include <stdio.h>
  27 #include <stdint.h>
  28 #if ! defined(__cplusplus)
  29 #include <stdbool.h>
  30 #endif
  31 #include <time.h>
  32 #include "tcutil.h"
  33
  34 #define BSON_IS_NUM_TYPE(atype) (atype == BSON_INT || atype == BSON_LONG || atype == BSON_DOUBLE)
  35 #define BSON_IS_STRING_TYPE(atype) ((atype) == BSON_STRING || (atype) == BSON_SYMBOL)
  36
  37 EJDB_EXTERN_C_START
  38
  39 #define BSON_OK 0
  40 #define BSON_ERROR -1
  41
  42 //Maximum field path length allocated on stack
  43 #define BSON_MAX_FPATH_LEN (255)
  44
  45 enum bson_error_t {
  46     BSON_SIZE_OVERFLOW = 1 /**< Trying to create a BSON object larger than INT_MAX. */
  47 };
  48
  49 enum bson_validity_t {
  50     BSON_VALID = 0, /**< BSON is valid and UTF-8 compliant. */
  51     BSON_NOT_UTF8 = (1 << 1), /**< A key or a string is not valid UTF-8. */
  52     BSON_FIELD_HAS_DOT = (1 << 2), /**< Warning: key contains '.' character. */
  53     BSON_FIELD_INIT_DOLLAR = (1 << 3), /**< Warning: key starts with '$' character. */
  54     BSON_ALREADY_FINISHED = (1 << 4), /**< Trying to modify a finished BSON object. */
  55     BSON_ERROR_ANY = (1 << 5) /**< Unspecified error */
  56 };
  57
  58 enum bson_binary_subtype_t {
  59     BSON_BIN_BINARY = 0,
  60     BSON_BIN_FUNC = 1,
  61     BSON_BIN_BINARY_OLD = 2,
  62     BSON_BIN_UUID = 3,
  63     BSON_BIN_MD5 = 5,
  64     BSON_BIN_USER = 128
  65 };
  66
  67 enum bson_flags_t {
  68     BSON_FLAG_QUERY_MODE = 1,
  69     BSON_FLAG_STACK_ALLOCATED = 1 << 1 /**< If it set BSON data is allocated on stack and realloc should deal with this case */
  70 };
  71
  72 typedef enum {
  73     BSON_EOO = 0,
  74     BSON_DOUBLE = 1,
  75     BSON_STRING = 2,
  76     BSON_OBJECT = 3,
  77     BSON_ARRAY = 4,
  78     BSON_BINDATA = 5,
  79     BSON_UNDEFINED = 6,
  80     BSON_OID = 7,
  81     BSON_BOOL = 8,
  82     BSON_DATE = 9,
  83     BSON_NULL = 10,
  84     BSON_REGEX = 11,
  85     BSON_DBREF = 12, /**< Deprecated. */
  86     BSON_CODE = 13,
  87     BSON_SYMBOL = 14,
  88     BSON_CODEWSCOPE = 15,
  89     BSON_INT = 16,
  90     BSON_TIMESTAMP = 17,
  91     BSON_LONG = 18
  92 } bson_type;
  93
  94 typedef int bson_bool_t;
  95
  96 typedef struct {
  97     const char *cur;
  98     bson_bool_t first;
  99 } bson_iterator;
 100
 101 typedef struct {
 102     char *data; /**< Pointer to a block of data in this BSON object. */
 103     char *cur; /**< Pointer to the current position. */
 104     int dataSize; /**< The number of bytes allocated to char *data. */
 105     bson_bool_t finished; /**< When finished, the BSON object can no longer be modified. */
 106     int stack[32]; /**< A stack used to keep track of nested BSON elements. */
 107     int stackPos; /**< Index of current stack position. */
 108     int err; /**< Bitfield representing errors or warnings on this buffer */
 109     char *errstr; /**< A string representation of the most recent error or warning. */
 110     int flags;
 111 } bson;
 112
 113 #pragma pack(1)
 114
 115 typedef union {
 116     char bytes[12];
 117     int ints[3];
 118 } bson_oid_t;
 119 #pragma pack()
 120
 121 typedef int64_t bson_date_t; /* milliseconds since epoch UTC */
 122
 123 typedef struct {
 124     int i; /* increment */
 125     int t; /* time in seconds */
 126 } bson_timestamp_t;
 127
 128
 129 EJDB_EXPORT const char* bson_first_errormsg(bson *bson);
 130
 131
 132 #define BSON_ITERATOR_FROM_BUFFER(_bs_I, _bs_B) \
 133     (_bs_I)->cur = ((char*) (_bs_B)) + 4;       \
 134     (_bs_I)->first = 1;
 135
 136 #define BSON_ITERATOR_SUBITERATOR(_bs_I, _bs_S) \
 137     BSON_ITERATOR_FROM_BUFFER((_bs_S), bson_iterator_value(_bs_I))
 138
 139 #define BSON_ITERATOR_TYPE(_bs_I) \
 140     ((bson_type) (_bs_I)->cur[0])
 141
 142 #define BSON_ITERATOR_KEY(_bs_I) \
 143     ((_bs_I)->cur + 1)
 144
 145 #define BSON_ITERATOR_INIT(_bs_I, _bs) \
 146     (_bs_I)->cur = (_bs)->data + 4; \
 147     (_bs_I)->first = 1;
 148
 149 /* ----------------------------
 150    READING
 151    ------------------------------ */
 152
 153 EJDB_EXPORT bson* bson_create(void);
 154 EJDB_EXPORT void bson_dispose(bson* b);
 155
 156 /**
 157  * Size of a BSON object.
 158  *
 159  * @param b the BSON object.
 160  *
 161  * @return the size.
 162  */
 163 EJDB_EXPORT int bson_size(const bson *b);
 164 EJDB_EXPORT int bson_size2(const void *bsdata);
 165 EJDB_EXPORT int bson_buffer_size(const bson *b);
 166
 167 /**
 168  * Return a pointer to the raw buffer stored by this bson object.
 169  *
 170  * @param b a BSON object
 171  */
 172 EJDB_EXPORT const char *bson_data(const bson *b);
 173 EJDB_EXPORT const char* bson_data2(const bson *b, int *bsize);
 174
 175 /**
 176  * Print a string representation of a BSON object.
 177  *
 178  * @param bson the raw data to print.
 179  * @param depth the depth to recurse the object.x
 180  */
 181 EJDB_EXPORT void bson_print_raw(const char *bson, int depth);
 182
 183 /**
 184  * Advance a bson_iterator to the named field.
 185  *
 186  * @param it the bson_iterator to use.
 187  * @param obj the BSON object to use.
 188  * @param name the name of the field to find.
 189  *
 190  * @return the type of the found object or BSON_EOO if it is not found.
 191  */
 192 EJDB_EXPORT bson_type bson_find(bson_iterator *it, const bson *obj, const char *name);
 193
 194 EJDB_EXPORT bson_type bson_find_from_buffer(bson_iterator *it, const char *buffer, const char *name);
 195
 196 typedef struct { /**< Find field path context */
 197     const char* fpath;
 198     int fplen;
 199     bson_iterator *input;
 200     int stopos;
 201     bool stopnestedarr;
 202     int mpos; /**< Array index of the first matched array field */
 203     int dpos; /**< Position of `$` in array projection fieldpath. */
 204 } FFPCTX;
 205
 206
 207 /**
 208  * Advance specified iterator 'it' to field value pointing by 'fieldpath'/
 209  * Field path string format: 'field1.nestedfield1.nestedfield.2'.
 210  * If specified field not found BSON_EOO will be returned.
 211  *
 212  * @param fieldpath Path specification to the BSON field.
 213  * @param it the bson_iterator to use.
 214  * @return the type of the found object or BSON_EOO if it is not found.
 215  */
 216 EJDB_EXPORT bson_type bson_find_fieldpath_value(const char *fieldpath, bson_iterator *it);
 217 EJDB_EXPORT bson_type bson_find_fieldpath_value2(const char *fpath, int fplen, bson_iterator *it);
 218 EJDB_EXPORT bson_type bson_find_fieldpath_value3(FFPCTX* ffctx);
 219
 220 /**
 221  * BSON object visitor
 222  * @param it bson iterator to traverse
 223  * @param visitor Visitor function
 224  * @param op Opaque data for visitor
 225  */
 226 typedef enum {
 227     BSON_TRAVERSE_ARRAYS_EXCLUDED = 1,
 228     BSON_TRAVERSE_OBJECTS_EXCLUDED = 1 << 1
 229 } bson_traverse_flags_t;
 230
 231 typedef enum {
 232     BSON_VCMD_OK = 0,
 233     BSON_VCMD_TERMINATE = 1,
 234     BSON_VCMD_SKIP_NESTED = 1 << 1,
 235     BSON_VCMD_SKIP_AFTER = 1 << 2
 236 } bson_visitor_cmd_t;
 237 typedef bson_visitor_cmd_t(*BSONVISITOR)(const char *ipath, int ipathlen, const char *key, int keylen, const bson_iterator *it, bool after, void *op);
 238 EJDB_EXPORT void bson_visit_fields(bson_iterator *it, bson_traverse_flags_t flags, BSONVISITOR visitor, void *op);
 239
 240
 241 EJDB_EXPORT bson_iterator* bson_iterator_create(void);
 242 EJDB_EXPORT void bson_iterator_dispose(bson_iterator*);
 243 /**
 244  * Initialize a bson_iterator.
 245  *
 246  * @param i the bson_iterator to initialize.
 247  * @param bson the BSON object to associate with the iterator.
 248  */
 249 EJDB_EXPORT void bson_iterator_init(bson_iterator *i, const bson *b);
 250
 251 /**
 252  * Initialize a bson iterator from a const char* buffer. Note
 253  * that this is mostly used internally.
 254  *
 255  * @param i the bson_iterator to initialize.
 256  * @param buffer the buffer to point to.
 257  */
 258 EJDB_EXPORT void bson_iterator_from_buffer(bson_iterator *i, const char *buffer);
 259
 260 /* more returns true for eoo. best to loop with bson_iterator_next(&it) */
 261 /**
 262  * Check to see if the bson_iterator has more data.
 263  *
 264  * @param i the iterator.
 265  *
 266  * @return  returns true if there is more data.
 267  */
 268 EJDB_EXPORT bson_bool_t bson_iterator_more(const bson_iterator *i);
 269
 270 /**
 271  * Point the iterator at the next BSON object.
 272  *
 273  * @param i the bson_iterator.
 274  *
 275  * @return the type of the next BSON object.
 276  */
 277 EJDB_EXPORT bson_type bson_iterator_next(bson_iterator *i);
 278
 279 /**
 280  * Get the type of the BSON object currently pointed to by the iterator.
 281  *
 282  * @param i the bson_iterator
 283  *
 284  * @return  the type of the current BSON object.
 285  */
 286 EJDB_EXPORT bson_type bson_iterator_type(const bson_iterator *i);
 287
 288 /**
 289  * Get the key of the BSON object currently pointed to by the iterator.
 290  *
 291  * @param i the bson_iterator
 292  *
 293  * @return the key of the current BSON object.
 294  */
 295 EJDB_EXPORT const char *bson_iterator_key(const bson_iterator *i);
 296
 297 /**
 298  * Get the value of the BSON object currently pointed to by the iterator.
 299  *
 300  * @param i the bson_iterator
 301  *
 302  * @return  the value of the current BSON object.
 303  */
 304 EJDB_EXPORT const char *bson_iterator_value(const bson_iterator *i);
 305
 306 /* these convert to the right type (return 0 if non-numeric) */
 307 /**
 308  * Get the double value of the BSON object currently pointed to by the
 309  * iterator.
 310  *
 311  * @param i the bson_iterator
 312  *
 313  * @return  the value of the current BSON object.
 314  */
 315 EJDB_EXPORT double bson_iterator_double(const bson_iterator *i);
 316
 317 /**
 318  * Get the int value of the BSON object currently pointed to by the iterator.
 319  *
 320  * @param i the bson_iterator
 321  *
 322  * @return  the value of the current BSON object.
 323  */
 324 EJDB_EXPORT int bson_iterator_int(const bson_iterator *i);
 325
 326 /**
 327  * Get the long value of the BSON object currently pointed to by the iterator.
 328  *
 329  * @param i the bson_iterator
 330  *
 331  * @return the value of the current BSON object.
 332  */
 333 EJDB_EXPORT int64_t bson_iterator_long(const bson_iterator *i);
 334
 335 /* return the bson timestamp as a whole or in parts */
 336 /**
 337  * Get the timestamp value of the BSON object currently pointed to by
 338  * the iterator.
 339  *
 340  * @param i the bson_iterator
 341  *
 342  * @return the value of the current BSON object.
 343  */
 344 EJDB_EXPORT bson_timestamp_t bson_iterator_timestamp(const bson_iterator *i);
 345 EJDB_EXPORT int bson_iterator_timestamp_time(const bson_iterator *i);
 346 EJDB_EXPORT int bson_iterator_timestamp_increment(const bson_iterator *i);
 347
 348 /**
 349  * Get the boolean value of the BSON object currently pointed to by
 350  * the iterator.
 351  *
 352  * @param i the bson_iterator
 353  *
 354  * @return the value of the current BSON object.
 355  */
 356 /* false: boolean false, 0 in any type, or null */
 357 /* true: anything else (even empty strings and objects) */
 358 EJDB_EXPORT bson_bool_t bson_iterator_bool(const bson_iterator *i);
 359
 360 /**
 361  * Get the double value of the BSON object currently pointed to by the
 362  * iterator. Assumes the correct type is used.
 363  *
 364  * @param i the bson_iterator
 365  *
 366  * @return the value of the current BSON object.
 367  */
 368 /* these assume you are using the right type */
 369 EJDB_EXPORT double bson_iterator_double_raw(const bson_iterator *i);
 370
 371 /**
 372  * Get the int value of the BSON object currently pointed to by the
 373  * iterator. Assumes the correct type is used.
 374  *
 375  * @param i the bson_iterator
 376  *
 377  * @return the value of the current BSON object.
 378  */
 379 EJDB_EXPORT int bson_iterator_int_raw(const bson_iterator *i);
 380
 381 /**
 382  * Get the long value of the BSON object currently pointed to by the
 383  * iterator. Assumes the correct type is used.
 384  *
 385  * @param i the bson_iterator
 386  *
 387  * @return the value of the current BSON object.
 388  */
 389 EJDB_EXPORT int64_t bson_iterator_long_raw(const bson_iterator *i);
 390
 391 /**
 392  * Get the bson_bool_t value of the BSON object currently pointed to by the
 393  * iterator. Assumes the correct type is used.
 394  *
 395  * @param i the bson_iterator
 396  *
 397  * @return the value of the current BSON object.
 398  */
 399 EJDB_EXPORT bson_bool_t bson_iterator_bool_raw(const bson_iterator *i);
 400
 401 /**
 402  * Get the bson_oid_t value of the BSON object currently pointed to by the
 403  * iterator.
 404  *
 405  * @param i the bson_iterator
 406  *
 407  * @return the value of the current BSON object.
 408  */
 409 EJDB_EXPORT bson_oid_t *bson_iterator_oid(const bson_iterator *i);
 410
 411 /**
 412  * Get the string value of the BSON object currently pointed to by the
 413  * iterator.
 414  *
 415  * @param i the bson_iterator
 416  *
 417  * @return  the value of the current BSON object.
 418  */
 419 /* these can also be used with bson_code and bson_symbol*/
 420 EJDB_EXPORT const char *bson_iterator_string(const bson_iterator *i);
 421
 422 /**
 423  * Get the string length of the BSON object currently pointed to by the
 424  * iterator.
 425  *
 426  * @param i the bson_iterator
 427  *
 428  * @return the length of the current BSON object.
 429  */
 430 EJDB_EXPORT int bson_iterator_string_len(const bson_iterator *i);
 431
 432 /**
 433  * Get the code value of the BSON object currently pointed to by the
 434  * iterator. Works with bson_code, bson_codewscope, and BSON_STRING
 435  * returns NULL for everything else.
 436  *
 437  * @param i the bson_iterator
 438  *
 439  * @return the code value of the current BSON object.
 440  */
 441 /* works with bson_code, bson_codewscope, and BSON_STRING */
 442 /* returns NULL for everything else */
 443 EJDB_EXPORT const char *bson_iterator_code(const bson_iterator *i);
 444
 445 /**
 446  * Calls bson_empty on scope if not a bson_codewscope
 447  *
 448  * @param i the bson_iterator.
 449  * @param scope the bson scope.
 450  */
 451 /* calls bson_empty on scope if not a bson_codewscope */
 452 EJDB_EXPORT void bson_iterator_code_scope(const bson_iterator *i, bson *scope);
 453
 454 /**
 455  * Get the date value of the BSON object currently pointed to by the
 456  * iterator.
 457  *
 458  * @param i the bson_iterator
 459  *
 460  * @return the date value of the current BSON object.
 461  */
 462 /* both of these only work with bson_date */
 463 EJDB_EXPORT bson_date_t bson_iterator_date(const bson_iterator *i);
 464
 465 /**
 466  * Get the time value of the BSON object currently pointed to by the
 467  * iterator.
 468  *
 469  * @param i the bson_iterator
 470  *
 471  * @return the time value of the current BSON object.
 472  */
 473 EJDB_EXPORT time_t bson_iterator_time_t(const bson_iterator *i);
 474
 475 /**
 476  * Get the length of the BSON binary object currently pointed to by the
 477  * iterator.
 478  *
 479  * @param i the bson_iterator
 480  *
 481  * @return the length of the current BSON binary object.
 482  */
 483 EJDB_EXPORT int bson_iterator_bin_len(const bson_iterator *i);
 484
 485 /**
 486  * Get the type of the BSON binary object currently pointed to by the
 487  * iterator.
 488  *
 489  * @param i the bson_iterator
 490  *
 491  * @return the type of the current BSON binary object.
 492  */
 493 EJDB_EXPORT char bson_iterator_bin_type(const bson_iterator *i);
 494
 495 /**
 496  * Get the value of the BSON binary object currently pointed to by the
 497  * iterator.
 498  *
 499  * @param i the bson_iterator
 500  *
 501  * @return the value of the current BSON binary object.
 502  */
 503 EJDB_EXPORT const char *bson_iterator_bin_data(const bson_iterator *i);
 504
 505 /**
 506  * Get the value of the BSON regex object currently pointed to by the
 507  * iterator.
 508  *
 509  * @param i the bson_iterator
 510  *
 511  * @return the value of the current BSON regex object.
 512  */
 513 EJDB_EXPORT const char *bson_iterator_regex(const bson_iterator *i);
 514
 515 /**
 516  * Get the options of the BSON regex object currently pointed to by the
 517  * iterator.
 518  *
 519  * @param i the bson_iterator.
 520  *
 521  * @return the options of the current BSON regex object.
 522  */
 523 EJDB_EXPORT const char *bson_iterator_regex_opts(const bson_iterator *i);
 524
 525 /* these work with BSON_OBJECT and BSON_ARRAY */
 526 /**
 527  * Get the BSON subobject currently pointed to by the
 528  * iterator.
 529  *
 530  * @param i the bson_iterator.
 531  * @param sub the BSON subobject destination.
 532  */
 533 EJDB_EXPORT void bson_iterator_subobject(const bson_iterator *i, bson *sub);
 534
 535 /**
 536  * Get a bson_iterator that on the BSON subobject.
 537  *
 538  * @param i the bson_iterator.
 539  * @param sub the iterator to point at the BSON subobject.
 540  */
 541 EJDB_EXPORT void bson_iterator_subiterator(const bson_iterator *i, bson_iterator *sub);
 542
 543 /* str must be at least 24 hex chars + null byte */
 544 /**
 545  * Create a bson_oid_t from a string.
 546  *
 547  * @param oid the bson_oid_t destination.
 548  * @param str a null terminated string comprised of at least 24 hex chars.
 549  */
 550 EJDB_EXPORT void bson_oid_from_string(bson_oid_t *oid, const char *str);
 551
 552 /**
 553  * Create a string representation of the bson_oid_t.
 554  *
 555  * @param oid the bson_oid_t source.
 556  * @param str the string representation destination.
 557  */
 558 EJDB_EXPORT void bson_oid_to_string(const bson_oid_t *oid, char *str);
 559
 560 /**
 561  * Create a bson_oid object.
 562  *
 563  * @param oid the destination for the newly created bson_oid_t.
 564  */
 565 EJDB_EXPORT void bson_oid_gen(bson_oid_t *oid);
 566
 567 /**
 568  * Set a function to be used to generate the second four bytes
 569  * of an object id.
 570  *
 571  * @param func a pointer to a function that returns an int.
 572  */
 573 EJDB_EXPORT void bson_set_oid_fuzz(int ( *func)(void));
 574
 575 /**
 576  * Set a function to be used to generate the incrementing part
 577  * of an object id (last four bytes). If you need thread-safety
 578  * in generating object ids, you should set this function.
 579  *
 580  * @param func a pointer to a function that returns an int.
 581  */
 582 EJDB_EXPORT void bson_set_oid_inc(int ( *func)(void));
 583
 584 /**
 585  * Get the time a bson_oid_t was created.
 586  *
 587  * @param oid the bson_oid_t.
 588  */
 589 EJDB_EXPORT time_t bson_oid_generated_time(bson_oid_t *oid); /* Gives the time the OID was created */
 590
 591 /* ----------------------------
 592    BUILDING
 593    ------------------------------ */
 594
 595
 596 EJDB_EXPORT void bson_append(bson *b, const void *data, int len);
 597
 598 /**
 599  *  Initialize a new bson object. If not created
 600  *  with bson_new, you must initialize each new bson
 601  *  object using this function.
 602  *
 603  *  @note When finished, you must pass the bson object to
 604  *      bson_del( ).
 605  */
 606 EJDB_EXPORT void bson_init(bson *b);
 607
 608
 609 /**
 610  * Intialize a new bson object. In query contruction mode allowing
 611  * dot and dollar chars in field names.
 612  * @param b
 613  */
 614 EJDB_EXPORT void bson_init_as_query(bson *b);
 615
 616 /**
 617  * Initialize a BSON object, and point its data
 618  * pointer to the provided char*.
 619  *
 620  * @param b the BSON object to initialize.
 621  * @param data the raw BSON data.
 622  *
 623  * @return BSON_OK or BSON_ERROR.
 624  */
 625 EJDB_EXPORT int bson_init_data(bson *b, char *data);
 626 EJDB_EXPORT int bson_init_finished_data(bson *b, const char *data);
 627
 628 /**
 629  * Initialize a BSON object, and set its
 630  * buffer to the given size.
 631  *
 632  * @param b the BSON object to initialize.
 633  * @param size the initial size of the buffer.
 634  *
 635  * @return BSON_OK or BSON_ERROR.
 636  */
 637 EJDB_EXPORT void bson_init_size(bson *b, int size);
 638
 639 EJDB_EXPORT void bson_init_on_stack(bson *b, char *bstack, int mincapacity, int maxonstack);
 640
 641 /**
 642  * Grow a bson object.
 643  *
 644  * @param b the bson to grow.
 645  * @param bytesNeeded the additional number of bytes needed.
 646  *
 647  * @return BSON_OK or BSON_ERROR with the bson error object set.
 648  *   Exits if allocation fails.
 649  */
 650 EJDB_EXPORT int bson_ensure_space(bson *b, const int bytesNeeded);
 651
 652 /**
 653  * Finalize a bson object.
 654  *
 655  * @param b the bson object to finalize.
 656  *
 657  * @return the standard error code. To deallocate memory,
 658  *   call bson_del on the bson object.
 659  */
 660 EJDB_EXPORT int bson_finish(bson *b);
 661
 662 /**
 663  * Destroy a bson object.
 664  * Clears bson object and frees internal memory buffers held by bson
 665  * object BUT does not delete bson object itself
 666  * @param b the bson object to destroy.
 667  */
 668 EJDB_EXPORT void bson_destroy(bson *b);
 669
 670 /**
 671  * The bson_del() performs bson_destroy() then frees bson object itself.
 672  * @param b
 673  */
 674 EJDB_EXPORT void bson_del(bson *b);
 675
 676 EJDB_EXPORT void bson_reset(bson *b);
 677
 678 /**
 679  * Returns a pointer to a static empty BSON object.
 680  *
 681  * @param obj the BSON object to initialize.
 682  *
 683  * @return the empty initialized BSON object.
 684  */
 685 /* returns pointer to static empty bson object */
 686 EJDB_EXPORT bson *bson_empty(bson *obj);
 687
 688 /**
 689  * Make a complete copy of the a BSON object.
 690  * The source bson object must be in a finished
 691  * state; otherwise, the copy will fail.
 692  *
 693  * @param out the copy destination BSON object.
 694  * @param in the copy source BSON object.
 695  */
 696 EJDB_EXPORT int bson_copy(bson *out, const bson *in); /* puts data in new buffer. NOOP if out==NULL */
 697
 698 /**
 699  * Append a previously created bson_oid_t to a bson object.
 700  *
 701  * @param b the bson to append to.
 702  * @param name the key for the bson_oid_t.
 703  * @param oid the bson_oid_t to append.
 704  *
 705  * @return BSON_OK or BSON_ERROR.
 706  */
 707 EJDB_EXPORT int bson_append_oid(bson *b, const char *name, const bson_oid_t *oid);
 708
 709 /**
 710  * Append a bson_oid_t to a bson.
 711  *
 712  * @param b the bson to append to.
 713  * @param name the key for the bson_oid_t.
 714  *
 715  * @return BSON_OK or BSON_ERROR.
 716  */
 717 EJDB_EXPORT int bson_append_new_oid(bson *b, const char *name);
 718
 719 /**
 720  * Append an int to a bson.
 721  *
 722  * @param b the bson to append to.
 723  * @param name the key for the int.
 724  * @param i the int to append.
 725  *
 726  * @return BSON_OK or BSON_ERROR.
 727  */
 728 EJDB_EXPORT int bson_append_int(bson *b, const char *name, const int i);
 729
 730 /**
 731  * Append an long to a bson.
 732  *
 733  * @param b the bson to append to.
 734  * @param name the key for the long.
 735  * @param i the long to append.
 736  *
 737  * @return BSON_OK or BSON_ERROR.
 738  */
 739 EJDB_EXPORT int bson_append_long(bson *b, const char *name, const int64_t i);
 740
 741 /**
 742  * Append an double to a bson.
 743  *
 744  * @param b the bson to append to.
 745  * @param name the key for the double.
 746  * @param d the double to append.
 747  *
 748  * @return BSON_OK or BSON_ERROR.
 749  */
 750 EJDB_EXPORT int bson_append_double(bson *b, const char *name, const double d);
 751
 752 /**
 753  * Append a string to a bson.
 754  *
 755  * @param b the bson to append to.
 756  * @param name the key for the string.
 757  * @param str the string to append.
 758  *
 759  * @return BSON_OK or BSON_ERROR.
 760  */
 761 EJDB_EXPORT int bson_append_string(bson *b, const char *name, const char *str);
 762
 763 /**
 764  * Append len bytes of a string to a bson.
 765  *
 766  * @param b the bson to append to.
 767  * @param name the key for the string.
 768  * @param str the string to append.
 769  * @param len the number of bytes from str to append.
 770  *
 771  * @return BSON_OK or BSON_ERROR.
 772  */
 773 EJDB_EXPORT int bson_append_string_n(bson *b, const char *name, const char *str, int len);
 774
 775 /**
 776  * Append a symbol to a bson.
 777  *
 778  * @param b the bson to append to.
 779  * @param name the key for the symbol.
 780  * @param str the symbol to append.
 781  *
 782  * @return BSON_OK or BSON_ERROR.
 783  */
 784 EJDB_EXPORT int bson_append_symbol(bson *b, const char *name, const char *str);
 785
 786 /**
 787  * Append len bytes of a symbol to a bson.
 788  *
 789  * @param b the bson to append to.
 790  * @param name the key for the symbol.
 791  * @param str the symbol to append.
 792  * @param len the number of bytes from str to append.
 793  *
 794  * @return BSON_OK or BSON_ERROR.
 795  */
 796 EJDB_EXPORT int bson_append_symbol_n(bson *b, const char *name, const char *str, int len);
 797
 798 /**
 799  * Append code to a bson.
 800  *
 801  * @param b the bson to append to.
 802  * @param name the key for the code.
 803  * @param str the code to append.
 804  * @param len the number of bytes from str to append.
 805  *
 806  * @return BSON_OK or BSON_ERROR.
 807  */
 808 EJDB_EXPORT int bson_append_code(bson *b, const char *name, const char *str);
 809
 810 /**
 811  * Append len bytes of code to a bson.
 812  *
 813  * @param b the bson to append to.
 814  * @param name the key for the code.
 815  * @param str the code to append.
 816  * @param len the number of bytes from str to append.
 817  *
 818  * @return BSON_OK or BSON_ERROR.
 819  */
 820 EJDB_EXPORT int bson_append_code_n(bson *b, const char *name, const char *str, int len);
 821
 822 /**
 823  * Append code to a bson with scope.
 824  *
 825  * @param b the bson to append to.
 826  * @param name the key for the code.
 827  * @param str the string to append.
 828  * @param scope a BSON object containing the scope.
 829  *
 830  * @return BSON_OK or BSON_ERROR.
 831  */
 832 EJDB_EXPORT int bson_append_code_w_scope(bson *b, const char *name, const char *code, const bson *scope);
 833
 834 /**
 835  * Append len bytes of code to a bson with scope.
 836  *
 837  * @param b the bson to append to.
 838  * @param name the key for the code.
 839  * @param str the string to append.
 840  * @param len the number of bytes from str to append.
 841  * @param scope a BSON object containing the scope.
 842  *
 843  * @return BSON_OK or BSON_ERROR.
 844  */
 845 EJDB_EXPORT int bson_append_code_w_scope_n(bson *b, const char *name, const char *code, int size, const bson *scope);
 846
 847 /**
 848  * Append binary data to a bson.
 849  *
 850  * @param b the bson to append to.
 851  * @param name the key for the data.
 852  * @param type the binary data type.
 853  * @param str the binary data.
 854  * @param len the length of the data.
 855  *
 856  * @return BSON_OK or BSON_ERROR.
 857  */
 858 EJDB_EXPORT int bson_append_binary(bson *b, const char *name, char type, const char *str, int len);
 859
 860 /**
 861  * Append a bson_bool_t to a bson.
 862  *
 863  * @param b the bson to append to.
 864  * @param name the key for the boolean value.
 865  * @param v the bson_bool_t to append.
 866  *
 867  * @return BSON_OK or BSON_ERROR.
 868  */
 869 EJDB_EXPORT int bson_append_bool(bson *b, const char *name, const bson_bool_t v);
 870
 871 /**
 872  * Append a null value to a bson.
 873  *
 874  * @param b the bson to append to.
 875  * @param name the key for the null value.
 876  *
 877  * @return BSON_OK or BSON_ERROR.
 878  */
 879 EJDB_EXPORT int bson_append_null(bson *b, const char *name);
 880
 881 /**
 882  * Append an undefined value to a bson.
 883  *
 884  * @param b the bson to append to.
 885  * @param name the key for the undefined value.
 886  *
 887  * @return BSON_OK or BSON_ERROR.
 888  */
 889 EJDB_EXPORT int bson_append_undefined(bson *b, const char *name);
 890
 891 /**
 892  * Append a regex value to a bson.
 893  *
 894  * @param b the bson to append to.
 895  * @param name the key for the regex value.
 896  * @param pattern the regex pattern to append.
 897  * @param the regex options.
 898  *
 899  * @return BSON_OK or BSON_ERROR.
 900  */
 901 EJDB_EXPORT int bson_append_regex(bson *b, const char *name, const char *pattern, const char *opts);
 902
 903 /**
 904  * Append bson data to a bson.
 905  *
 906  * @param b the bson to append to.
 907  * @param name the key for the bson data.
 908  * @param bson the bson object to append.
 909  *
 910  * @return BSON_OK or BSON_ERROR.
 911  */
 912 EJDB_EXPORT int bson_append_bson(bson *b, const char *name, const bson *bson);
 913
 914 /**
 915  * Append a BSON element to a bson from the current point of an iterator.
 916  *
 917  * @param b the bson to append to.
 918  * @param name_or_null the key for the BSON element, or NULL.
 919  * @param elem the bson_iterator.
 920  *
 921  * @return BSON_OK or BSON_ERROR.
 922  */
 923 EJDB_EXPORT int bson_append_element(bson *b, const char *name_or_null, const bson_iterator *elem);
 924
 925 /**
 926  * Append a bson_timestamp_t value to a bson.
 927  *
 928  * @param b the bson to append to.
 929  * @param name the key for the timestampe value.
 930  * @param ts the bson_timestamp_t value to append.
 931  *
 932  * @return BSON_OK or BSON_ERROR.
 933  */
 934 EJDB_EXPORT int bson_append_timestamp(bson *b, const char *name, bson_timestamp_t *ts);
 935 EJDB_EXPORT int bson_append_timestamp2(bson *b, const char *name, int time, int increment);
 936
 937 /* these both append a bson_date */
 938 /**
 939  * Append a bson_date_t value to a bson.
 940  *
 941  * @param b the bson to append to.
 942  * @param name the key for the date value.
 943  * @param millis the bson_date_t to append.
 944  *
 945  * @return BSON_OK or BSON_ERROR.
 946  */
 947 EJDB_EXPORT int bson_append_date(bson *b, const char *name, bson_date_t millis);
 948
 949 /**
 950  * Append a time_t value to a bson.
 951  *
 952  * @param b the bson to append to.
 953  * @param name the key for the date value.
 954  * @param secs the time_t to append.
 955  *
 956  * @return BSON_OK or BSON_ERROR.
 957  */
 958 EJDB_EXPORT int bson_append_time_t(bson *b, const char *name, time_t secs);
 959
 960 /**
 961  * Start appending a new object to a bson.
 962  *
 963  * @param b the bson to append to.
 964  * @param name the name of the new object.
 965  *
 966  * @return BSON_OK or BSON_ERROR.
 967  */
 968 EJDB_EXPORT int bson_append_start_object(bson *b, const char *name);
 969 EJDB_EXPORT int bson_append_start_object2(bson *b, const char *name, int namelen);
 970
 971 /**
 972  * Start appending a new array to a bson.
 973  *
 974  * @param b the bson to append to.
 975  * @param name the name of the new array.
 976  *
 977  * @return BSON_OK or BSON_ERROR.
 978  */
 979 EJDB_EXPORT int bson_append_start_array(bson *b, const char *name);
 980 EJDB_EXPORT int bson_append_start_array2(bson *b, const char *name, int namelen);
 981
 982 /**
 983  * Finish appending a new object or array to a bson.
 984  *
 985  * @param b the bson to append to.
 986  *
 987  * @return BSON_OK or BSON_ERROR.
 988  */
 989 EJDB_EXPORT int bson_append_finish_object(bson *b);
 990
 991 /**
 992  * Finish appending a new object or array to a bson. This
 993  * is simply an alias for bson_append_finish_object.
 994  *
 995  * @param b the bson to append to.
 996  *
 997  * @return BSON_OK or BSON_ERROR.
 998  */
 999 EJDB_EXPORT int bson_append_finish_array(bson *b);
1000
1001 EJDB_EXPORT void bson_numstr(char *str, int64_t i);
1002 EJDB_EXPORT int bson_numstrn(char *str, int maxbuf, int64_t i);
1003
1004 //void bson_incnumstr(char *str);
1005
1006 /* Error handling and standard library function over-riding. */
1007 /* -------------------------------------------------------- */
1008
1009 /* bson_err_handlers shouldn't return!!! */
1010 typedef void( *bson_err_handler)(const char *errmsg);
1011 typedef int (*bson_printf_func)(const char *, ...);
1012
1013 extern void *(*bson_malloc_func)(size_t);
1014 extern void *(*bson_realloc_func)(void *, size_t);
1015 extern void ( *bson_free_func)(void *);
1016
1017 extern bson_printf_func bson_errprintf;
1018
1019 void bson_free(void *ptr);
1020
1021 /**
1022  * Allocates memory and checks return value, exiting fatally if malloc() fails.
1023  *
1024  * @param size bytes to allocate.
1025  *
1026  * @return a pointer to the allocated memory.
1027  *
1028  * @sa malloc(3)
1029  */
1030 void *bson_malloc(int size);
1031
1032 /**
1033  * Changes the size of allocated memory and checks return value,
1034  * exiting fatally if realloc() fails.
1035  *
1036  * @param ptr pointer to the space to reallocate.
1037  * @param size bytes to allocate.
1038  *
1039  * @return a pointer to the allocated memory.
1040  *
1041  * @sa realloc()
1042  */
1043 void *bson_realloc(void *ptr, int size);
1044
1045 /**
1046  * Set a function for error handling.
1047  *
1048  * @param func a bson_err_handler function.
1049  *
1050  * @return the old error handling function, or NULL.
1051  */
1052 EJDB_EXPORT bson_err_handler set_bson_err_handler(bson_err_handler func);
1053
1054 /* does nothing if ok != 0 */
1055 /**
1056  * Exit fatally.
1057  *
1058  * @param ok exits if ok is equal to 0.
1059  */
1060 void bson_fatal(int ok);
1061
1062 /**
1063  * Exit fatally with an error message.
1064  *
1065  * @param ok exits if ok is equal to 0.
1066  * @param msg prints to stderr before exiting.
1067  */
1068 void bson_fatal_msg(int ok, const char *msg);
1069
1070 /**
1071  * Invoke the error handler, but do not exit.
1072  *
1073  * @param b the buffer object.
1074  */
1075 void bson_builder_error(bson *b);
1076
1077 /**
1078  * Cast an int64_t to double. This is necessary for embedding in
1079  * certain environments.
1080  *
1081  */
1082 EJDB_EXPORT double bson_int64_to_double(int64_t i64);
1083 EJDB_EXPORT void bson_swap_endian32(void *outp, const void *inp);
1084 EJDB_EXPORT void bson_swap_endian64(void *outp, const void *inp);
1085
1086
1087 /**
1088  * Append current field from iterator into bson object.
1089  *
1090  * @param from
1091  * @param into
1092  * @return BSON_OK or BSON_ERROR.
1093  */
1094 EJDB_EXPORT int bson_append_field_from_iterator(const bson_iterator *from, bson *into);
1095
1096 /**
1097  * Append current field value from iterator into bson object under specified string key.
1098  *
1099  * @param key Key name.
1100  * @param from Source iterator value
1101  * @param into Target bsob object
1102  * @return BSON_OK or BSON_ERROR.
1103  */
1104 EJDB_EXPORT int bson_append_field_from_iterator2(const char *key, const bson_iterator *from, bson *into);
1105 EJDB_EXPORT int bson_append_object_from_iterator(const char *key, bson_iterator *from, bson *into);
1106 EJDB_EXPORT int bson_append_array_from_iterator(const char *key, bson_iterator *from, bson *into);
1107
1108
1109 /**
1110  * Merge bson  `b2` into `b1` saving result the 'out' object.
1111  * `b1` & `b2` bson must be finished BSONS.
1112  * Resulting 'out' bson must be allocated and not finished.
1113  *
1114  * Nested object skipped and usupported.
1115  *
1116  * @param b1 BSON to to be merged in `out`
1117  * @param b2 Second BSON to to be merged in `out`
1118  * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1119  * @param out
1120  *
1121  * @return BSON_OK or BSON_ERROR.
1122  */
1123 EJDB_EXPORT int bson_merge(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1124 EJDB_EXPORT int bson_merge2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1125
1126 /**
1127  * Recursive merge bson  `b2` into `b1` saving result the 'out' object.
1128  * `b1` & `b2` bson must be finished BSONS.
1129  * Resulting 'out' bson must be allocated and not finished.
1130  *
1131  * NOTE. Arrays with same paths joined.
1132  *
1133  * @param b1 BSON to to be merged in `out`
1134  * @param b2 Second BSON to to be merged in `out`
1135  * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1136  * @param out
1137  *
1138  * @return BSON_OK or BSON_ERROR.
1139  */
1140 EJDB_EXPORT int bson_merge_recursive(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1141 EJDB_EXPORT int bson_merge_recursive2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1142
1143 /**
1144  * Merge bsons.
1145  * `bsdata2` may contain field path keys (eg: 'foo.bar').
1146  * @param bsdata1 BSON data to to be merged in `out`
1147  * @param bsdata2 Second BSON data to to be merged in `out`
1148  * @param out Resulting `out` bson must be allocated and not finished.
1149  *
1150  * @return BSON_OK or BSON_ERROR.
1151  */
1152 EJDB_EXPORT int bson_merge3(const void *bsdata1, const void *bsdata2, bson *out);
1153
1154 EJDB_EXPORT int bson_inplace_set_bool(bson_iterator *pos, bson_bool_t val);
1155 EJDB_EXPORT int bson_inplace_set_long(bson_iterator *pos, int64_t val);
1156 EJDB_EXPORT int bson_inplace_set_double(bson_iterator *pos, double val);
1157
1158 typedef struct {
1159     TCMAP *ifields; //Required Map of fieldpaths. Map values are a simple boolean bufs.
1160     bool imode; //Required If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1161     const void *bsbuf; //Required BSON buffer to process.
1162     bson *bsout; //Required Allocated output not finished bson* object.
1163     TCMAP *fkfields; //Optional: Map (fpath => bson key) used to force specific bson keys for selected fpaths.
1164     int matched;  //Output: number of matched fieldpaths
1165 } BSONSTRIPCTX;
1166
1167 /**
1168  * Include or exclude fpaths in the specified BSON and put resulting data into `bsout`.
1169  * On completion it finishes `bsout` object.
1170  *
1171  * @param ifields Map of fieldpaths. Map values are a simple boolean bufs.
1172  * @param imode If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1173  * @param bsbuf BSON buffer to process.
1174  * @param bsout Allocated output not finished bson* object
1175  * @param matched[out] Number of matched include/exclude fieldpaths.
1176  * @return BSON error code
1177  */
1178 EJDB_EXPORT int bson_strip(TCMAP *ifields, bool imode, const void *bsbuf, bson *bsout, int *matched);
1179 EJDB_EXPORT int bson_strip2(BSONSTRIPCTX *sctx);
1180
1181
1182 /**
1183  * Compares field path primitive values of two BSONs
1184  * @param bsdata1 BSON raw data
1185  * @param bsdata2 BSON raw data
1186  * @param fpath Field path to the field
1187  * @param fplen Length of fpath value
1188  */
1189 EJDB_EXPORT int bson_compare(const void *bsdata1, const void *bsdata2, const char* fpath, int fplen);
1190 EJDB_EXPORT int bson_compare_fpaths(const void *bsdata1, const void *bsdata2,
1191                                     const char *fpath1, int fplen1,
1192                                     const char *fpath2, int fplen2);
1193 EJDB_EXPORT int bson_compare_it_current(const bson_iterator *it1, const bson_iterator *it2);
1194 EJDB_EXPORT int bson_compare_string(const char* cv, const void *bsdata, const char *fpath);
1195 EJDB_EXPORT int bson_compare_long(const int64_t cv, const void *bsdata, const char *fpath);
1196 EJDB_EXPORT int bson_compare_double(double cv, const void *bsdata, const char *fpath);
1197 EJDB_EXPORT int bson_compare_bool(bson_bool_t cv, const void *bsdata, const char *fpath);
1198
1199
1200 /**
1201  * Duplicates BSON object.
1202  * @param src BSON
1203  * @return Finished copy of src
1204  */
1205 EJDB_EXPORT bson* bson_dup(const bson *src);
1206
1207
1208 EJDB_EXPORT bson* bson_create_from_iterator(bson_iterator *from);
1209 EJDB_EXPORT bson* bson_create_from_buffer(const void *buf, int bufsz);
1210 EJDB_EXPORT bson* bson_create_from_buffer2(bson *bs, const void *buf, int bufsz);
1211 EJDB_EXPORT void bson_init_with_data(bson *bs, const void *bsdata);
1212
1213 typedef enum {
1214     BSON_MERGE_ARRAY_ADDSET = 0,
1215     BSON_MERGE_ARRAY_PULL = 1,
1216     BSON_MERGE_ARRAY_PUSH = 2
1217 } bson_merge_array_mode;
1218
1219 EJDB_EXPORT int bson_merge_arrays(const void *mbuf, const void *inbuf,
1220                                   bson_merge_array_mode mode,
1221                                   bool expandall, bson *bsout);
1222
1223 EJDB_EXPORT bool bson_find_unmerged_arrays(const void *mbuf, const void *inbuf);
1224 EJDB_EXPORT bool bson_find_merged_arrays(const void *mbuf, const void *inbuf, bool expandall);
1225
1226 /**
1227  * Convert BSON into JSON buffer.
1228  *
1229  * A caller should free an allocated `*buf`
1230  * if value of `*buf` is not `NULL` after function completion.
1231  *
1232  * @param src BSON data
1233  * @param buf Allocated buffer with resulting JSON data
1234  * @param sp JSON data length will be stored into
1235  * @return BSON_OK or BSON_ERROR
1236  */
1237 EJDB_EXPORT int bson2json(const char *bsdata, char **buf, int *sp);
1238
1239 /**
1240  * Convert JSON into BSON object.
1241  * @param jsonstr NULL terminated JSON string
1242  * @return Allocated BSON object filled with given JSON data or NULL on error
1243  */
1244 EJDB_EXPORT bson* json2bson(const char *jsonstr);
1245
1246
1247 EJDB_EXTERN_C_END
1248 #endif