- libbson 1.13.1 »
- Tutorial

# ObjectIDs

Libbson provides a simple way to generate ObjectIDs. It can be used in a single-threaded or multi-threaded manner depending on your requirements.

The bson_oid_t structure represents an `ObjectID` in MongoDB. It is a 96-bit identifier that includes various information about the system generating the OID.

## Composition

- 4 bytes : The UNIX timestamp in big-endian format.
- 3 bytes : A hash of the hostname.
- 2 bytes : The `pid_t` of the current process. Alternatively the task-id if configured.
- 3 bytes : A 24-bit monotonic counter incrementing from `rand()` in big-endian.

## Sorting ObjectIDs

The typical way to sort in C is using `qsort()`. Therefore, Libbson provides a `qsort()` compatible callback function named bson_oid_compare(). It returns `less than 1`, `greater than 1`, or `0` depending on the equality of two bson_oid_t structures.

## Comparing Object IDs

If you simply want to compare two bson_oid_t structures for equality, use bson_oid_equal().

## Generating

To generate a bson_oid_t, you may use the following.

    bson_oid_t oid;

    bson_oid_init (&oid, NULL);

## Parsing ObjectID Strings

You can also parse a string containing a bson_oid_t. The input string MUST be 24 characters or more in length.

    bson_oid_t oid;

    bson_oid_init_from_string (&oid, "123456789012345678901234");

If you need to parse may bson_oid_t in a tight loop and can guarantee the data is safe, you might consider using the inline variant. It will be inlined into your code and reduce the need for a foreign function call.

    bson_oid_t oid;

    bson_oid_init_from_string_unsafe (&oid, "123456789012345678901234");

## Hashing ObjectIDs

If you need to store items in a hashtable, you may want to use the bson_oid_t as the key. Libbson provides a hash function for just this purpose. It is based on DJB hash.

    unsigned hash;

    hash = bson_oid_hash (oid);

## Fetching ObjectID Creation Time

You can easily fetch the time that a bson_oid_t was generated using bson_oid_get_time_t().

    time_t t;

    t = bson_oid_get_time_t (oid);
    printf ("The OID was generated at %u\n", (unsigned) t);

Created using Sphinx 1.8.3, based on Sphinx Readable Theme.