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
 238 typedef bson_visitor_cmd_t(*BSONVISITOR)(const char *ipath, int ipathlen,
 239                                          const char *key, int keylen,
 240                                          const bson_iterator *it,
 241                                          bool after, void *op);
 242
 243 EJDB_EXPORT void bson_visit_fields(bson_iterator *it,
 244                                    bson_traverse_flags_t flags,
 245                                    BSONVISITOR visitor, void *op);
 246
 247
 248 EJDB_EXPORT bson_iterator* bson_iterator_create(void);
 249 EJDB_EXPORT void bson_iterator_dispose(bson_iterator*);
 250 /**
 251  * Initialize a bson_iterator.
 252  *
 253  * @param i the bson_iterator to initialize.
 254  * @param bson the BSON object to associate with the iterator.
 255  */
 256 EJDB_EXPORT void bson_iterator_init(bson_iterator *i, const bson *b);
 257
 258 /**
 259  * Initialize a bson iterator from a const char* buffer. Note
 260  * that this is mostly used internally.
 261  *
 262  * @param i the bson_iterator to initialize.
 263  * @param buffer the buffer to point to.
 264  */
 265 EJDB_EXPORT void bson_iterator_from_buffer(bson_iterator *i, const char *buffer);
 266
 267 /* more returns true for eoo. best to loop with bson_iterator_next(&it) */
 268 /**
 269  * Check to see if the bson_iterator has more data.
 270  *
 271  * @param i the iterator.
 272  *
 273  * @return  returns true if there is more data.
 274  */
 275 EJDB_EXPORT bson_bool_t bson_iterator_more(const bson_iterator *i);
 276
 277 /**
 278  * Point the iterator at the next BSON object.
 279  *
 280  * @param i the bson_iterator.
 281  *
 282  * @return the type of the next BSON object.
 283  */
 284 EJDB_EXPORT bson_type bson_iterator_next(bson_iterator *i);
 285
 286 /**
 287  * Get the type of the BSON object currently pointed to by the iterator.
 288  *
 289  * @param i the bson_iterator
 290  *
 291  * @return  the type of the current BSON object.
 292  */
 293 EJDB_EXPORT bson_type bson_iterator_type(const bson_iterator *i);
 294
 295 /**
 296  * Get the key of the BSON object currently pointed to by the iterator.
 297  *
 298  * @param i the bson_iterator
 299  *
 300  * @return the key of the current BSON object.
 301  */
 302 EJDB_EXPORT const char *bson_iterator_key(const bson_iterator *i);
 303
 304 /**
 305  * Get the value of the BSON object currently pointed to by the iterator.
 306  *
 307  * @param i the bson_iterator
 308  *
 309  * @return  the value of the current BSON object.
 310  */
 311 EJDB_EXPORT const char *bson_iterator_value(const bson_iterator *i);
 312
 313 /* these convert to the right type (return 0 if non-numeric) */
 314 /**
 315  * Get the double value of the BSON object currently pointed to by the
 316  * iterator.
 317  *
 318  * @param i the bson_iterator
 319  *
 320  * @return  the value of the current BSON object.
 321  */
 322 EJDB_EXPORT double bson_iterator_double(const bson_iterator *i);
 323
 324 /**
 325  * Get the int value of the BSON object currently pointed to by the iterator.
 326  *
 327  * @param i the bson_iterator
 328  *
 329  * @return  the value of the current BSON object.
 330  */
 331 EJDB_EXPORT int bson_iterator_int(const bson_iterator *i);
 332
 333 /**
 334  * Get the long value of the BSON object currently pointed to by the iterator.
 335  *
 336  * @param i the bson_iterator
 337  *
 338  * @return the value of the current BSON object.
 339  */
 340 EJDB_EXPORT int64_t bson_iterator_long(const bson_iterator *i);
 341
 342 /* return the bson timestamp as a whole or in parts */
 343 /**
 344  * Get the timestamp value of the BSON object currently pointed to by
 345  * the iterator.
 346  *
 347  * @param i the bson_iterator
 348  *
 349  * @return the value of the current BSON object.
 350  */
 351 EJDB_EXPORT bson_timestamp_t bson_iterator_timestamp(const bson_iterator *i);
 352 EJDB_EXPORT int bson_iterator_timestamp_time(const bson_iterator *i);
 353 EJDB_EXPORT int bson_iterator_timestamp_increment(const bson_iterator *i);
 354
 355 /**
 356  * Get the boolean value of the BSON object currently pointed to by
 357  * the iterator.
 358  *
 359  * @param i the bson_iterator
 360  *
 361  * @return the value of the current BSON object.
 362  */
 363 /* false: boolean false, 0 in any type, or null */
 364 /* true: anything else (even empty strings and objects) */
 365 EJDB_EXPORT bson_bool_t bson_iterator_bool(const bson_iterator *i);
 366
 367 /**
 368  * Get the double value of the BSON object currently pointed to by the
 369  * iterator. Assumes the correct type is used.
 370  *
 371  * @param i the bson_iterator
 372  *
 373  * @return the value of the current BSON object.
 374  */
 375 /* these assume you are using the right type */
 376 EJDB_EXPORT double bson_iterator_double_raw(const bson_iterator *i);
 377
 378 /**
 379  * Get the int value of the BSON object currently pointed to by the
 380  * iterator. Assumes the correct type is used.
 381  *
 382  * @param i the bson_iterator
 383  *
 384  * @return the value of the current BSON object.
 385  */
 386 EJDB_EXPORT int bson_iterator_int_raw(const bson_iterator *i);
 387
 388 /**
 389  * Get the long value of the BSON object currently pointed to by the
 390  * iterator. Assumes the correct type is used.
 391  *
 392  * @param i the bson_iterator
 393  *
 394  * @return the value of the current BSON object.
 395  */
 396 EJDB_EXPORT int64_t bson_iterator_long_raw(const bson_iterator *i);
 397
 398 /**
 399  * Get the bson_bool_t value of the BSON object currently pointed to by the
 400  * iterator. Assumes the correct type is used.
 401  *
 402  * @param i the bson_iterator
 403  *
 404  * @return the value of the current BSON object.
 405  */
 406 EJDB_EXPORT bson_bool_t bson_iterator_bool_raw(const bson_iterator *i);
 407
 408 /**
 409  * Get the bson_oid_t value of the BSON object currently pointed to by the
 410  * iterator.
 411  *
 412  * @param i the bson_iterator
 413  *
 414  * @return the value of the current BSON object.
 415  */
 416 EJDB_EXPORT bson_oid_t *bson_iterator_oid(const bson_iterator *i);
 417
 418 /**
 419  * Get the string value of the BSON object currently pointed to by the
 420  * iterator.
 421  *
 422  * @param i the bson_iterator
 423  *
 424  * @return  the value of the current BSON object.
 425  */
 426 /* these can also be used with bson_code and bson_symbol*/
 427 EJDB_EXPORT const char *bson_iterator_string(const bson_iterator *i);
 428
 429 /**
 430  * Get the string length of the BSON object currently pointed to by the
 431  * iterator.
 432  *
 433  * @param i the bson_iterator
 434  *
 435  * @return the length of the current BSON object.
 436  */
 437 EJDB_EXPORT int bson_iterator_string_len(const bson_iterator *i);
 438
 439 /**
 440  * Get the code value of the BSON object currently pointed to by the
 441  * iterator. Works with bson_code, bson_codewscope, and BSON_STRING
 442  * returns NULL for everything else.
 443  *
 444  * @param i the bson_iterator
 445  *
 446  * @return the code value of the current BSON object.
 447  */
 448 /* works with bson_code, bson_codewscope, and BSON_STRING */
 449 /* returns NULL for everything else */
 450 EJDB_EXPORT const char *bson_iterator_code(const bson_iterator *i);
 451
 452 /**
 453  * Calls bson_empty on scope if not a bson_codewscope
 454  *
 455  * @param i the bson_iterator.
 456  * @param scope the bson scope.
 457  */
 458 /* calls bson_empty on scope if not a bson_codewscope */
 459 EJDB_EXPORT void bson_iterator_code_scope(const bson_iterator *i, bson *scope);
 460
 461 /**
 462  * Get the date value of the BSON object currently pointed to by the
 463  * iterator.
 464  *
 465  * @param i the bson_iterator
 466  *
 467  * @return the date value of the current BSON object.
 468  */
 469 /* both of these only work with bson_date */
 470 EJDB_EXPORT bson_date_t bson_iterator_date(const bson_iterator *i);
 471
 472 /**
 473  * Get the time value of the BSON object currently pointed to by the
 474  * iterator.
 475  *
 476  * @param i the bson_iterator
 477  *
 478  * @return the time value of the current BSON object.
 479  */
 480 EJDB_EXPORT time_t bson_iterator_time_t(const bson_iterator *i);
 481
 482 /**
 483  * Get the length of the BSON binary object currently pointed to by the
 484  * iterator.
 485  *
 486  * @param i the bson_iterator
 487  *
 488  * @return the length of the current BSON binary object.
 489  */
 490 EJDB_EXPORT int bson_iterator_bin_len(const bson_iterator *i);
 491
 492 /**
 493  * Get the type of the BSON binary object currently pointed to by the
 494  * iterator.
 495  *
 496  * @param i the bson_iterator
 497  *
 498  * @return the type of the current BSON binary object.
 499  */
 500 EJDB_EXPORT char bson_iterator_bin_type(const bson_iterator *i);
 501
 502 /**
 503  * Get the value of the BSON binary object currently pointed to by the
 504  * iterator.
 505  *
 506  * @param i the bson_iterator
 507  *
 508  * @return the value of the current BSON binary object.
 509  */
 510 EJDB_EXPORT const char *bson_iterator_bin_data(const bson_iterator *i);
 511
 512 /**
 513  * Get the value of the BSON regex object currently pointed to by the
 514  * iterator.
 515  *
 516  * @param i the bson_iterator
 517  *
 518  * @return the value of the current BSON regex object.
 519  */
 520 EJDB_EXPORT const char *bson_iterator_regex(const bson_iterator *i);
 521
 522 /**
 523  * Get the options of the BSON regex object currently pointed to by the
 524  * iterator.
 525  *
 526  * @param i the bson_iterator.
 527  *
 528  * @return the options of the current BSON regex object.
 529  */
 530 EJDB_EXPORT const char *bson_iterator_regex_opts(const bson_iterator *i);
 531
 532 /* these work with BSON_OBJECT and BSON_ARRAY */
 533 /**
 534  * Get the BSON subobject currently pointed to by the
 535  * iterator.
 536  *
 537  * @param i the bson_iterator.
 538  * @param sub the BSON subobject destination.
 539  */
 540 EJDB_EXPORT void bson_iterator_subobject(const bson_iterator *i, bson *sub);
 541
 542 /**
 543  * Get a bson_iterator that on the BSON subobject.
 544  *
 545  * @param i the bson_iterator.
 546  * @param sub the iterator to point at the BSON subobject.
 547  */
 548 EJDB_EXPORT void bson_iterator_subiterator(const bson_iterator *i, bson_iterator *sub);
 549
 550 /* str must be at least 24 hex chars + null byte */
 551 /**
 552  * Create a bson_oid_t from a string.
 553  *
 554  * @param oid the bson_oid_t destination.
 555  * @param str a null terminated string comprised of at least 24 hex chars.
 556  */
 557 EJDB_EXPORT void bson_oid_from_string(bson_oid_t *oid, const char *str);
 558
 559 /**
 560  * Create a string representation of the bson_oid_t.
 561  *
 562  * @param oid the bson_oid_t source.
 563  * @param str the string representation destination.
 564  */
 565 EJDB_EXPORT void bson_oid_to_string(const bson_oid_t *oid, char *str);
 566
 567 /**
 568  * Create a bson_oid object.
 569  *
 570  * @param oid the destination for the newly created bson_oid_t.
 571  */
 572 EJDB_EXPORT void bson_oid_gen(bson_oid_t *oid);
 573
 574 /**
 575  * Set a function to be used to generate the second four bytes
 576  * of an object id.
 577  *
 578  * @param func a pointer to a function that returns an int.
 579  */
 580 EJDB_EXPORT void bson_set_oid_fuzz(int ( *func)(void));
 581
 582 /**
 583  * Set a function to be used to generate the incrementing part
 584  * of an object id (last four bytes). If you need thread-safety
 585  * in generating object ids, you should set this function.
 586  *
 587  * @param func a pointer to a function that returns an int.
 588  */
 589 EJDB_EXPORT void bson_set_oid_inc(int ( *func)(void));
 590
 591 /**
 592  * Get the time a bson_oid_t was created.
 593  *
 594  * @param oid the bson_oid_t.
 595  */
 596 EJDB_EXPORT time_t bson_oid_generated_time(bson_oid_t *oid); /* Gives the time the OID was created */
 597
 598 /* ----------------------------
 599    BUILDING
 600    ------------------------------ */
 601
 602
 603 EJDB_EXPORT void bson_append(bson *b, const void *data, int len);
 604
 605 /**
 606  *  Initialize a new bson object. If not created
 607  *  with bson_new, you must initialize each new bson
 608  *  object using this function.
 609  *
 610  *  @note When finished, you must pass the bson object to
 611  *      bson_del( ).
 612  */
 613 EJDB_EXPORT void bson_init(bson *b);
 614
 615
 616 /**
 617  * Intialize a new bson object. In query contruction mode allowing
 618  * dot and dollar chars in field names.
 619  * @param b
 620  */
 621 EJDB_EXPORT void bson_init_as_query(bson *b);
 622
 623 /**
 624  * Initialize a BSON object, and point its data
 625  * pointer to the provided char*.
 626  *
 627  * @param b the BSON object to initialize.
 628  * @param data the raw BSON data.
 629  *
 630  * @return BSON_OK or BSON_ERROR.
 631  */
 632 EJDB_EXPORT int bson_init_data(bson *b, char *data);
 633 EJDB_EXPORT int bson_init_finished_data(bson *b, const char *data);
 634
 635 /**
 636  * Initialize a BSON object, and set its
 637  * buffer to the given size.
 638  *
 639  * @param b the BSON object to initialize.
 640  * @param size the initial size of the buffer.
 641  *
 642  * @return BSON_OK or BSON_ERROR.
 643  */
 644 EJDB_EXPORT void bson_init_size(bson *b, int size);
 645
 646 EJDB_EXPORT void bson_init_on_stack(bson *b, char *bstack, int mincapacity, int maxonstack);
 647
 648 /**
 649  * Grow a bson object.
 650  *
 651  * @param b the bson to grow.
 652  * @param bytesNeeded the additional number of bytes needed.
 653  *
 654  * @return BSON_OK or BSON_ERROR with the bson error object set.
 655  *   Exits if allocation fails.
 656  */
 657 EJDB_EXPORT int bson_ensure_space(bson *b, const int bytesNeeded);
 658
 659 /**
 660  * Finalize a bson object.
 661  *
 662  * @param b the bson object to finalize.
 663  *
 664  * @return the standard error code. To deallocate memory,
 665  *   call bson_del on the bson object.
 666  */
 667 EJDB_EXPORT int bson_finish(bson *b);
 668
 669 /**
 670  * Destroy a bson object.
 671  * Clears bson object and frees internal memory buffers held by bson
 672  * object BUT does not delete bson object itself
 673  * @param b the bson object to destroy.
 674  */
 675 EJDB_EXPORT void bson_destroy(bson *b);
 676
 677 /**
 678  * The bson_del() performs bson_destroy() then frees bson object itself.
 679  * @param b
 680  */
 681 EJDB_EXPORT void bson_del(bson *b);
 682
 683 EJDB_EXPORT void bson_reset(bson *b);
 684
 685 /**
 686  * Returns a pointer to a static empty BSON object.
 687  *
 688  * @param obj the BSON object to initialize.
 689  *
 690  * @return the empty initialized BSON object.
 691  */
 692 /* returns pointer to static empty bson object */
 693 EJDB_EXPORT bson *bson_empty(bson *obj);
 694
 695 /**
 696  * Make a complete copy of the a BSON object.
 697  * The source bson object must be in a finished
 698  * state; otherwise, the copy will fail.
 699  *
 700  * @param out the copy destination BSON object.
 701  * @param in the copy source BSON object.
 702  */
 703 EJDB_EXPORT int bson_copy(bson *out, const bson *in); /* puts data in new buffer. NOOP if out==NULL */
 704
 705 /**
 706  * Append a previously created bson_oid_t to a bson object.
 707  *
 708  * @param b the bson to append to.
 709  * @param name the key for the bson_oid_t.
 710  * @param oid the bson_oid_t to append.
 711  *
 712  * @return BSON_OK or BSON_ERROR.
 713  */
 714 EJDB_EXPORT int bson_append_oid(bson *b, const char *name, const bson_oid_t *oid);
 715
 716 /**
 717  * Append a bson_oid_t to a bson.
 718  *
 719  * @param b the bson to append to.
 720  * @param name the key for the bson_oid_t.
 721  *
 722  * @return BSON_OK or BSON_ERROR.
 723  */
 724 EJDB_EXPORT int bson_append_new_oid(bson *b, const char *name);
 725
 726 /**
 727  * Append an int to a bson.
 728  *
 729  * @param b the bson to append to.
 730  * @param name the key for the int.
 731  * @param i the int to append.
 732  *
 733  * @return BSON_OK or BSON_ERROR.
 734  */
 735 EJDB_EXPORT int bson_append_int(bson *b, const char *name, const int i);
 736
 737 /**
 738  * Append an long to a bson.
 739  *
 740  * @param b the bson to append to.
 741  * @param name the key for the long.
 742  * @param i the long to append.
 743  *
 744  * @return BSON_OK or BSON_ERROR.
 745  */
 746 EJDB_EXPORT int bson_append_long(bson *b, const char *name, const int64_t i);
 747
 748 /**
 749  * Append an double to a bson.
 750  *
 751  * @param b the bson to append to.
 752  * @param name the key for the double.
 753  * @param d the double to append.
 754  *
 755  * @return BSON_OK or BSON_ERROR.
 756  */
 757 EJDB_EXPORT int bson_append_double(bson *b, const char *name, const double d);
 758
 759 /**
 760  * Append a string to a bson.
 761  *
 762  * @param b the bson to append to.
 763  * @param name the key for the string.
 764  * @param str the string to append.
 765  *
 766  * @return BSON_OK or BSON_ERROR.
 767  */
 768 EJDB_EXPORT int bson_append_string(bson *b, const char *name, const char *str);
 769
 770 /**
 771  * Append len bytes of a string to a bson.
 772  *
 773  * @param b the bson to append to.
 774  * @param name the key for the string.
 775  * @param str the string to append.
 776  * @param len the number of bytes from str to append.
 777  *
 778  * @return BSON_OK or BSON_ERROR.
 779  */
 780 EJDB_EXPORT int bson_append_string_n(bson *b, const char *name, const char *str, int len);
 781
 782 /**
 783  * Append a symbol to a bson.
 784  *
 785  * @param b the bson to append to.
 786  * @param name the key for the symbol.
 787  * @param str the symbol to append.
 788  *
 789  * @return BSON_OK or BSON_ERROR.
 790  */
 791 EJDB_EXPORT int bson_append_symbol(bson *b, const char *name, const char *str);
 792
 793 /**
 794  * Append len bytes of a symbol to a bson.
 795  *
 796  * @param b the bson to append to.
 797  * @param name the key for the symbol.
 798  * @param str the symbol to append.
 799  * @param len the number of bytes from str to append.
 800  *
 801  * @return BSON_OK or BSON_ERROR.
 802  */
 803 EJDB_EXPORT int bson_append_symbol_n(bson *b, const char *name, const char *str, int len);
 804
 805 /**
 806  * Append code to a bson.
 807  *
 808  * @param b the bson to append to.
 809  * @param name the key for the code.
 810  * @param str the code to append.
 811  * @param len the number of bytes from str to append.
 812  *
 813  * @return BSON_OK or BSON_ERROR.
 814  */
 815 EJDB_EXPORT int bson_append_code(bson *b, const char *name, const char *str);
 816
 817 /**
 818  * Append len bytes of code to a bson.
 819  *
 820  * @param b the bson to append to.
 821  * @param name the key for the code.
 822  * @param str the code to append.
 823  * @param len the number of bytes from str to append.
 824  *
 825  * @return BSON_OK or BSON_ERROR.
 826  */
 827 EJDB_EXPORT int bson_append_code_n(bson *b, const char *name, const char *str, int len);
 828
 829 /**
 830  * Append code to a bson with scope.
 831  *
 832  * @param b the bson to append to.
 833  * @param name the key for the code.
 834  * @param str the string to append.
 835  * @param scope a BSON object containing the scope.
 836  *
 837  * @return BSON_OK or BSON_ERROR.
 838  */
 839 EJDB_EXPORT int bson_append_code_w_scope(bson *b, const char *name, const char *code, const bson *scope);
 840
 841 /**
 842  * Append len bytes of code to a bson with scope.
 843  *
 844  * @param b the bson to append to.
 845  * @param name the key for the code.
 846  * @param str the string to append.
 847  * @param len the number of bytes from str to append.
 848  * @param scope a BSON object containing the scope.
 849  *
 850  * @return BSON_OK or BSON_ERROR.
 851  */
 852 EJDB_EXPORT int bson_append_code_w_scope_n(bson *b, const char *name, const char *code, int size, const bson *scope);
 853
 854 /**
 855  * Append binary data to a bson.
 856  *
 857  * @param b the bson to append to.
 858  * @param name the key for the data.
 859  * @param type the binary data type.
 860  * @param str the binary data.
 861  * @param len the length of the data.
 862  *
 863  * @return BSON_OK or BSON_ERROR.
 864  */
 865 EJDB_EXPORT int bson_append_binary(bson *b, const char *name, char type, const char *str, int len);
 866
 867 /**
 868  * Append a bson_bool_t to a bson.
 869  *
 870  * @param b the bson to append to.
 871  * @param name the key for the boolean value.
 872  * @param v the bson_bool_t to append.
 873  *
 874  * @return BSON_OK or BSON_ERROR.
 875  */
 876 EJDB_EXPORT int bson_append_bool(bson *b, const char *name, const bson_bool_t v);
 877
 878 /**
 879  * Append a null value to a bson.
 880  *
 881  * @param b the bson to append to.
 882  * @param name the key for the null value.
 883  *
 884  * @return BSON_OK or BSON_ERROR.
 885  */
 886 EJDB_EXPORT int bson_append_null(bson *b, const char *name);
 887
 888 /**
 889  * Append an undefined value to a bson.
 890  *
 891  * @param b the bson to append to.
 892  * @param name the key for the undefined value.
 893  *
 894  * @return BSON_OK or BSON_ERROR.
 895  */
 896 EJDB_EXPORT int bson_append_undefined(bson *b, const char *name);
 897
 898 /**
 899  * Append a regex value to a bson.
 900  *
 901  * @param b the bson to append to.
 902  * @param name the key for the regex value.
 903  * @param pattern the regex pattern to append.
 904  * @param the regex options.
 905  *
 906  * @return BSON_OK or BSON_ERROR.
 907  */
 908 EJDB_EXPORT int bson_append_regex(bson *b, const char *name, const char *pattern, const char *opts);
 909
 910 /**
 911  * Append bson data to a bson.
 912  *
 913  * @param b the bson to append to.
 914  * @param name the key for the bson data.
 915  * @param bson the bson object to append.
 916  *
 917  * @return BSON_OK or BSON_ERROR.
 918  */
 919 EJDB_EXPORT int bson_append_bson(bson *b, const char *name, const bson *bson);
 920
 921 /**
 922  * Append a BSON element to a bson from the current point of an iterator.
 923  *
 924  * @param b the bson to append to.
 925  * @param name_or_null the key for the BSON element, or NULL.
 926  * @param elem the bson_iterator.
 927  *
 928  * @return BSON_OK or BSON_ERROR.
 929  */
 930 EJDB_EXPORT int bson_append_element(bson *b, const char *name_or_null, const bson_iterator *elem);
 931
 932 /**
 933  * Append a bson_timestamp_t value to a bson.
 934  *
 935  * @param b the bson to append to.
 936  * @param name the key for the timestampe value.
 937  * @param ts the bson_timestamp_t value to append.
 938  *
 939  * @return BSON_OK or BSON_ERROR.
 940  */
 941 EJDB_EXPORT int bson_append_timestamp(bson *b, const char *name, bson_timestamp_t *ts);
 942 EJDB_EXPORT int bson_append_timestamp2(bson *b, const char *name, int time, int increment);
 943
 944 /* these both append a bson_date */
 945 /**
 946  * Append a bson_date_t value to a bson.
 947  *
 948  * @param b the bson to append to.
 949  * @param name the key for the date value.
 950  * @param millis the bson_date_t to append.
 951  *
 952  * @return BSON_OK or BSON_ERROR.
 953  */
 954 EJDB_EXPORT int bson_append_date(bson *b, const char *name, bson_date_t millis);
 955
 956 /**
 957  * Append a time_t value to a bson.
 958  *
 959  * @param b the bson to append to.
 960  * @param name the key for the date value.
 961  * @param secs the time_t to append.
 962  *
 963  * @return BSON_OK or BSON_ERROR.
 964  */
 965 EJDB_EXPORT int bson_append_time_t(bson *b, const char *name, time_t secs);
 966
 967 /**
 968  * Start appending a new object to a bson.
 969  *
 970  * @param b the bson to append to.
 971  * @param name the name of the new object.
 972  *
 973  * @return BSON_OK or BSON_ERROR.
 974  */
 975 EJDB_EXPORT int bson_append_start_object(bson *b, const char *name);
 976 EJDB_EXPORT int bson_append_start_object2(bson *b, const char *name, int namelen);
 977
 978 /**
 979  * Start appending a new array to a bson.
 980  *
 981  * @param b the bson to append to.
 982  * @param name the name of the new array.
 983  *
 984  * @return BSON_OK or BSON_ERROR.
 985  */
 986 EJDB_EXPORT int bson_append_start_array(bson *b, const char *name);
 987 EJDB_EXPORT int bson_append_start_array2(bson *b, const char *name, int namelen);
 988
 989 /**
 990  * Finish appending a new object or array to a bson.
 991  *
 992  * @param b the bson to append to.
 993  *
 994  * @return BSON_OK or BSON_ERROR.
 995  */
 996 EJDB_EXPORT int bson_append_finish_object(bson *b);
 997
 998 /**
 999  * Finish appending a new object or array to a bson. This
1000  * is simply an alias for bson_append_finish_object.
1001  *
1002  * @param b the bson to append to.
1003  *
1004  * @return BSON_OK or BSON_ERROR.
1005  */
1006 EJDB_EXPORT int bson_append_finish_array(bson *b);
1007
1008 EJDB_EXPORT void bson_numstr(char *str, int64_t i);
1009 EJDB_EXPORT int bson_numstrn(char *str, int maxbuf, int64_t i);
1010
1011 //void bson_incnumstr(char *str);
1012
1013 /* Error handling and standard library function over-riding. */
1014 /* -------------------------------------------------------- */
1015
1016 /* bson_err_handlers shouldn't return!!! */
1017 typedef void( *bson_err_handler)(const char *errmsg);
1018 typedef int (*bson_printf_func)(const char *, ...);
1019
1020 extern void *(*bson_malloc_func)(size_t);
1021 extern void *(*bson_realloc_func)(void *, size_t);
1022 extern void ( *bson_free_func)(void *);
1023
1024 extern bson_printf_func bson_errprintf;
1025
1026 void bson_free(void *ptr);
1027
1028 /**
1029  * Allocates memory and checks return value, exiting fatally if malloc() fails.
1030  *
1031  * @param size bytes to allocate.
1032  *
1033  * @return a pointer to the allocated memory.
1034  *
1035  * @sa malloc(3)
1036  */
1037 void *bson_malloc(int size);
1038
1039 /**
1040  * Changes the size of allocated memory and checks return value,
1041  * exiting fatally if realloc() fails.
1042  *
1043  * @param ptr pointer to the space to reallocate.
1044  * @param size bytes to allocate.
1045  *
1046  * @return a pointer to the allocated memory.
1047  *
1048  * @sa realloc()
1049  */
1050 void *bson_realloc(void *ptr, int size);
1051
1052 /**
1053  * Set a function for error handling.
1054  *
1055  * @param func a bson_err_handler function.
1056  *
1057  * @return the old error handling function, or NULL.
1058  */
1059 EJDB_EXPORT bson_err_handler set_bson_err_handler(bson_err_handler func);
1060
1061 /* does nothing if ok != 0 */
1062 /**
1063  * Exit fatally.
1064  *
1065  * @param ok exits if ok is equal to 0.
1066  */
1067 void bson_fatal(int ok);
1068
1069 /**
1070  * Exit fatally with an error message.
1071  *
1072  * @param ok exits if ok is equal to 0.
1073  * @param msg prints to stderr before exiting.
1074  */
1075 void bson_fatal_msg(int ok, const char *msg);
1076
1077 /**
1078  * Invoke the error handler, but do not exit.
1079  *
1080  * @param b the buffer object.
1081  */
1082 void bson_builder_error(bson *b);
1083
1084 /**
1085  * Cast an int64_t to double. This is necessary for embedding in
1086  * certain environments.
1087  *
1088  */
1089 EJDB_EXPORT double bson_int64_to_double(int64_t i64);
1090 EJDB_EXPORT void bson_swap_endian32(void *outp, const void *inp);
1091 EJDB_EXPORT void bson_swap_endian64(void *outp, const void *inp);
1092
1093
1094 /**
1095  * Append current field from iterator into bson object.
1096  *
1097  * @param from
1098  * @param into
1099  * @return BSON_OK or BSON_ERROR.
1100  */
1101 EJDB_EXPORT int bson_append_field_from_iterator(const bson_iterator *from, bson *into);
1102
1103 /**
1104  * Append current field value from iterator into bson object under specified string key.
1105  *
1106  * @param key Key name.
1107  * @param from Source iterator value
1108  * @param into Target bsob object
1109  * @return BSON_OK or BSON_ERROR.
1110  */
1111 EJDB_EXPORT int bson_append_field_from_iterator2(const char *key, const bson_iterator *from, bson *into);
1112 EJDB_EXPORT int bson_append_object_from_iterator(const char *key, bson_iterator *from, bson *into);
1113 EJDB_EXPORT int bson_append_array_from_iterator(const char *key, bson_iterator *from, bson *into);
1114
1115
1116 /**
1117  * Merge bson  `b2` into `b1` saving result the 'out' object.
1118  * `b1` & `b2` bson must be finished BSONS.
1119  * Resulting 'out' bson must be allocated and not finished.
1120  *
1121  * Nested object skipped and usupported.
1122  *
1123  * @param b1 BSON to to be merged in `out`
1124  * @param b2 Second BSON to to be merged in `out`
1125  * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1126  * @param out
1127  *
1128  * @return BSON_OK or BSON_ERROR.
1129  */
1130 EJDB_EXPORT int bson_merge(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1131 EJDB_EXPORT int bson_merge2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1132
1133 /**
1134  * Recursive merge bson  `b2` into `b1` saving result the 'out' object.
1135  * `b1` & `b2` bson must be finished BSONS.
1136  * Resulting 'out' bson must be allocated and not finished.
1137  *
1138  * NOTE. Arrays with same paths joined.
1139  *
1140  * @param b1 BSON to to be merged in `out`
1141  * @param b2 Second BSON to to be merged in `out`
1142  * @param overwrite if `true` all `b1` fields will be overwriten by corresponding `b2` fields
1143  * @param out
1144  *
1145  * @return BSON_OK or BSON_ERROR.
1146  */
1147 EJDB_EXPORT int bson_merge_recursive(const bson *b1, const bson *b2, bson_bool_t overwrite, bson *out);
1148 EJDB_EXPORT int bson_merge_recursive2(const void *b1data, const void *b2data, bson_bool_t overwrite, bson *out);
1149
1150 /**
1151  * Merge bsons.
1152  * `bsdata2` may contain field path keys (eg: 'foo.bar').
1153  * @param bsdata1 BSON data to to be merged in `out`
1154  * @param bsdata2 Second BSON data to to be merged in `out`
1155  * @param out Resulting `out` bson must be allocated and not finished.
1156  *
1157  * @return BSON_OK or BSON_ERROR.
1158  */
1159 EJDB_EXPORT int bson_merge_fieldpaths(const void *bsdata1, const void *bsdata2, bson *out);
1160
1161 EJDB_EXPORT int bson_inplace_set_bool(bson_iterator *pos, bson_bool_t val);
1162 EJDB_EXPORT int bson_inplace_set_long(bson_iterator *pos, int64_t val);
1163 EJDB_EXPORT int bson_inplace_set_double(bson_iterator *pos, double val);
1164
1165 typedef struct {
1166     TCMAP *ifields;     //Required Map of fieldpaths. Map values are a simple boolean bufs.
1167     bool imode;         //Required If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1168     const void *bsbuf;  //Required BSON buffer to process.
1169     bson *bsout;        //Required Allocated output not finished bson* object.
1170     TCMAP *fkfields;    //Optional: Map (fpath => bson key) used to force specific bson keys for selected fpaths.
1171     int matched;        //Output: number of matched fieldpaths
1172     bson *collector;    //Optional: Collector for excluded data (fieldpath -> excluded value)
1173 } BSONSTRIPCTX;
1174
1175 /**
1176  * Include or exclude fpaths in the specified BSON and put resulting data into `bsout`.
1177  * On completion it finishes `bsout` object.
1178  *
1179  * @param ifields Map of fieldpaths. Map values are a simple boolean bufs.
1180  * @param imode If true fpaths will be included. Otherwise fpaths will be excluded from bson.
1181  * @param bsbuf BSON buffer to process.
1182  * @param bsout Allocated and not finished output bson* object
1183  * @param matched[out] Number of matched include/exclude fieldpaths.
1184  * @return BSON error code
1185  */
1186 EJDB_EXPORT int bson_strip(TCMAP *ifields, bool imode, const void *bsbuf, bson *bsout, int *matched);
1187 EJDB_EXPORT int bson_strip2(BSONSTRIPCTX *sctx);
1188
1189 /**
1190  * @brief Rename a fields specified by `fields` rename mapping.
1191  *
1192  * This operation unsets both all and new fieldpaths and then sets
1193  * new fieldpath values.
1194  *
1195  * @param fields Rename mapping old `fieldpath` to new `fieldpath`.
1196  * @param bsbuf BSON buffer to process.
1197  * @param bsout Allocated and not finished output bson* object
1198  * @param rencnt A number of fieldpaths actually renamed.
1199  */
1200 EJDB_EXPORT int bson_rename(TCMAP *fields, const void *bsbuf, bson *bsout, int *rencnt);
1201
1202
1203 /**
1204  * Compares field path primitive values of two BSONs
1205  * @param bsdata1 BSON raw data
1206  * @param bsdata2 BSON raw data
1207  * @param fpath Field path to the field
1208  * @param fplen Length of fpath value
1209  */
1210 EJDB_EXPORT int bson_compare(const void *bsdata1, const void *bsdata2, const char* fpath, int fplen);
1211 EJDB_EXPORT int bson_compare_fpaths(const void *bsdata1, const void *bsdata2,
1212                                     const char *fpath1, int fplen1,
1213                                     const char *fpath2, int fplen2);
1214 EJDB_EXPORT int bson_compare_it_current(const bson_iterator *it1, const bson_iterator *it2);
1215 EJDB_EXPORT int bson_compare_string(const char* cv, const void *bsdata, const char *fpath);
1216 EJDB_EXPORT int bson_compare_long(const int64_t cv, const void *bsdata, const char *fpath);
1217 EJDB_EXPORT int bson_compare_double(double cv, const void *bsdata, const char *fpath);
1218 EJDB_EXPORT int bson_compare_bool(bson_bool_t cv, const void *bsdata, const char *fpath);
1219
1220
1221 /**
1222  * Duplicates BSON object.
1223  * @param src BSON
1224  * @return Finished copy of src
1225  */
1226 EJDB_EXPORT bson* bson_dup(const bson *src);
1227
1228
1229 EJDB_EXPORT bson* bson_create_from_iterator(bson_iterator *from);
1230 EJDB_EXPORT bson* bson_create_from_buffer(const void *buf, int bufsz);
1231 EJDB_EXPORT bson* bson_create_from_buffer2(bson *bs, const void *buf, int bufsz);
1232 EJDB_EXPORT void bson_init_with_data(bson *bs, const void *bsdata);
1233
1234 typedef enum {
1235     BSON_MERGE_ARRAY_ADDSET = 0,
1236     BSON_MERGE_ARRAY_PULL = 1,
1237     BSON_MERGE_ARRAY_PUSH = 2
1238 } bson_merge_array_mode;
1239
1240 EJDB_EXPORT int bson_merge_arrays(const void *mbuf, const void *inbuf,
1241                                   bson_merge_array_mode mode,
1242                                   bool expandall, bson *bsout);
1243
1244 EJDB_EXPORT bool bson_find_unmerged_arrays(const void *mbuf, const void *inbuf);
1245 EJDB_EXPORT bool bson_find_merged_arrays(const void *mbuf, const void *inbuf, bool expandall);
1246
1247 /**
1248  * Convert BSON into JSON buffer.
1249  *
1250  * A caller should free an allocated `*buf`
1251  * if value of `*buf` is not `NULL` after function completion.
1252  *
1253  * @param src BSON data
1254  * @param buf Allocated buffer with resulting JSON data
1255  * @param sp JSON data length will be stored into
1256  * @return BSON_OK or BSON_ERROR
1257  */
1258 EJDB_EXPORT int bson2json(const char *bsdata, char **buf, int *sp);
1259
1260 /**
1261  * Convert JSON into BSON object.
1262  * @param jsonstr NULL terminated JSON string
1263  * @return Allocated BSON object filled with given JSON data or NULL on error
1264  */
1265 EJDB_EXPORT bson* json2bson(const char *jsonstr);
1266
1267
1268 EJDB_EXTERN_C_END
1269 #endif