HTTPS Client Feature Documentation

deanberris · deanberris · commit 431b31f44612 · 2014-09-01T23:24:25.000+10:00
These are the source-level changes to document the HTTPS support in the
client. This is useful in explicitly spelling out how to build the
client libraries to support HTTPS URIs in the client.
diff --git a/libs/network/doc/getting_started.rst b/libs/network/doc/getting_started.rst
@@ -114,7 +114,7 @@ the ``~/cpp-netlib`` directory exists, and is the top-level directory of the
 Building with CMake
 ===================
 
-To build the tests that come with cpp-netlib, we first need to configure the
+To build the tests that come with :mod:`cpp-netlib`, we first need to configure the
 build system to use our compiler of choice. This is done by running the
 ``cmake`` command at the top-level directory of :mod:`cpp-netlib` with
 additional parameters::
@@ -131,6 +131,31 @@ additional parameters::
           For the purposes of documentation, we'll assume that all
           builds are done in ``~/cpp-netlib-build``.
 
+If you intend to use the SSL support when using the HTTP client libraries in
+:mod:`cpp-netlib`, you may need to build it with OpenSSL_ installed or at least
+available to CMake. One example for building the library with OpenSSL_ support
+is by doing the following::
+
+    $ cmake -DCMAKE_BUILD_TYPE=Debug \
+    >       -DCMAKE_C_COMPILER=clang \
+    >       -DCMAKE_CXX_COMPILER=clang++ \
+    >       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f
+    >       ../cpp-netlib
+
+.. _OpenSSL: http://www.openssl.org/
+
+You can also use a different root directory for the Boost_ project by using the
+``-DBOOST_ROOT`` configuration option to CMake. This is useful if you intend to
+build the library with a specific version of Boost that you've built in a
+separate directory::
+
+    $ cmake -DCMAKE_BUILD_TYPE=Debug \
+    >       -DCMAKE_C_COMPILER=clang \
+    >       -DCMAKE_CXX_COMPILER=clang++ \
+    >       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f \
+    >       -DBOOST_ROOT=/Users/dberris/Source/boost_1_55_0
+    >       ../cpp-netlib
+
 Building on Linux
 ~~~~~~~~~~~~~~~~~
 
@@ -178,8 +203,8 @@ Building On Windows
 ~~~~~~~~~~~~~~~~~~~
 
 If you're using the Microsoft Visual C++ compiler or the Microsoft Visual Studio
-IDE and you would like to build cpp-netlib from within Visual Studio, you can
-look for the solution and project files as the artifacts of the call to
+IDE and you would like to build :mod:`cpp-netlib` from within Visual Studio, you
+can look for the solution and project files as the artifacts of the call to
 ``cmake`` -- the file should be named ``CPP-NETLIB.sln`` (the solution) along
 with a number of project files for Visual Studio.
 
diff --git a/libs/network/doc/index.rst b/libs/network/doc/index.rst
@@ -3,7 +3,7 @@
 
 .. :Authors: Glyn Matthews <glyn.matthews@gmail.com>
 .. 	  Dean Michael Berris <dberris@google.com>
-.. :Date: 2013-12-21
+.. :Date: 2014-10-01
 .. :Version: 0.11.0
 .. :Description: Complete user documentation, with examples, for the :mod:`cpp-netlib`.
 .. :Copyright: Copyright Glyn Matthews, Dean Michael Berris 2008-2013.
diff --git a/libs/network/doc/reference/http_client.rst b/libs/network/doc/reference/http_client.rst
@@ -25,6 +25,23 @@ asynchronous.
 As of 0.11 the `Synchronous Clients`_ are now *DEPRECATED* and will be removed
 in subsequent releases.
 
+Features
+--------
+
+The HTTP client implementation supports requesting secure HTTP (HTTPS) content
+only in the following situations:
+
+  * **Client libraries are built with ``BOOST_NETWORK_ENABLE_HTTPS``.** This
+    tells the implementation to use HTTPS-specific code to handle HTTPS-based
+    content when making connections associated with HTTPS URI's. This requires
+    a dependency on OpenSSL_.
+  * **The ``BOOST_NETWORK_ENABLE_HTTPS`` macro is set when compiling user
+    code.** It is best to define this either at compile-time of all code using
+    the library, or before including any of the client headers.
+
+.. _OpenSSL: http://www.openssl.org/
+
+
 Implementations
 ---------------
 
@@ -126,6 +143,9 @@ operations on responses. In code, usage should look like the following:
 
 A common mistake is to declare the client inside the try block which invokes
 undefined behavior when errors arise from the handling of response objects.
+Previous examples cited by the documentation showed the short version of the
+code which didn't bother moving the ``http::client`` object outside of the same
+``try`` block where the request/response objects are being used.
 
 Member Functions
 ----------------
