boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-02 06:15:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source
This commit is contained in:
Vinnie Falco
2017-06-16 19:27:00 -07:00
parent fd9a13b11f
commit 8b732f94f4
35 changed files with 111 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/0_main.qbk
View File

@@ -87,7 +87,7 @@
[import ../test/websocket/doc_snippets.cpp] [import ../test/websocket/doc_snippets.cpp]
[import ../test/websocket/ssl/doc_snippets.cpp] [import ../test/websocket/ssl/doc_snippets.cpp]
[include 1_overview.qbk] [include 1_intro.qbk]
[include 2_examples.qbk] [include 2_examples.qbk]
[include 3_0_core.qbk] [include 3_0_core.qbk]
[include 5_00_http.qbk] [include 5_00_http.qbk]

2
doc/1_overview.qbk → doc/1_intro.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Beast is a C++ header-only library serving as a foundation for writing
interoperable networking libraries by providing [*low-level HTTP/1, interoperable networking libraries by providing [*low-level HTTP/1,

117
doc/2_examples.qbk
View File

@@ -5,15 +5,9 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:example Examples] [section Quick Start]
[block'''<?dbhtml stop-chunking?>'''] [block'''<?dbhtml stop-chunking?>''']
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] [section HTTP Client]
Use HTTP to make a GET request to a website and print the response: 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] [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'''<?dbhtml stop-chunking?>''']
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)] [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)] [section WebSocket Client (with SSL)]
Establish a WebSocket connection over an encrypted TLS connection, 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] [section Server Framework]
This is a complete program and framework of classes implementing 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] [endsect]

2
doc/3_0_core.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 This library makes network primitives used by the implementation publicly
available so users can take advantage of them in their own libraries. available so users can take advantage of them in their own libraries.

2
doc/3_1_asio.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 [warning
Beast does not manage sockets, make outgoing connections, Beast does not manage sockets, make outgoing connections,

2
doc/3_2_streams.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 A __Stream__ is a communication channel where data is transferred as
an ordered sequence of octet buffers. Streams are either synchronous an ordered sequence of octet buffers. Streams are either synchronous

2
doc/3_3_buffers.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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__ __Asio__ provides the __ConstBufferSequence__ and __MutableBufferSequence__
concepts, whose models provide ranges of buffers, as well as the __streambuf__ concepts, whose models provide ranges of buffers, as well as the __streambuf__

4
doc/3_4_composed.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:composed Composed Operations] [section Composed Operations]
[block'''<?dbhtml stop-chunking?>'''] [block'''<?dbhtml stop-chunking?>''']
Asynchronous operations are started by calling a free function or member 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]. Here we develop an asynchronous composed operation called [*echo].
This operation will read up to the first newline on a stream, and This operation will read up to the first newline on a stream, and

2
doc/3_5_detect_ssl.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 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 of the SSL handshake given an input buffer sequence. Then we build on

2
doc/5_00_http.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:http Using HTTP] [section Using HTTP]
[warning [warning
Higher level functions such as Basic Higher level functions such as Basic

2
doc/5_01_primer.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 The HTTP protocol defines the
[@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]: [@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]:

2
doc/5_02_message.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Beast provides a single class template __message__ which models
HTTP/1 and HTTP/1 and

2
doc/5_03_streams.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Beast provides synchronous and asynchronous algorithms to parse and
serialize HTTP/1 wire format messages on streams. These functions form serialize HTTP/1 wire format messages on streams. These functions form

2
doc/5_04_serializer_streams.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Non-trivial algorithms need to do more than send entire messages
at once, such as: at once, such as:

2
doc/5_05_parser_streams.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Non-trivial algorithms need to do more than receive entire messages
at once, such as: at once, such as:

2
doc/5_06_serializer_buffers.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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'''<?dbhtml stop-chunking?>'''] [block'''<?dbhtml stop-chunking?>''']
An instance of __serializer__ can be invoked directly, without using An instance of __serializer__ can be invoked directly, without using

2
doc/5_07_parser_buffers.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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'''<?dbhtml stop-chunking?>'''] [block'''<?dbhtml stop-chunking?>''']
A subclass of __basic_parser__ can be invoked directly, without using A subclass of __basic_parser__ can be invoked directly, without using

23
doc/5_08_custom_body.qbk
View File

@@ -5,14 +5,31 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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'''<?dbhtml stop-chunking?>'''] [block'''<?dbhtml stop-chunking?>''']
User-defined types are possible for the message body, where the type meets the User-defined types are possible for the message body, where the type meets the
__Body__ requirements. This simplified class declaration __Body__ requirements. This simplified class declaration
shows the customization points available to user-defined body types: 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 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 Use of the flexible __Body__ concept customization point enables authors to
preserve the self-contained nature of the __message__ object while allowing preserve the self-contained nature of the __message__ object while allowing

2
doc/5_09_custom_parsers.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 While the parsers included in the library will handle a broad number of
use-cases, the __basic_parser__ interface can be subclassed to implement use-cases, the __basic_parser__ interface can be subclassed to implement

2
doc/7_0_websocket.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 The WebSocket Protocol enables two-way communication between a client
running untrusted code in a controlled environment to a remote host that has running untrusted code in a controlled environment to a remote host that has

2
doc/7_1_streams.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 The interface to the WebSocket implementation is a single template class
[link beast.ref.beast__websocket__stream `stream`] [link beast.ref.beast__websocket__stream `stream`]

2
doc/7_2_connect.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 Connections are established by invoking functions directly on the next layer
object. For example, to make an outgoing connection using a standard TCP/IP object. For example, to make an outgoing connection using a standard TCP/IP

2
doc/7_3_client.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 A WebSocket session begins when a client sends the HTTP/1
[@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade] [@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade]

2
doc/7_4_server.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
] ]
[section:server Handshaking (Servers)] [section Handshaking (Servers)]
A A
[link beast.ref.beast__websocket__stream `stream`] [link beast.ref.beast__websocket__stream `stream`]

2
doc/7_5_messages.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 After the WebSocket handshake is accomplished, callers may send and receive
messages using the message oriented interface. This interface requires that messages using the message oriented interface. This interface requires that

2
doc/7_6_control.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 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 in an individual WebSocket frame. They may be sent at any time by either

2
doc/7_7_notes.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 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 interface to calls that read data require an object that meets the requirements

2
doc/9_0_design.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 The implementations were originally driven by business needs of cryptocurrency
server applications (e.g. [@https://github.com/ripple/rippled rippled]), server applications (e.g. [@https://github.com/ripple/rippled rippled]),

2
doc/9_1_http_message.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 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 how the library arrived at its solution, with a discussion of the benefits

2
doc/9_2_http_comparison.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 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 protocol. We analyze the message model chosen by those libraries and discuss

2
doc/9_3_websocket_zaphoyd.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 [variablelist

2
doc/9_4_faq.qbk
View File

@@ -5,7 +5,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 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 To set realistic expectations and prevent a litany of duplicate review
statements, these notes address the most common questions and comments statements, these notes address the most common questions and comments

1
doc/Jamfile
View File

@@ -32,7 +32,6 @@ install images
: :
[ glob $(broot)/doc/src/images/*.png ] [ glob $(broot)/doc/src/images/*.png ]
images/beast.png images/beast.png
images/body.png
images/message.png images/message.png
: :
<location>$(out)/html/images <location>$(out)/html/images

BIN
doc/images/body.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.9 KiB

BIN
doc/images/body.psd
View File

Binary file not shown.