<?xml version="1.0"?>
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      style="function"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/"
      id="bson_validate">
  <info>
    <link type="guide" xref="bson_t" group="function"/>
  </info>
  <title>bson_validate()</title>

  <section id="synopsis">
    <title>Synopsis</title>
    <synopsis><code mime="text/x-csrc"><![CDATA[
typedef enum
{
   BSON_VALIDATE_NONE            = 0,
   BSON_VALIDATE_UTF8            = (1 << 0),
   BSON_VALIDATE_DOLLAR_KEYS     = (1 << 1),
   BSON_VALIDATE_DOT_KEYS        = (1 << 2),
   BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3),
} bson_validate_flags_t;

bool
bson_validate (const bson_t         *bson,
               bson_validate_flags_t flags,
               size_t               *offset);
]]></code></synopsis>
  </section>

  <section id="parameters">
    <title>Parameters</title>
    <table>
      <tr><td><p>bson</p></td><td><p>A <code xref="bson_t">bson_t</code>.</p></td></tr>
      <tr><td><p>flags</p></td><td><p>A bitwise-or of all desired <code xref="bson_validate">bson_validate_flags_t</code>.</p></td></tr>
      <tr><td><p>offset</p></td><td><p>A location for the offset within <code>bson</code> where the error ocurred.</p></td></tr>
    </table>
  </section>

  <section id="description">
    <title>Description</title>
    <p>Validates a BSON document by walking through the document and inspecting the fields for valid content.</p>
    <p>You can modify how the validation occurs through the use of the <code>flags</code> parameter. A description of their effect is below.</p>
    <list>
      <item><p><code>BSON_VALIDATE_UTF8</code> will request that all UTF-8 strings are checked to contain valid UTF-8 sequences. This is expensive and disabled by default.</p></item>
      <item><p><code>BSON_VALIDATE_UTF8_ALLOW_NULL</code> will specify that UTF-8 strings are allowed to have embedded NULL bytes. Many UTF-8 implementations use a 2-byte squence for embedded NULLs so that they work with stanard libc functions. Libbson expects this by default.</p></item>
      <item><p><code>BSON_VALIDATE_DOLLAR_KEYS</code> will request that all key names are checked to ensure they do not start with the ASCII dollar character (<code>$</code>).</p></item>
      <item><p><code>BSON_VALIDATE_DOT_KEYS</code> will request that all key names are checked to ensure they do not contain an ASCII dot (<code>.</code>) character.</p></item>
    </list>
  </section>

  <section id="return">
    <title>Returns</title>
    <p>Returns true if <code>bson</code> is valid; otherwise false and <code>offset</code> is set to the byte offset where the error was detected.</p>
  </section>
</page>
