forked from boostorg/beast
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:
1 parent
81f33a0f89
commit
0647c902ac
54 files changed
+395
-345
No files matched your search
@@ -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
|
||||
+1
-1
@@ -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
|
||||
@@ -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]
|
||||
@@ -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]
|
||||
@@ -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]
|
||||
File renamed without changes.
File renamed without changes.
+8
-6
@@ -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.
|
||||
|
||||
@@ -58,6 +58,7 @@
|
||||
<member><link linkend="beast.ref.boost__beast__condition">condition</link> <emphasis role="green">★</emphasis></member>
|
||||
<member><link linkend="beast.ref.boost__beast__error">error</link> <emphasis role="green">★</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> <emphasis role="green">★</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>
|
||||
|
||||
@@ -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]:
|
||||
|
||||
Reference in new issue
Block a user