<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="updating-document">

  <info>
    <link type="guide" xref="index#getting-started" />
  </info>

  <title>Updating a Document</title>

  <p>The following guide will step you through the process of connecting to MongoDB and updating a document.</p>

  <include href="basic-prequisites.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <section id="inserting-basics">
    <title>The Basics</title>

    <p>
      The following code example creates a new <code>mongoc_client_t</code> that we will use to communicate with MongoDB.
      The <link href="http://docs.mongodb.org/manual/reference/connection-string/">Connection String URI</link> component is quite comprehensive.
    </p>

    <p>
      Using our <code>mongoc_client_t</code>, we get a handle to a <code>mongoc_collection_t</code> which represents the remote collection.
      We create a new document, initialized with an <code>_id</code> and a field named <code>hello</code> and insert it into the <code>test.test</code> collection.
      Then, using that same <code>_id</code>, we update the document, overwriting an existing field and adding a new field.
    </p>

    <p>
      Lastly, we release all of our heap allocated structures.
    </p>

    <listing>
      <title><file>example4.c</file></title>
      <desc>Update a document from the collection.</desc>
      <synopsis><code mime="text/x-csrc"><![CDATA[#include <bcon.h>
#include <bson.h>
#include <mongoc.h>
#include <stdio.h>

int
main (int   argc,
      char *argv[])
{
    mongoc_collection_t *collection;
    mongoc_client_t *client;
    bson_error_t error;
    bson_oid_t oid;
    bson_t *doc = NULL;
    bson_t *update = NULL;
    bson_t *query = NULL;

    mongoc_init ();

    client = mongoc_client_new ("mongodb://localhost:27017/");
    collection = mongoc_client_get_collection (client, "test", "test");

    bson_oid_init (&oid, NULL);
    doc = BCON_NEW ("_id", BCON_OID (&oid),
                    "hello", BCON_UTF8 ("world!"));

    if (!mongoc_collection_insert (collection, MONGOC_INSERT_NONE, doc, NULL, &error)) {
        printf ("%s\n", error.message);
        goto fail;
    }

    query = BCON_NEW ("_id", BCON_OID (&oid));
    update = BCON_NEW ("$set", "{",
                           "hello", BCON_UTF8 ("Everybody!"),
                           "updated", BCON_BOOL (true),
                       "}");

    if (!mongoc_collection_update (collection, MONGOC_UPDATE_NONE, query, update, NULL, &error)) {
        printf ("%s\n", error.message);
        goto fail;
    }

fail:
    if (doc)
        bson_destroy (doc);
    if (query)
        bson_destroy (query);
    if (update)
        bson_destroy (update);

    mongoc_collection_destroy (collection);
    mongoc_client_destroy (client);

    return 0;
}
]]></code></synopsis>
    </listing>

    <p>Let's use <code>GCC</code> and <code>pkg-config</code> to compile <file>example4.c</file>.</p>
    <screen>gcc -o example4 example4.c $(pkg-config --cflags --libs libmongoc-1.0)</screen>

    <note style="warning">
      <p>
        When using the MongoDB C Driver, you must call <code>mongoc_init()</code> at the beginning of your application.
        This allows the driver to initialize it's required subsystems.
        Failure to do so will result in a runtime crash.
      </p>
    </note>

    <p>Now let's run it!</p>

    <screen>./example4</screen>

    <p>Let's make a query with the MongoDB shell now and see what happened!</p>

    <screen>[christian@starpulse ~]$ mongo
MongoDB shell version: 2.4.10
connecting to: test
> use test
switched to db test
> db.test.find({})
{ "_id" : { "$oid" : "534cde1a4f05ea4055d4cd4c" }, "hello" : "Everybody!", "updated" : true }
> 
bye</screen>

  </section>

</page>
