.\" This manpage is Copyright (C) 2016 MongoDB, Inc.
.\" 
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.3
.\" or any later version published by the Free Software Foundation;
.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.\" A copy of the license is included in the section entitled "GNU
.\" Free Documentation License".
.\" 
.TH "BSON_OID_T" "3" "2016\(hy10\(hy12" "libbson"
.SH NAME
bson_oid_t \- BSON ObjectID Abstraction
.SH "SYNOPSIS"

.nf
.nf
#include <bson.h>

typedef struct
{
   uint8_t bytes[12];
} bson_oid_t;
.fi
.fi

.SH "DESCRIPTION"

The
.B bson_oid_t
structure contains the 12\(hybyte ObjectId notation defined by the
.B BSON ObjectID specificiation
.

ObjectId is a 12\(hybyte BSON type, constructed using:

.IP \[bu] 2
a 4\(hybyte value representing the seconds since the Unix epoch (in Big Endian)
.IP \[bu] 2
a 3\(hybyte machine identifier
.IP \[bu] 2
a 2\(hybyte process id (Big Endian), and
.IP \[bu] 2
a 3\(hybyte counter (Big Endian), starting with a random value.

.SH "STRING CONVERSION"

You can convert an Object ID to a string using
.B bson_oid_to_string(3)
and back with
.B bson_oid_init_from_string(3)
.

.SH "HASHING"

A
.B bson_oid_t
can be used in hashtables using the function
.B bson_oid_hash(3)
and
.B bson_oid_equal(3)
.

.SH "COMPARING"

A
.B bson_oid_t
can be compared to another using
.B bson_oid_compare(3)
for
.B qsort(3)
style comparing and
.B bson_oid_equal(3)
for direct equality.

.SH "VALIDATING"

You can validate that a string containing a hex\(hyencoded ObjectID is valid using the function
.B bson_oid_is_valid(3)
.

.SH "EXAMPLE"

.nf
.nf
#include <bson.h>
#include <stdio.h>

int main (int argc, char *argv[])
{
   bson_oid_t oid;
   char str[25];

   bson_oid_init (&oid, NULL);
   bson_oid_to_string (&oid, str);
   printf ("%s\en", str);

   if (bson_oid_is_valid (str, sizeof str)) {
      bson_oid_init_from_string (&oid, str);
   }

   printf ("The UNIX time was: %u\en",
           (unsigned)bson_oid_get_time_t (&oid));

   return 0;
}
.fi
.fi


.B
.SH COLOPHON
This page is part of libbson.
Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.