diff --git a/doc/0_main.qbk b/doc/0_main.qbk index d8772b20..f291cce9 100644 --- a/doc/0_main.qbk +++ b/doc/0_main.qbk @@ -87,7 +87,7 @@ [import ../test/websocket/doc_snippets.cpp] [import ../test/websocket/ssl/doc_snippets.cpp] -[include 1_overview.qbk] +[include 1_intro.qbk] [include 2_examples.qbk] [include 3_0_core.qbk] [include 5_00_http.qbk] diff --git a/doc/1_overview.qbk b/doc/1_intro.qbk similarity index 99% rename from doc/1_overview.qbk rename to doc/1_intro.qbk index 3cdf4c6c..e667f9b5 100644 --- a/doc/1_overview.qbk +++ b/doc/1_intro.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:overview Introduction] +[section Introduction] Beast is a C++ header-only library serving as a foundation for writing interoperable networking libraries by providing [*low-level HTTP/1, diff --git a/doc/2_examples.qbk b/doc/2_examples.qbk index e8df84f7..d22759a6 100644 --- a/doc/2_examples.qbk +++ b/doc/2_examples.qbk @@ -5,15 +5,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:example Examples] +[section Quick Start] [block''''''] -These complete programs are intended to quickly impress upon readers the -flavor of the library. Source code and build scripts for them are located -in the examples directory. - - - [section HTTP Client] Use HTTP to make a GET request to a website and print the response: @@ -24,6 +18,38 @@ File: [repo_file example/http-client/http_client.cpp] [endsect] +[section WebSocket Client] + +Establish a WebSocket connection, send a message and receive the reply: + +File: [repo_file example/websocket-client/websocket_client.cpp] + +[example_websocket_client] + +[endsect] + +[endsect] + + + +[section Examples] +[block''''''] + +These complete programs are intended to quickly impress upon readers the +flavor of the library. Source code and build scripts for them are located +in the examples directory. + + + +[section HTTP Crawl] + +This example retrieves the page at each of the most popular domains +as measured by Alexa. + +* [repo_file example/http-crawl/http_crawl.cpp] + +[endsect] + [section HTTP Client (with SSL)] @@ -37,29 +63,6 @@ over a TLS connection. Requires OpenSSL to build. -[section HTTP Crawl] - -This example retrieves the page at each of the most popular domains -as measured by Alexa. - -* [repo_file example/http-crawl/http_crawl.cpp] - -[endsect] - - - -[section WebSocket Client] - -Establish a WebSocket connection, send a message and receive the reply: - -File: [repo_file example/websocket-client/websocket_client.cpp] - -[example_websocket_client] - -[endsect] - - - [section WebSocket Client (with SSL)] Establish a WebSocket connection over an encrypted TLS connection, @@ -71,6 +74,33 @@ send a message and receive the reply. Requires OpenSSL to build. +[section Documentation Samples] + +Here are all of the example functions and classes presented +throughout the documentation, they can be included and used +in your program without modification + +* [repo_file example/doc/core_examples.hpp] + +* [repo_file example/doc/http_examples.hpp] + +[endsect] + + + +[section Composed Operations] + +This program shows how to use Beast's network foundations to build a +composable asynchronous initiation function with associated composed +operation implementation. This is a complete, runnable version of +the example described in the Core Foundations document section. + +* [repo_file example/echo-op/echo_op.cpp] + +[endsect] + + + [section Server Framework] This is a complete program and framework of classes implementing @@ -96,31 +126,4 @@ for writing their own servers. It serves both HTTP and WebSocket. -[section Composed Operations] - -This program shows how to use Beast's network foundations to build a -composable asynchronous initiation function with associated composed -operation implementation. This is a complete, runnable version of -the example described in the Core Foundations document section. - -* [repo_file example/echo-op/echo_op.cpp] - -[endsect] - - - -[section Documentation Samples] - -Here are all of the example functions and classes presented -throughout the documentation, they can be included and used -in your program without modification - -* [repo_file example/doc/core_examples.hpp] - -* [repo_file example/doc/http_examples.hpp] - -[endsect] - - - [endsect] diff --git a/doc/3_0_core.qbk b/doc/3_0_core.qbk index 035fed75..01a18d32 100644 --- a/doc/3_0_core.qbk +++ b/doc/3_0_core.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:core Using Networking] +[section Using Networking] This library makes network primitives used by the implementation publicly available so users can take advantage of them in their own libraries. diff --git a/doc/3_1_asio.qbk b/doc/3_1_asio.qbk index bd10a716..9070dac7 100644 --- a/doc/3_1_asio.qbk +++ b/doc/3_1_asio.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:asio Boost.Asio Refresher] +[section Asio Refresher] [warning Beast does not manage sockets, make outgoing connections, diff --git a/doc/3_2_streams.qbk b/doc/3_2_streams.qbk index 1c49dd30..13773125 100644 --- a/doc/3_2_streams.qbk +++ b/doc/3_2_streams.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:streams Stream Types] +[section Stream Types] A __Stream__ is a communication channel where data is transferred as an ordered sequence of octet buffers. Streams are either synchronous diff --git a/doc/3_3_buffers.qbk b/doc/3_3_buffers.qbk index bac0b568..6fdc2632 100644 --- a/doc/3_3_buffers.qbk +++ b/doc/3_3_buffers.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:buffers Buffer Types] +[section Buffer Types] __Asio__ provides the __ConstBufferSequence__ and __MutableBufferSequence__ concepts, whose models provide ranges of buffers, as well as the __streambuf__ diff --git a/doc/3_4_composed.qbk b/doc/3_4_composed.qbk index 48f9cc98..2e7e70a2 100644 --- a/doc/3_4_composed.qbk +++ b/doc/3_4_composed.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:composed Composed Operations] +[section Composed Operations] [block''''''] Asynchronous operations are started by calling a free function or member @@ -103,7 +103,7 @@ available: -[section Asynchronous Echo] +[section Echo] Here we develop an asynchronous composed operation called [*echo]. This operation will read up to the first newline on a stream, and diff --git a/doc/3_5_detect_ssl.qbk b/doc/3_5_detect_ssl.qbk index 3fe70cbd..087e973c 100644 --- a/doc/3_5_detect_ssl.qbk +++ b/doc/3_5_detect_ssl.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:detect_tls Example: Detect SSL] +[section Example: Detect SSL] In this example we will build a simple function to detect the presence of the SSL handshake given an input buffer sequence. Then we build on diff --git a/doc/5_00_http.qbk b/doc/5_00_http.qbk index 62d7b681..6a90c066 100644 --- a/doc/5_00_http.qbk +++ b/doc/5_00_http.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:http Using HTTP] +[section Using HTTP] [warning Higher level functions such as Basic diff --git a/doc/5_01_primer.qbk b/doc/5_01_primer.qbk index b42e9e7b..26501748 100644 --- a/doc/5_01_primer.qbk +++ b/doc/5_01_primer.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:primer Protocol Primer] +[section Protocol Primer] The HTTP protocol defines the [@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]: diff --git a/doc/5_02_message.qbk b/doc/5_02_message.qbk index b457c2af..f9391bbd 100644 --- a/doc/5_02_message.qbk +++ b/doc/5_02_message.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:message Message Containers] +[section Message Containers] Beast provides a single class template __message__ which models HTTP/1 and diff --git a/doc/5_03_streams.qbk b/doc/5_03_streams.qbk index 1107a9ba..8209078b 100644 --- a/doc/5_03_streams.qbk +++ b/doc/5_03_streams.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:streams Message Stream Operations] +[section Message Stream Operations] Beast provides synchronous and asynchronous algorithms to parse and serialize HTTP/1 wire format messages on streams. These functions form diff --git a/doc/5_04_serializer_streams.qbk b/doc/5_04_serializer_streams.qbk index df0ba9eb..90c9297b 100644 --- a/doc/5_04_serializer_streams.qbk +++ b/doc/5_04_serializer_streams.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:serializer_streams Serializer Stream Operations] +[section Serializer Stream Operations] Non-trivial algorithms need to do more than send entire messages at once, such as: diff --git a/doc/5_05_parser_streams.qbk b/doc/5_05_parser_streams.qbk index e5e5d009..f3edfa3a 100644 --- a/doc/5_05_parser_streams.qbk +++ b/doc/5_05_parser_streams.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:parser_streams Parser Stream Operations] +[section Parser Stream Operations] Non-trivial algorithms need to do more than receive entire messages at once, such as: diff --git a/doc/5_06_serializer_buffers.qbk b/doc/5_06_serializer_buffers.qbk index f2250919..79587881 100644 --- a/doc/5_06_serializer_buffers.qbk +++ b/doc/5_06_serializer_buffers.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:serializer_buffers Buffer-Oriented Serializing] +[section Buffer-Oriented Serializing] [block''''''] An instance of __serializer__ can be invoked directly, without using diff --git a/doc/5_07_parser_buffers.qbk b/doc/5_07_parser_buffers.qbk index 2f966271..a3455394 100644 --- a/doc/5_07_parser_buffers.qbk +++ b/doc/5_07_parser_buffers.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:parser_buffers Buffer-Oriented Parsing] +[section Buffer-Oriented Parsing] [block''''''] A subclass of __basic_parser__ can be invoked directly, without using diff --git a/doc/5_08_custom_body.qbk b/doc/5_08_custom_body.qbk index 2872e1ef..a3bfff7b 100644 --- a/doc/5_08_custom_body.qbk +++ b/doc/5_08_custom_body.qbk @@ -5,14 +5,31 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:custom_body Custom Body Types] +[section Custom Body Types] [block''''''] User-defined types are possible for the message body, where the type meets the __Body__ requirements. This simplified class declaration shows the customization points available to user-defined body types: +``` +/// Defines a Body type +struct body +{ + /// This determines the type of the `message::body` member + using value_type = ...; -[$images/body.png [width 525px] [height 190px]] + /// An optional function, returns the body's payload size + static + std::uint64_t + size(value_type const& v); + + /// The algorithm used for extracting buffers + class reader; + + /// The algorithm used for inserting buffers + class writer; +} +``` The meaning of the nested types is as follows @@ -80,7 +97,7 @@ those bodies may be serialized or parsed. -[section File Body Type] +[section File Body] Use of the flexible __Body__ concept customization point enables authors to preserve the self-contained nature of the __message__ object while allowing diff --git a/doc/5_09_custom_parsers.qbk b/doc/5_09_custom_parsers.qbk index 4e0f2370..fbecba3e 100644 --- a/doc/5_09_custom_parsers.qbk +++ b/doc/5_09_custom_parsers.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:custom_parsers Custom Parsers] +[section Custom Parsers] While the parsers included in the library will handle a broad number of use-cases, the __basic_parser__ interface can be subclassed to implement diff --git a/doc/7_0_websocket.qbk b/doc/7_0_websocket.qbk index 85621f0c..7e2e03a5 100644 --- a/doc/7_0_websocket.qbk +++ b/doc/7_0_websocket.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:websocket Using WebSocket] +[section Using WebSocket] The WebSocket Protocol enables two-way communication between a client running untrusted code in a controlled environment to a remote host that has diff --git a/doc/7_1_streams.qbk b/doc/7_1_streams.qbk index 489d8654..93e12f6e 100644 --- a/doc/7_1_streams.qbk +++ b/doc/7_1_streams.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:streams Creating Streams] +[section Creating Streams] The interface to the WebSocket implementation is a single template class [link beast.ref.beast__websocket__stream `stream`] diff --git a/doc/7_2_connect.qbk b/doc/7_2_connect.qbk index 19716b77..a7f8f233 100644 --- a/doc/7_2_connect.qbk +++ b/doc/7_2_connect.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:connect Establishing Connections] +[section Establishing Connections] Connections are established by invoking functions directly on the next layer object. For example, to make an outgoing connection using a standard TCP/IP diff --git a/doc/7_3_client.qbk b/doc/7_3_client.qbk index 0ebdf603..65a0e651 100644 --- a/doc/7_3_client.qbk +++ b/doc/7_3_client.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:client Handshaking (Clients)] +[section Handshaking (Clients)] A WebSocket session begins when a client sends the HTTP/1 [@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade] diff --git a/doc/7_4_server.qbk b/doc/7_4_server.qbk index f2d90fc3..f32b3105 100644 --- a/doc/7_4_server.qbk +++ b/doc/7_4_server.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:server Handshaking (Servers)] +[section Handshaking (Servers)] A [link beast.ref.beast__websocket__stream `stream`] diff --git a/doc/7_5_messages.qbk b/doc/7_5_messages.qbk index 88e973d3..9518d37a 100644 --- a/doc/7_5_messages.qbk +++ b/doc/7_5_messages.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:messages Send and Receive Messages] +[section Send and Receive Messages] After the WebSocket handshake is accomplished, callers may send and receive messages using the message oriented interface. This interface requires that diff --git a/doc/7_6_control.qbk b/doc/7_6_control.qbk index c94edf80..ec79be7d 100644 --- a/doc/7_6_control.qbk +++ b/doc/7_6_control.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:control Control Frames] +[section Control Frames] Control frames are small (less than 128 bytes) messages entirely contained in an individual WebSocket frame. They may be sent at any time by either diff --git a/doc/7_7_notes.qbk b/doc/7_7_notes.qbk index 83650b50..2444072c 100644 --- a/doc/7_7_notes.qbk +++ b/doc/7_7_notes.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:notes Notes] +[section Notes] Because calls to read data may return a variable amount of bytes, the interface to calls that read data require an object that meets the requirements diff --git a/doc/9_0_design.qbk b/doc/9_0_design.qbk index 7cdd66a8..8b4c0a0d 100644 --- a/doc/9_0_design.qbk +++ b/doc/9_0_design.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:design Design Choices] +[section Design Choices] The implementations were originally driven by business needs of cryptocurrency server applications (e.g. [@https://github.com/ripple/rippled rippled]), diff --git a/doc/9_1_http_message.qbk b/doc/9_1_http_message.qbk index 2fd40f3b..861cd067 100644 --- a/doc/9_1_http_message.qbk +++ b/doc/9_1_http_message.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:http_message HTTP Message Container] +[section HTTP Message Container] In this section we describe the problem of modeling HTTP messages and explain how the library arrived at its solution, with a discussion of the benefits diff --git a/doc/9_2_http_comparison.qbk b/doc/9_2_http_comparison.qbk index 203a1f84..e181fcb5 100644 --- a/doc/9_2_http_comparison.qbk +++ b/doc/9_2_http_comparison.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:http_comparison HTTP Comparison to Other Libraries] +[section HTTP Comparison to Other Libraries] There are a few C++ published libraries which implement some of the HTTP protocol. We analyze the message model chosen by those libraries and discuss diff --git a/doc/9_3_websocket_zaphoyd.qbk b/doc/9_3_websocket_zaphoyd.qbk index 5868651e..99ea62c3 100644 --- a/doc/9_3_websocket_zaphoyd.qbk +++ b/doc/9_3_websocket_zaphoyd.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:websocket_zaphoyd Comparison to Zaphoyd Studios WebSocket++] +[section Comparison to Zaphoyd Studios WebSocket++] [variablelist diff --git a/doc/9_4_faq.qbk b/doc/9_4_faq.qbk index 96e6730b..dec58392 100644 --- a/doc/9_4_faq.qbk +++ b/doc/9_4_faq.qbk @@ -5,7 +5,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ] -[section:faq FAQ] +[section FAQ] To set realistic expectations and prevent a litany of duplicate review statements, these notes address the most common questions and comments diff --git a/doc/Jamfile b/doc/Jamfile index 4f76c980..24b2cf7e 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -32,7 +32,6 @@ install images : [ glob $(broot)/doc/src/images/*.png ] images/beast.png - images/body.png images/message.png : $(out)/html/images diff --git a/doc/images/body.png b/doc/images/body.png deleted file mode 100644 index 91671f52..00000000 Binary files a/doc/images/body.png and /dev/null differ diff --git a/doc/images/body.psd b/doc/images/body.psd deleted file mode 100644 index 420565d1..00000000 Binary files a/doc/images/body.psd and /dev/null differ