boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-07-29 20:37:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source
This commit is contained in:
Vinnie Falco
2019-02-18 06:04:02 -08:00
parent 3f50efa138
commit bc436da9c5
6 changed files with 105 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@ -69,7 +69,7 @@ create concurrent network programs using callbacks or coroutines.
* **C++11:** Robust support for most language features.
* **Boost:** Boost.Asio and some other parts of Boost.
* **OpenSSL:** Optional, for using TLS/Secure sockets.
* **OpenSSL:** Required for using TLS/Secure sockets and examples/tests
When using Microsoft Visual C++, Visual Studio 2015 Update 3 or later is required.
@ -78,7 +78,26 @@ One of these components is required in order to build the tests and examples:
* Properly configured bjam/b2
* CMake 3.5.1 or later (Windows only)
## Branches
## Building
Beast is header-only. To use it just add the necessary `#include` line
to your source files, like this:
```C++
#include <boost/beast.hpp>
```
If you use coroutines you'll need to link with the Boost.Coroutine
library. Please visit the Boost documentation for instructions
on how to do this for your particular build system.
## GitHub
To use the latest official release of Beast, simply obtain the latest
Boost distribution and follow the instructions for integrating it
into your development environment. If you wish to build the examples
and tests, or if you wish to preview upcoming changes and features,
it is suggested to clone the "Boost superproject" and work with Beast
"in-tree" (meaning, the libs/beast subdirectory of the superproject).
The official repository contains the following branches:
@ -94,42 +113,44 @@ branch version of Beast, you should clone the Boost superproject,
switch to the **master** branch in the superproject and acquire
all the Boost libraries corresponding to that branch including Beast.
Or, to use the latest shipping version of Beast, simply use it
from the corresponding distribution of Boost.
## Building
Beast is header-only. To use it just add the necessary `#include` line
to your source files, like this:
```C++
#include <boost/beast.hpp>
To clone the superproject locally, and switch into the main project's
directory use:
```
git clone --recursive https://github.com/boostorg/boost.git
cd boost
```
If you use coroutines you'll need to link with the Boost.Coroutine
library. Please visit the Boost documentation for instructions
on how to do this for your particular build system.
To build the documentation, examples, tests, and benchmarks it is
necessary to first obtain the Boost "superproject" along with sources of
all of the Boost libraries, then run the `b2` command to build the Boost
libraries.
Instructions for doing so may be found on
the [Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
These commands will build the programs and documentation that come
with Beast:
"bjam" is used to build Beast and the Boost libraries. On a non-Windows
system use this command to build bjam:
```
cd boost # The directory containing the Boost superproject and libraries
b2 libs/beast/test cxxstd=11 # bjam must be in your $PATH
b2 libs/beast/example cxxstd=11
b2 libs/beast/doc
./bootstrap.sh
```
On Windows platforms only, CMake may be used to generate a Visual Studio
solution and a set of Visual Studio project files using these commands:
From a Windows command line, build bjam using this command:
```
.\BOOTSTRAP.BAT
```
Make sure the bjam tool (also called "b2") is available in the path
your shell uses to find executables. The Beast project is located in
"libs/beast" relative to the directory containing the Boot superproject.
To build the Beast tests, examples, and documentation use these commands:
```
b2 -j2 libs/beast/test cxxstd=11 # bjam must be in your $PATH
b2 -j2 libs/beast/example cxxstd=11 # "-j2" means use two processors
b2 libs/beast/doc # Doxygen and Saxon are required for this
```
Additional instructions for configuring, using, and building libraries
in superproject may be found in the
[Boost Wiki](https://github.com/boostorg/boost/wiki/Getting-Started).
## Visual Studio
CMake may be used to generate a very nice Visual Studio solution and
a set of Visual Studio project files using these commands:
```
cd boost # The directory containing the Boost superproject and libraries
cd libs/beast
mkdir bin
cd bin
@ -145,12 +166,11 @@ The files in the repository are laid out thusly:
bin/ Create this to hold executables and project files
bin64/ Create this to hold 64-bit Windows executables and project files
doc/ Source code and scripts for the documentation
include/ Where the header files live
extras/ Additional APIs, may change
include/ Where the header files are located
example/ Self contained example programs
meta/ Metadata for Boost integration
scripts/ Small scripts used with CI systems
test/ Unit tests
test/ The unit tests for Beast
tools/ Scripts used for CI testing
```
## Usage

6
include/boost/beast/websocket/stream_base.hpp
View File

@ -116,6 +116,12 @@ struct stream_base
values are selected upon construction, regardless of the
current or actual role in use on the stream.
@par Example
This statement sets the timeout settings of the stream to
the suggested values for the server role:
@code
@endcode
@param role The role of the websocket stream
(@ref role_type::client or @ref role_type::server).
*/

1
test/beast/websocket/CMakeLists.txt
View File

@ -34,6 +34,7 @@ add_executable (tests-beast-websocket
rfc6455.cpp
role.cpp
stream.cpp
stream_base.cpp
stream_explicit.cpp
stream_fwd.cpp
teardown.cpp

1
test/beast/websocket/Jamfile
View File

@ -24,6 +24,7 @@ local SOURCES =
rfc6455.cpp
role.cpp
stream.cpp
stream_base.cpp
stream_explicit.cpp
stream_fwd.cpp
teardown.cpp

38
test/beast/websocket/stream_base.cpp Normal file
View File

@ -0,0 +1,38 @@
//
// Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/beast
//
// Test that header file is self-contained.
#include <boost/beast/websocket/stream_base.hpp>
#include <boost/beast/_experimental/unit_test/suite.hpp>
namespace boost {
namespace beast {
namespace websocket {
class stream_base_test : public unit_test::suite
{
public:
void
testJavadoc()
{
}
void
run() override
{
testJavadoc();
}
};
BEAST_DEFINE_TESTSUITE(beast,websocket,stream_base);
} // websocket
} // beast
} // boost

84
test/doc/websocket_snippets.cpp
View File

@ -60,96 +60,20 @@ boost::ignore_unused(ec);
//[ws_snippet_6
std::string const host = "example.com";
net::ip::tcp::resolver r{ioc};
stream<net::ip::tcp::socket> ws{ioc};
stream<tcp_stream<net::io_context::executor_type>> ws{ioc};
auto const results = r.resolve(host, "ws");
net::connect(ws.next_layer(), results.begin(), results.end());
connect(get_lowest_layer(ws), results.begin(), results.end());
//]
}
{
//[ws_snippet_7
net::ip::tcp::acceptor acceptor{ioc};
stream<net::ip::tcp::socket> ws{acceptor.get_executor().context()};
acceptor.accept(ws.next_layer());
stream<tcp_stream<net::io_context::executor_type>> ws{acceptor.get_executor().context()};
acceptor.accept(get_lowest_layer(ws).socket());
//]
}
{
stream<net::ip::tcp::socket> ws{ioc};
//[ws_snippet_8
ws.handshake("localhost", "/");
//]
//[ws_snippet_9
ws.handshake_ex("localhost", "/",
[](request_type& m)
{
m.insert(http::field::sec_websocket_protocol, "xmpp;ws-chat");
});
//]
//[ws_snippet_10
response_type res;
ws.handshake(res, "localhost", "/");
if(! res.count(http::field::sec_websocket_protocol))
throw std::invalid_argument("missing subprotocols");
//]
//[ws_snippet_11
ws.accept();
//]
//[ws_snippet_12
ws.accept_ex(
[](response_type& m)
{
m.insert(http::field::server, "MyServer");
});
//]
}
{
//[ws_snippet_13]
// Buffer required for reading HTTP messages
flat_buffer buffer;
// Read the HTTP request ourselves
http::request<http::string_body> req;
http::read(sock, buffer, req);
// See if its a WebSocket upgrade request
if(websocket::is_upgrade(req))
{
// Construct the stream, transferring ownership of the socket
stream<net::ip::tcp::socket> ws{std::move(sock)};
// Clients SHOULD NOT begin sending WebSocket
// frames until the server has provided a response.
BOOST_ASSERT(buffer.size() == 0);
// Accept the upgrade request
ws.accept(req);
}
else
{
// Its not a WebSocket upgrade, so
// handle it like a normal HTTP request.
}
//]
}
{
stream<net::ip::tcp::socket> ws{ioc};
//[ws_snippet_14
// Read into our buffer until we reach the end of the HTTP request.
// No parsing takes place here, we are just accumulating data.
net::streambuf buffer;
net::read_until(sock, buffer, "\r\n\r\n");
// Now accept the connection, using the buffered data.
ws.accept(buffer.data());
//]
}
{
stream<net::ip::tcp::socket> ws{ioc};
//[ws_snippet_15