CDRIVER-1979 convert docs from XML to RST

Author: ajdavis

doc/advanced-connections.rst

@@ -0,0 +1,148 @@
+:man_page: mongoc_advanced_connections
+
+Advanced Connections
+====================
+
+The following guide contains information specific to certain types of MongoDB configurations.
+
+For an example of connecting to a simple standalone server, see the :ref:`Tutorial <tutorial_connecting>`. To establish a connection with authentication options enabled, see the :doc:`Authentication <authentication>` page.
+
+Connecting to a Replica Set
+---------------------------
+
+Connecting to a `replica set <http://docs.mongodb.org/manual/replication/>`_ is much like connecting to a standalone MongoDB server. Simply specify the replica set name using the ``?replicaSet=myreplset`` URI option.
+
+.. code-block:: c
+
+  #include <bson.h>
+  #include <mongoc.h>
+
+  int
+  main (int argc, char *argv[])
+  {
+     mongoc_client_t *client;
+
+     mongoc_init ();
+
+     /* Create our MongoDB Client */
+     client = mongoc_client_new (
+        "mongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset");
+
+     /* Do some work */
+     /* TODO */
+
+     /* Clean up */
+     mongoc_client_destroy (client);
+     mongoc_cleanup ();
+
+     return 0;
+  }
+
+.. tip::
+
+  Multiple hostnames can be specified in the MongoDB connection string URI, with a comma separating hosts in the seed list.
+
+  It is recommended to use a seed list of members of the replica set to allow the driver to connect to any node.
+
+Connecting to a Sharded Cluster
+-------------------------------
+
+To connect to a `sharded cluster <http://docs.mongodb.org/manual/sharding/>`_, specify the ``mongos`` nodes the client should connect to. The C Driver will automatically detect that it has connected to a ``mongos`` sharding server.
+
+If more than one hostname is specified, a seed list will be created to attempt failover between the ``mongos`` instances.
+
+.. warning::
+
+  Specifying the ``replicaSet`` parameter when connecting to a ``mongos`` sharding server is invalid.
+
+.. code-block:: c
+
+  #include <bson.h>
+  #include <mongoc.h>
+
+  int
+  main (int argc, char *argv[])
+  {
+     mongoc_client_t *client;
+
+     mongoc_init ();
+
+     /* Create our MongoDB Client */
+     client = mongoc_client_new ("mongodb://myshard01:27017/");
+
+     /* Do something with client ... */
+
+     /* Free the client */
+     mongoc_client_destroy (client);
+
+     mongoc_cleanup ();
+
+     return 0;
+  }
+
+Connecting to an IPv6 Address
+-----------------------------
+
+The MongoDB C Driver will automatically resolve IPv6 addresses from host names. However, to specify an IPv6 address directly, wrap the address in ``[]``.
+
+.. code-block:: none
+
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://[::1]:27017");
+
+Connecting to a UNIX Domain Socket
+----------------------------------
+
+On UNIX-like systems, the C Driver can connect directly to a MongoDB server using a UNIX domain socket. Pass the URL-encoded path to the socket, which *must* be suffixed with ``.sock``. For example, to connect to a domain socket at ``/tmp/mongodb-27017.sock``:
+
+.. code-block:: none
+
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://%2Ftmp%2Fmongodb-27017.sock");
+
+Include username and password like so:
+
+.. code-block:: none
+
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://user:pass@%2Ftmp%2Fmongodb-27017.sock");
+
+Connecting to a server over SSL
+-------------------------------
+
+These are instructions for configuring TLS/SSL connections.
+
+To run a server locally (on port 27017, for example):
+
+.. code-block:: none
+
+  $ mongod --port 27017 --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem 
+
+Add ``/?ssl=true`` to the end of a client URI.
+
+.. code-block:: none
+
+  mongoc_client_t *client = NULL;
+  client = mongoc_client_new ("mongodb://localhost:27017/?ssl=true");
+
+MongoDB requires client certificates by default, unless the ``--sslAllowConnectionsWithoutCertificates`` is provided. The C Driver can be configured to present a client certificate using a ``mongoc_ssl_opt_t``:
+
+.. code-block:: none
+
+  const mongoc_ssl_opt_t *ssl_default = mongoc_ssl_opt_get_default ();
+  mongoc_ssl_opt_t ssl_opts = { 0 };
+
+  /* optionally copy in a custom trust directory or file; otherwise the default is used. */
+  memcpy (&ssl_opts, ssl_default, sizeof ssl_opts);
+  ssl_opts.pem_file = "client.pem" 
+
+  mongoc_client_set_ssl_opts (client, &ssl_opts);
+
+The client certificate provided by ``pem_file`` must be issued by one of the server trusted Certificate Authorities listed in ``--sslCAFile``, or issued by a CA in the native certificate store on the server when omitted.
+
+To verify the server certificate against a specific CA, provide a PEM armored file with a CA certificate, or contatinated list of CA certificates using the ``ca_file`` option, or ``c_rehash`` directory structure of CAs, pointed to using the ``ca_dir`` option. When no ``ca_file`` or ``ca_dir`` is provided, the driver will use CAs provided by the native platform certificate store.
+
+See :doc:`mongoc_ssl_opt_t` for more information on the various SSL related options.
+
+Additional Connection Options
+-----------------------------
+
+A variety of connection options for the MongoDB URI can be found `here <http://docs.mongodb.org/manual/reference/connection-string/>`_.
+

doc/aggregate.rst

@@ -0,0 +1,136 @@
+:man_page: mongoc_aggregate
+
+Aggregation Framework Examples
+==============================
+
+This document provides a number of practical examples that display the capabilities of the aggregation framework.
+
+The `Aggregations using the Zip Codes Data Set <https://docs.mongodb.org/manual/tutorial/aggregation-zip-code-data-set/>`_ examples uses a publicly available data set of all zipcodes and populations in the United States. These data are available at: `zips.json <http://media.mongodb.org/zips.json>`_.
+
+Requirements
+------------
+
+`MongoDB <https://www.mongodb.org>`_, version 2.2.0 or later. `MongoDB C driver <https://github.com/mongodb/mongo-c-driver>`_, version 0.96.0 or later.
+
+Let's check if everything is installed.
+
+Use the following command to load zips.json data set into mongod instance:
+
+.. code-block:: none
+
+  $ mongoimport --drop -d test -c zipcodes zips.json
+
+Let's use the MongoDB shell to verify that everything was imported successfully.
+
+.. code-block:: none
+
+  $ mongo testMongoDB shell version: 2.6.1
+  connecting to: test> db.zipcodes.count()29467> db.zipcodes.findOne(){
+  	"_id" : "35004",
+  	"city" : "ACMAR",
+  	"loc" : [
+  		-86.51557,
+  		33.584132
+  	],
+  	"pop" : 6055,
+  	"state" : "AL"
+  }
+
+Aggregations using the Zip Codes Data Set
+-----------------------------------------
+
+Each document in this collection has the following form:
+
+.. code-block:: none
+
+  {
+    "_id" : "35004",
+    "city" : "Acmar",
+    "state" : "AL",
+    "pop" : 6055,
+    "loc" : [-86.51557, 33.584132]
+  }
+
+In these documents:
+
+* The ``_id`` field holds the zipcode as a string.
+* The ``city`` field holds the city name.
+* The ``state`` field holds the two letter state abbreviation.
+* The ``pop`` field holds the population.
+* The ``loc`` field holds the location as a ``[latitude, longitude]`` array.
+
+States with Populations Over 10 Million
+---------------------------------------
+
+To get all states with a population greater than 10 million, use the following aggregation pipeline:
+
+.. literalinclude:: ../examples/aggregation/aggregation1.c
+   :language: c
+   :caption: aggregation1.c
+
+You should see a result like the following:
+
+.. code-block:: none
+
+  { "_id" : "PA", "total_pop" : 11881643 }
+  { "_id" : "OH", "total_pop" : 10847115 }
+  { "_id" : "NY", "total_pop" : 17990455 }
+  { "_id" : "FL", "total_pop" : 12937284 }
+  { "_id" : "TX", "total_pop" : 16986510 }
+  { "_id" : "IL", "total_pop" : 11430472 }
+  { "_id" : "CA", "total_pop" : 29760021 }
+
+The above aggregation pipeline is build from two pipeline operators: ``$group`` and ``$match``.
+
+The ``$group`` pipeline operator requires _id field where we specify grouping; remaining fields specify how to generate composite value and must use one of the group aggregation functions: ``$addToSet``, ``$first``, ``$last``, ``$max``, ``$min``, ``$avg``, ``$push``, ``$sum``. The ``$match`` pipeline operator syntax is the same as the read operation query syntax.
+
+The ``$group`` process reads all documents and for each state it creates a separate document, for example:
+
+.. code-block:: none
+
+  { "_id" : "WA", "total_pop" : 4866692 }
+
+The ``total_pop`` field uses the $sum aggregation function to sum the values of all pop fields in the source documents.
+
+Documents created by ``$group`` are piped to the ``$match`` pipeline operator. It returns the documents with the value of ``total_pop`` field greater than or equal to 10 million.
+
+Average City Population by State
+--------------------------------
+
+To get the first three states with the greatest average population per city, use the following aggregation:
+
+.. code-block:: none
+
+  pipeline = BCON_NEW ("pipeline", "[",
+     "{", "$group", "{", "_id", "{", "state", "$state", "city", "$city", "}", "pop", "{", "$sum", "$pop", "}", "}", "}",
+     "{", "$group", "{", "_id", "$_id.state", "avg_city_pop", "{", "$avg", "$pop", "}", "}", "}",
+     "{", "$sort", "{", "avg_city_pop", BCON_INT32 (-1), "}", "}",
+     "{", "$limit", BCON_INT32 (3) "}",
+  "]");
+
+This aggregate pipeline produces:
+
+.. code-block:: none
+
+  { "_id" : "DC", "avg_city_pop" : 303450.0 }
+  { "_id" : "FL", "avg_city_pop" : 27942.29805615551 }
+  { "_id" : "CA", "avg_city_pop" : 27735.341099720412 }
+
+The above aggregation pipeline is build from three pipeline operators: ``$group``, ``$sort`` and ``$limit``.
+
+The first ``$group`` operator creates the following documents:
+
+.. code-block:: none
+
+  { "_id" : { "state" : "WY", "city" : "Smoot" }, "pop" : 414 }
+
+Note, that the ``$group`` operator can't use nested documents except the ``_id`` field.
+
+The second ``$group`` uses these documents to create the following documents:
+
+.. code-block:: none
+
+  { "_id" : "FL", "avg_city_pop" : 27942.29805615551 }
+
+These documents are sorted by the ``avg_city_pop`` field in descending order. Finally, the ``$limit`` pipeline operator returns the first 3 documents from the sorted set.
+