Skip to content

Commit f034299

Browse files
committed
Updating packaged documentation for cpp-netlib 0.9.
1 parent 5b82adf commit f034299

38 files changed

+972
-247
lines changed

libs/network/doc/html/_sources/reference_http_client.txt

Lines changed: 56 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,12 @@ Also, that code using the HTTP client will have use the following header:
122122

123123
#include <boost/network/include/http/client.hpp>
124124

125+
.. note:: Starting version 0.9, cpp-netlib clients and server implementations
126+
by default now have an externally-linked component. This is a breaking change
127+
for code that used to rely on cpp-netlib being a header-only library, but can
128+
inhibited by defining the ``BOOST_NETWORK_NO_LIB`` preprocessor macro before
129+
including any cpp-netlib header.
130+
125131
Constructors
126132
~~~~~~~~~~~~
127133

@@ -130,18 +136,55 @@ initialization.
130136

131137
``client()``
132138
Default constructor.
133-
``client(client::cache_resolved)``
134-
Construct a client which caches resolved endpoints.
135-
``client(client::follow_redirects)``
136-
Construct a client which follows HTTP redirects. [#]_
137-
``client(client::cache_resolved, client::follow_redirects), client(client::follow_redirects, client::cache_resolved)``
138-
Construct a client which caches resolved endpoints and follows HTTP
139-
redirects. [#]_
140-
141-
.. [#] In Asynchronous Clients, redirects are not followed. This means the
142-
response objects will contain whatever HTTP response was retrieved by the
143-
client implementation.
144-
.. [#] In Asynchronous Clients, only caching resolved endpoints take effect.
139+
``client(boost::asio::io_service & io_service)``
140+
Construct a client to use an existing Boost.Asio ``io_service`` instance.
141+
``template <class ArgPack> client(ArgPack const & args)``
142+
Pass in an argument pack. See supported parameters in the table below.
143+
144+
+----------------------+-------------------------------+-------------------------+
145+
| Parameter Name | Type | Description |
146+
+======================+===============================+=========================+
147+
| _follow_redirects | ``bool`` | Boolean to specify |
148+
| | | whether the client |
149+
| | | should follow HTTP |
150+
| | | redirects. Default is |
151+
| | | ``false``. |
152+
+----------------------+-------------------------------+-------------------------+
153+
| _cache_resolved | ``bool`` | Boolean to specify |
154+
| | | whether the client |
155+
| | | should cache resolved |
156+
| | | endpoints. The default |
157+
| | | is ``false``. |
158+
+----------------------+-------------------------------+-------------------------+
159+
| _io_service | ``boost::asio::io_service &`` | Reference to an |
160+
| | | instance of a |
161+
| | | Boost.Asio |
162+
| | | ``io_service``. |
163+
+----------------------+-------------------------------+-------------------------+
164+
| _openssl_certificate | string | The filename of the |
165+
| | | certificate to load for |
166+
| | | the SSL connection for |
167+
| | | verification. |
168+
+----------------------+-------------------------------+-------------------------+
169+
| _openssl_verify_path | string | The directory from |
170+
| | | which the certificate |
171+
| | | authority files are |
172+
| | | located. |
173+
+----------------------+-------------------------------+-------------------------+
174+
175+
176+
To use the above supported named parameters, you'll have code that looks like
177+
the following:
178+
179+
.. code-block:: c++
180+
181+
using namespace boost::network::http; // parameters are in this namespace
182+
boost::asio::io_service my_io_service;
183+
client client_(_follow_redirects=true, _cache_resolved=true,
184+
_io_service=my_io_service
185+
, _openssl_certificate="/tmp/my-cert"
186+
, _openssl_verify_path="/tmp/ca-certs/");
187+
// use client_ as normal from here on out.
145188

146189
HTTP Methods
147190
~~~~~~~~~~~~
@@ -193,3 +236,4 @@ Client-Specific
193236
``client_.clear_resolved_cache()``
194237
Clear the cache of resolved endpoints.
195238

239+

libs/network/doc/html/_sources/reference_http_server.txt

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,70 @@ Constructor
172172
``std::string const &`` and handler being of type ``handler_type`` but
173173
passed in as an lvalue reference.
174174

175+
``template <class ArgPack> client(ArgPack const & args)``
176+
Pass in an argument pack. See supported parameters in the table below.
177+
178+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
179+
| Parameter Name | Type | Description |
180+
+========================+==========================================+==================================================================================================+
181+
| _address | string_type | The hostname or IP address from which the server should be bound to. This parameter is required. |
182+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
183+
| _port | string_type | The port to which the server should bind and listen to. This parameter is required. |
184+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
185+
| _handler | ``Handler &`` | An lvalue reference to an instance of ``Handler``. This parameter is required. |
186+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
187+
| _thread_pool | ``boost::network::utils::thread_pool &`` | An lvalue reference to an instance of ``boost::network::utils::thread_pool`` -- this is the |
188+
| | | thread pool from where the handler is invoked. This parameter is only applicable and required |
189+
| | | for ``async_server`` instances. |
190+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
191+
| _io_service | ``boost::asio::io_service &`` | An optional lvalue to an instance of ``boost::asio::io_service`` which allows the server to use |
192+
| | | an already-constructed ``boost::asio::io_service`` instance instead of instantiating one that it |
193+
| | | manages. |
194+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
195+
| _reuse_address | ``bool`` | A boolean that specifies whether to re-use the address and port on which the server will be |
196+
| | | bound to. This enables or disables the socket option for listener sockets. The default is |
197+
| | | ``false``. |
198+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
199+
| _report_aborted | ``bool`` | A boolean that specifies whether the listening socket should report aborted connection attempts |
200+
| | | to the accept handler (an internal detail of cpp-netlib). This is put in place to allow for |
201+
| | | future-proofing the code in case an optional error handler function is supported in later |
202+
| | | releases of cpp-netlib. The default is ``false``. |
203+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
204+
| _receive_buffer_size | ``int`` | The size of the socket's receive buffer. The default is defined by Boost.Asio and is |
205+
| | | platform-dependent. |
206+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
207+
| _send_buffer_size | ``int`` | The size of the socket's send buffer. The default is defined by Boost.Asio and is |
208+
| | | platform-dependent. |
209+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
210+
| _receive_low_watermark | ``int`` | The size of the socket's low watermark for its receive buffer. The default is defined by |
211+
| | | Boost.Asio and is platform-dependent. |
212+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
213+
| _send_buffer_size | ``int`` | The size of the socket's send low watermark for its send buffer. The default is defined by |
214+
| | | Boost.Asio and is platform-dependent. |
215+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
216+
| _non_blocking_io | ``bool`` | An optional bool to define whether the socket should use non-blocking I/O in case the platform |
217+
| | | supports it. The default is ``true``. |
218+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
219+
| _linger | ``bool`` | An optional bool to determine whether the socket should linger in case there's still data to be |
220+
| | | sent out at the time of its closing. The default is ``true``. |
221+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
222+
| _linger_timeout | ``int`` | An optional int to define the timeout to wait for socket closes before it is set to linger. |
223+
| | | The default is ``0``. |
224+
+------------------------+------------------------------------------+--------------------------------------------------------------------------------------------------+
225+
226+
To use the above supported named parameters, you'll have code that looks like the following:
227+
228+
.. code-block:: c++
229+
230+
using namespace boost::network::http; // parameters are in this namespace
231+
boost::asio::io_service my_io_service;
232+
boost::network::utils::thread_pool pool(2);
233+
handler handler_instance;
234+
async_server<handler> instance(_address="0.0.0.0", _port="80", _handler=handler_instance,
235+
_io_service=my_io_service, _thread_pool=pool,
236+
_reuse_address=true);
237+
instance.run();
238+
175239
Public Members
176240
``````````````
177241

libs/network/doc/html/_sources/whats_new.txt

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,24 @@
44
What's New
55
************
66

7+
:mod:`cpp-netlib` 0.9
8+
---------------------
9+
10+
* **IMPORTANT BREAKING CHANGE**: By default all compile-time heavy parser
11+
implementations are now compiled to external static libraries. In order to use
12+
:mod:`cpp-netlib` in header-only mode, users must define the preprocessor
13+
macro ``BOOST_NETWORK_NO_LIB`` before including any :mod:`cpp-netlib` header.
14+
This breaks code that relied on the version 0.8.x line where the library is
15+
strictly header-only.
16+
* More consistent message API for client and server messages (request and
17+
response objects).
18+
* Refactoring of internal implementations to allow better separation of concerns
19+
and more manageable coding/documentation.
20+
* Client and Server constructors that support Boost.Parameter named parameters.
21+
* Client and Server cosntructors now take in an optional reference to a Boost.Asio
22+
``io_service`` to use internally.
23+
* Documentation updates to reflect new APIs.
24+
725
:mod:`cpp-netlib` 0.8
826
---------------------
927

libs/network/doc/html/_static/basic.css

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*
55
* Sphinx stylesheet -- basic theme.
66
*
7-
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
7+
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
88
* :license: BSD, see LICENSE for details.
99
*
1010
*/
@@ -213,6 +213,24 @@ p.rubric {
213213
font-weight: bold;
214214
}
215215

216+
img.align-left, .figure.align-left, object.align-left {
217+
clear: left;
218+
float: left;
219+
margin-right: 1em;
220+
}
221+
222+
img.align-right, .figure.align-right, object.align-right {
223+
clear: right;
224+
float: right;
225+
margin-left: 1em;
226+
}
227+
228+
img.align-center, .figure.align-center, object.align-center {
229+
display: block;
230+
margin-left: auto;
231+
margin-right: auto;
232+
}
233+
216234
.align-left {
217235
text-align: left;
218236
}
@@ -395,7 +413,7 @@ dl.glossary dt {
395413
}
396414

397415
.footnote:target {
398-
background-color: #ffa
416+
background-color: #ffa;
399417
}
400418

401419
.line-block {
@@ -426,6 +444,7 @@ dl.glossary dt {
426444

427445
pre {
428446
overflow: auto;
447+
overflow-y: hidden; /* fixes display issues on Chrome browsers */
429448
}
430449

431450
td.linenos pre {

libs/network/doc/html/_static/cpp-netlib.css

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
@import url(reset-fonts-grids.css);
22

3-
html, body {background-image: url(./background.jpg); background-repeat:no-repeat; background-position:right top; background-attachment:fixed}
3+
html, body {background-image: url(./orange-background.jpg); background-repeat:no-repeat; background-position:left top; background-attachment:fixed; background-color:black}
44
body {font:12pt "Times New Roman", Lucida, serif; color:black}
55
#custom-doc { width:80%;*width:720px; min-width:720px; max-width:960px; margin:auto; text-align:left; padding-top:16px; margin-top:0}
66
#hd { padding: 4px 0 12px 0}

libs/network/doc/html/_static/doctools.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*
55
* Sphinx JavaScript utilties for all documentation.
66
*
7-
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
7+
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
88
* :license: BSD, see LICENSE for details.
99
*
1010
*/
Loading

libs/network/doc/html/_static/searchtools.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*
55
* Sphinx JavaScript utilties for the full-text search.
66
*
7-
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
7+
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
88
* :license: BSD, see LICENSE for details.
99
*
1010
*/

libs/network/doc/html/_static/sphinxdoc.css

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
* Sphinx stylesheet -- sphinxdoc theme. Originally created by
66
* Armin Ronacher for Werkzeug.
77
*
8-
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
8+
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
99
* :license: BSD, see LICENSE for details.
1010
*
1111
*/

0 commit comments

Comments
 (0)