role_type is in boost/beast/core/role.hpp (API Change):

This enumeration is now part of the library core and
not specific to websocket.
This commit is contained in:
Vinnie Falco
2019-02-26 07:20:46 -08:00
parent 81f33a0f89
commit 0647c902ac
54 changed files with 395 additions and 345 deletions
@@ -7,7 +7,7 @@
Official repository: https://github.com/boostorg/beast
]
[section Using HTTP]
[section:using_http HTTP]
[warning
Higher level functions such as Basic
@@ -7,7 +7,7 @@
Official repository: https://github.com/boostorg/beast
]
[section More Examples]
[section:more_examples HTTP Examples]
These examples in this section are working functions that may be found
in the examples directory. They demonstrate the usage of the library for
@@ -7,7 +7,7 @@
Official repository: https://github.com/boostorg/beast
]
[section Establishing Connections]
[section:establishing_connections Connecting]
Connections are established by invoking functions directly on the next layer
object. For example, to make an outgoing connection using a standard TCP/IP
-85
View File
@@ -1,85 +0,0 @@
[/
Copyright (c) 2016-2019 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
]
[section Creating Streams]
The interface to the WebSocket implementation is a single template class
[link beast.ref.boost__beast__websocket__stream `stream`]:
[ws_snippet_26]
An instance of the stream wraps an existing network transport object
or other type of octet oriented stream. The wrapped object is called
the "next layer" and must meet the requirements of __SyncStream__ if
synchronous operations are performed, __AsyncStream__ if asynchronous
operations are performed, or both. Any arguments supplied to the
constructor of the stream wrapper are forwarded to next layer's constructor.
The value of `deflateSupported` determines if the stream will support
(but not require) the permessage-deflate extension
([@https://tools.ietf.org/html/rfc7692 rfc7692])
negotiation during handshaking. This extension allows messages to be
optionally automatically compressed using the deflate algorithm prior
to transmission. When this boolean value is `false`, the extension is
disabled. Applications which do not intend to use the permessage-deflate
extension may set the value to `false` to enjoy a reduction in the size
of the compiled output, as the necessary compression code (included with
Beast) will not be compiled in.
Here we declare a websocket stream over a TCP/IP socket with ownership
of the socket. The `io_context` argument is forwarded to the wrapped
socket's constructor:
[ws_snippet_2]
[heading Using SSL]
To use WebSockets over SSL, use an instance of the __ssl_stream__
class template as the template type for the stream. The required
__io_context__ and __ssl_context__ arguments are forwarded to the
wrapped stream's constructor:
[wss_snippet_1]
[wss_snippet_2]
[important
Code which declares websocket stream objects using Asio SSL types
must include the file [include_file boost/beast/websocket/ssl.hpp].
]
[heading Non-owning References]
If a socket type supports move construction, a websocket stream may be
constructed around the already existing socket by invoking the move
constructor signature:
[ws_snippet_3]
Or, the wrapper can be constructed with a non-owning reference. In
this case, the caller is responsible for managing the lifetime of the
underlying socket being wrapped:
[ws_snippet_4]
Once the WebSocket stream wrapper is created, the wrapped object may be
accessed by calling
[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`]:
[ws_snippet_5]
[warning
Initiating operations on the next layer while websocket
operations are being performed may result in undefined behavior.
]
[heading Non-Blocking Mode]
Please note that websocket streams do not support non-blocking modes.
[endsect]
-42
View File
@@ -1,42 +0,0 @@
[/
Copyright (c) 2016-2019 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
]
[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
opted-in to communications from that code. The protocol consists of an opening
handshake followed by basic message framing, layered over TCP. The goal of
this technology is to provide a mechanism for browser-based applications
needing two-way communication with servers without relying on opening multiple
HTTP connections.
Beast provides developers with a robust WebSocket implementation built on
Boost.Asio with a consistent asynchronous model using a modern C++ approach.
[note
This documentation assumes familiarity with __Asio__ and
the protocol specification described in __rfc6455__.
Sample code and identifiers appearing in this section is written
as if these declarations are in effect:
[ws_snippet_1]
]
[include 01_streams.qbk]
[include 02_connect.qbk]
[include 03_client.qbk]
[include 04_server.qbk]
[include 05_decorator.qbk]
[include 06_messages.qbk]
[include 07_control.qbk]
[include 08_teardown.qbk]
[include 09_notes.qbk]
[endsect]
+155
View File
@@ -0,0 +1,155 @@
[/
Copyright (c) 2016-2019 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
]
[section:using_websocket WebSocket __new__]
[/-----------------------------------------------------------------------------]
The WebSocket Protocol enables two-way communication between a client running
untrusted code in a controlled environment to a remote host that has opted-in
to communications from that code. The protocol consists of an opening handshake
followed by basic message framing, layered over TCP. The goal of this
technology is to provide a mechanism for browser-based applications needing
two-way communication with servers without relying on opening multiple HTTP
connections.
Beast provides developers with a robust WebSocket implementation
built on Boost.Asio with a consistent asynchronous model using a modern C++
approach.
[note
This documentation assumes familiarity with __Asio__ and
the protocol specification described in __rfc6455__.
Sample code and identifiers appearing in this section is written
as if these declarations are in effect:
[code_websocket_1a]
'''<?linebreak?>'''
[code_websocket_1b]
]
[/-----------------------------------------------------------------------------]
[heading Construction]
A WebSocket connection requires a stateful object, represented in Beast by a
single class template
[link beast.ref.boost__beast__websocket__stream `websocket::stream`].
The interface uses the layered stream model. A websocket stream object contains
another stream object, called the "next layer", which it uses to perform I/O.
Descriptions of each template parameter follow:
[code_websocket_1h]
[table WebSocket Stream Template Parameters
[[Name][Description]]
[
[`NextLayer`]
[
The type of the next layer. An object of this type will be constructed
and maintained for the lifetime of the stream. All reads and writes
will go through the next layer. This type must meet the requirements
of either __SyncStream__, __AsyncStream__, or both, depending on the
style of I/O that is to be performed.
]
][
[`deflateSupported`]
[
When this value is `true`, the stream will support (but not require)
the [@https://tools.ietf.org/html/rfc7692 permessage-deflate extension].
Whether or not the stream actually requests or accepts the extension
during a handshake depends on a separate configurable option.
When the value is `false` the extension is disabled. Streams will
never request the extension in the client role or accept a request
for the extension in the server role. An additional benefit of
disabling the extension is that compilation will be faster, and
the resulting program executable will contain less code.
]
]]
When a stream is constructed, any arguments provided to the constructor are
forwarded to the next layer object's constructor. This declares a stream
over a plain TCP/IP socket using an I/O context:
[code_websocket_1f]
[tip
Websocket streams use their own protocol-specific timeout feature. When
using a websocket stream with the
[link beast.ref.boost__beast__tcp_stream `tcp_stream`] or
[link beast.ref.boost__beast__basic_stream `basic_stream`]
class template, timeouts should be disabled on the TCP or basic stream
after the connection is established, otherwise the behavior of the
stream is undefined.
]
As with most I/O objects, a websocket stream is [*not thread-safe]. Undefined
behavior results if two different threads access the object concurrently.
For multi-threaded programs, the `tcp_stream` can be constructed from an
executor, in this case a strand. The stream declared below will use a
strand to invoke all completion handlers:
[code_websocket_2f]
[heading Using SSL]
To use WebSockets over SSL, use an instance of the __ssl_stream__
class template as the template type for the stream. The required
__io_context__ and __ssl_context__ arguments are forwarded to the
wrapped stream's constructor:
[code_websocket_3f]
[important
Code which declares websocket stream objects using Asio SSL types
must include the file [include_file boost/beast/websocket/ssl.hpp].
]
[heading Non-owning References]
If a socket type supports move construction, a websocket stream may be
constructed around the already existing socket by invoking the move
constructor signature:
[ws_snippet_3]
Or, the wrapper can be constructed with a non-owning reference. In
this case, the caller is responsible for managing the lifetime of the
underlying socket being wrapped:
[ws_snippet_4]
Once the WebSocket stream wrapper is created, the wrapped object may be
accessed by calling
[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`]:
[ws_snippet_5]
[warning
Initiating operations on the next layer while websocket
operations are being performed may result in undefined behavior.
]
[heading Non-Blocking Mode]
Please note that websocket streams do not support non-blocking modes.
[include 01_connecting.qbk]
[include 03_client.qbk]
[include 04_server.qbk]
[include 05_decorator.qbk]
[include 06_messages.qbk]
[include 07_control.qbk]
[include 08_teardown.qbk]
[include 09_notes.qbk]
[endsect]
+8 -6
View File
@@ -64,7 +64,7 @@
[def __AsyncWriteStream__ [@boost:/doc/html/boost_asio/reference/AsyncWriteStream.html ['AsyncWriteStream]]]
[def __CompletionCondition__ [@boost:/doc/html/boost_asio/reference/CompletionCondition.html ['CompletionCondition]]]
[def __CompletionHandler__ [@boost:/doc/html/boost_asio/reference/CompletionHandler.html ['CompletionHandler]]]
[def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
[def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
[def __ConnectCondition__ [@boost:/doc/html/boost_asio/reference/ConnectCondition.html ['ConnectCondition]]]
[def __ConnectHandler__ [@boost:/doc/html/boost_asio/reference/ConnectHandler.html ['ConnectHandler]]]
[def __ConstBufferSequence__ [@boost:/doc/html/boost_asio/reference/ConstBufferSequence.html ['ConstBufferSequence]]]
@@ -133,6 +133,7 @@
[import ../../example/websocket/client/sync/websocket_client_sync.cpp]
[import ../../include/boost/beast/http/basic_file_body.hpp]
[import ../../include/boost/beast/websocket/stream_fwd.hpp]
[import ../../test/doc/exemplars.cpp]
[import ../../test/doc/core_snippets.cpp]
@@ -143,6 +144,7 @@
[import ../../test/doc/core_3_timeouts.cpp]
[import ../../test/doc/core_4_layers.cpp]
[import ../../test/doc/http_10_custom_parser.cpp]
[import ../../test/doc/websocket.cpp]
[import ../../test/doc/websocket_3_handshake.cpp]
[import ../../include/boost/beast/core/detect_ssl.hpp]
@@ -171,11 +173,11 @@ __new__ indicates an item that is new in this version.
[include 01_intro/_intro.qbk]
[include 02_examples/_examples.qbk]
[include 03_core/_core.qbk]
[include 04_http/0_http.qbk]
[include 05_http_examples/0_http_examples.qbk]
[include 06_websocket/0_websocket.qbk]
[include 07_concepts/0_concepts.qbk]
[include 08_design/0_design.qbk]
[include 04_http/_http.qbk]
[include 05_http_examples/_http_examples.qbk]
[include 06_websocket/_websocket.qbk]
[include 07_concepts/_concepts.qbk]
[include 08_design/_design.qbk]
[section:moved1 Release Notes (Moved)]
The Release Notes have been moved to the top of the table of contents.
+1 -1
View File
@@ -58,6 +58,7 @@
<member><link linkend="beast.ref.boost__beast__condition">condition</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
<member><link linkend="beast.ref.boost__beast__error">error</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
<member><link linkend="beast.ref.boost__beast__file_mode">file_mode</link></member>
<member><link linkend="beast.ref.boost__beast__role_type">role_type</link>&nbsp;<emphasis role="green">&#9733;</emphasis></member>
</simplelist>
</entry>
<entry valign="top">
@@ -312,7 +313,6 @@
<member><link linkend="beast.ref.boost__beast__websocket__condition">condition</link></member>
<member><link linkend="beast.ref.boost__beast__websocket__error">error</link></member>
<member><link linkend="beast.ref.boost__beast__websocket__frame_type">frame_type</link></member>
<member><link linkend="beast.ref.boost__beast__websocket__role_type">role_type</link></member>
</simplelist>
</entry>
</row></tbody>
+2
View File
@@ -261,6 +261,8 @@
`file_mode::append_existing`
as needed.
* `role_type` is moved from `websocket` to `beast`
* `buffers_range_ref`
is preferred to `std::reference_wrapper`.
['Actions Required]:
+10 -97
View File
@@ -8,7 +8,7 @@ PROJECT_BRIEF = C++ Networking Library
PROJECT_LOGO =
OUTPUT_DIRECTORY =
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
#####ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
@@ -39,7 +39,7 @@ CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = YES
GROUP_NESTED_COMPOUNDS = NO
#####GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
@@ -63,7 +63,7 @@ HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
HIDE_COMPOUND_REFERENCE= NO
#####HIDE_COMPOUND_REFERENCE= NO
SHOW_INCLUDE_FILES = NO
SHOW_GROUPED_MEMB_INC = NO
FORCE_LOCAL_INCLUDES = NO
@@ -95,7 +95,7 @@ WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
#####WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
@@ -112,6 +112,7 @@ INPUT = \
$(LIB_DIR)/include/boost/beast/websocket \
$(LIB_DIR)/include/boost/beast/zlib
INPUT_ENCODING = UTF-8
FILE_PATTERNS =
RECURSIVE = NO
@@ -210,47 +211,14 @@ SEARCHDATA_FILE = searchdata.xml
EXTERNAL_SEARCH_ID =
EXTRA_SEARCH_MAPPINGS =
#---------------------------------------------------------------------------
# Configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4
EXTRA_PACKAGES =
LATEX_HEADER =
LATEX_FOOTER =
LATEX_EXTRA_STYLESHEET =
LATEX_EXTRA_FILES =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
#---------------------------------------------------------------------------
# Configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
RTF_SOURCE_CODE = NO
#---------------------------------------------------------------------------
# Configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_SUBDIR =
MAN_LINKS = NO
GENERATE_DOCBOOK = NO
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
CLASS_DIAGRAMS = NO
HAVE_DOT = NO
#---------------------------------------------------------------------------
# Configuration options related to the XML output
@@ -259,22 +227,6 @@ GENERATE_XML = YES
XML_OUTPUT = $(XML_OUTPUT)
XML_PROGRAMLISTING = YES
#---------------------------------------------------------------------------
# Configuration options related to the DOCBOOK output
#---------------------------------------------------------------------------
GENERATE_DOCBOOK = NO
DOCBOOK_OUTPUT = docbook
DOCBOOK_PROGRAMLISTING = NO
#---------------------------------------------------------------------------
# Configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
@@ -305,42 +257,3 @@ ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = NO
MSCGEN_PATH =
DIA_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica
DOT_FONTSIZE = 10
DOT_FONTPATH =
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
CALLER_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
INTERACTIVE_SVG = NO
DOT_PATH =
DOTFILE_DIRS =
MSCFILE_DIRS =
DIAFILE_DIRS =
PLANTUML_JAR_PATH =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES