diff --git a/README.md b/README.md index f136553f..60458878 100644 --- a/README.md +++ b/README.md @@ -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 +``` + +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 +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 diff --git a/include/boost/beast/websocket/stream_base.hpp b/include/boost/beast/websocket/stream_base.hpp index 23e662b3..0a30f0dd 100644 --- a/include/boost/beast/websocket/stream_base.hpp +++ b/include/boost/beast/websocket/stream_base.hpp @@ -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). */ diff --git a/test/beast/websocket/CMakeLists.txt b/test/beast/websocket/CMakeLists.txt index 4f643038..c7cee35b 100644 --- a/test/beast/websocket/CMakeLists.txt +++ b/test/beast/websocket/CMakeLists.txt @@ -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 diff --git a/test/beast/websocket/Jamfile b/test/beast/websocket/Jamfile index 70de6247..9fe5cc4e 100644 --- a/test/beast/websocket/Jamfile +++ b/test/beast/websocket/Jamfile @@ -24,6 +24,7 @@ local SOURCES = rfc6455.cpp role.cpp stream.cpp + stream_base.cpp stream_explicit.cpp stream_fwd.cpp teardown.cpp diff --git a/test/beast/websocket/stream_base.cpp b/test/beast/websocket/stream_base.cpp new file mode 100644 index 00000000..5bf1b1d5 --- /dev/null +++ b/test/beast/websocket/stream_base.cpp @@ -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 + +#include + +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 diff --git a/test/doc/websocket_snippets.cpp b/test/doc/websocket_snippets.cpp index 6e108926..0b25c6f2 100644 --- a/test/doc/websocket_snippets.cpp +++ b/test/doc/websocket_snippets.cpp @@ -60,96 +60,20 @@ boost::ignore_unused(ec); //[ws_snippet_6 std::string const host = "example.com"; net::ip::tcp::resolver r{ioc}; - stream ws{ioc}; + stream> 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 ws{acceptor.get_executor().context()}; - acceptor.accept(ws.next_layer()); + stream> ws{acceptor.get_executor().context()}; + acceptor.accept(get_lowest_layer(ws).socket()); //] } -{ - stream 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 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 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 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 ws{ioc}; //[ws_snippet_15