//
-// Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
+// 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)
#include <boost/beast/core/detail/config.hpp>
#include <boost/beast/websocket/error.hpp>
#include <boost/beast/websocket/option.hpp>
-#include <boost/beast/websocket/role.hpp>
#include <boost/beast/websocket/rfc6455.hpp>
+#include <boost/beast/websocket/stream_base.hpp>
#include <boost/beast/websocket/stream_fwd.hpp>
-#include <boost/beast/websocket/detail/frame.hpp>
#include <boost/beast/websocket/detail/hybi13.hpp>
-#include <boost/beast/websocket/detail/mask.hpp>
-#include <boost/beast/websocket/detail/pausation.hpp>
+#include <boost/beast/websocket/detail/impl_base.hpp>
#include <boost/beast/websocket/detail/pmd_extension.hpp>
-#include <boost/beast/websocket/detail/stream_base.hpp>
-#include <boost/beast/websocket/detail/utf8_checker.hpp>
-#include <boost/beast/core/static_buffer.hpp>
+#include <boost/beast/websocket/detail/prng.hpp>
+#include <boost/beast/core/role.hpp>
+#include <boost/beast/core/stream_traits.hpp>
#include <boost/beast/core/string.hpp>
-#include <boost/beast/core/detail/type_traits.hpp>
-#include <boost/beast/http/empty_body.hpp>
-#include <boost/beast/http/message.hpp>
-#include <boost/beast/http/string_body.hpp>
#include <boost/beast/http/detail/type_traits.hpp>
#include <boost/asio/async_result.hpp>
#include <boost/asio/error.hpp>
+#include <boost/shared_ptr.hpp>
#include <algorithm>
#include <cstdint>
#include <functional>
#include <limits>
+#include <memory>
#include <type_traits>
+#include <random>
namespace boost {
namespace beast {
namespace websocket {
-/// The type of object holding HTTP Upgrade requests
-using request_type = http::request<http::empty_body>;
-
-/// The type of object holding HTTP Upgrade responses
-using response_type = http::response<http::string_body>;
-
/** The type of received control frame.
Values of this type are passed to the control frame
The @ref stream class template provides asynchronous and blocking
message-oriented functionality necessary for clients and servers
to utilize the WebSocket protocol.
-
+
For asynchronous operations, the application must ensure
that they are are all performed within the same implicit
or explicit strand.
operations are performed within the same implicit or explicit strand.
@par Example
-
- To use the @ref stream template with an `ip::tcp::socket`,
- you would write:
-
+ To declare the @ref stream object with a @ref tcp_stream in a
+ multi-threaded asynchronous program using a strand, you may write:
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
+ websocket::stream<tcp_stream> ws{net::io_context::strand(ioc)};
@endcode
- Alternatively, you can write:
+ Alternatively, for a single-threaded or synchronous application
+ you may write:
@code
- ip::tcp::socket sock{io_context};
- websocket::stream<ip::tcp::socket&> ws{sock};
+ websocket::stream<tcp_stream> ws(ioc);
@endcode
@tparam NextLayer The type representing the next layer, to which
data will be read and written during operations. For synchronous
- operations, the type must support the @b SyncStream concept.
+ operations, the type must support the <em>SyncStream</em> concept.
For asynchronous operations, the type must support the
- @b AsyncStream concept.
+ <em>AsyncStream</em> concept.
@tparam deflateSupported A `bool` indicating whether or not the
stream will be capable of negotiating the permessage-deflate websocket
are pending asynchronous operations associated with it.
@par Concepts
- @b AsyncStream,
- @b DynamicBuffer,
- @b SyncStream
+ @li <em>AsyncStream</em>
+ @li <em>DynamicBuffer</em>
+ @li <em>SyncStream</em>
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">Websocket Close (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">WebSocket Ping (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">WebSocket Pong (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
template<
class NextLayer,
bool deflateSupported>
class stream
-#ifndef BOOST_BEAST_DOXYGEN
- : private detail::stream_base<deflateSupported>
+#if ! BOOST_BEAST_DOXYGEN
+ : private stream_base
#endif
{
+ struct impl_type;
+
+ boost::shared_ptr<impl_type> impl_;
+
+ using time_point = typename
+ std::chrono::steady_clock::time_point;
+
+ using control_cb_type =
+ std::function<void(frame_type, string_view)>;
+
friend class close_test;
friend class frame_test;
friend class ping_test;
- friend class read1_test;
friend class read2_test;
+ friend class read3_test;
friend class stream_test;
friend class write_test;
-
+
/* The read buffer has to be at least as large
as the largest possible control frame including
the frame header.
static std::size_t constexpr max_control_frame_size = 2 + 8 + 4 + 125;
static std::size_t constexpr tcp_frame_size = 1536;
- using control_cb_type =
- std::function<void(frame_type, string_view)>;
-
- enum class status
+ static time_point never() noexcept
{
- open,
- closing,
- closed,
- failed
- };
-
- NextLayer stream_; // the wrapped stream
- close_reason cr_; // set from received close frame
- control_cb_type ctrl_cb_; // control callback
-
- std::size_t rd_msg_max_ // max message size
- = 16 * 1024 * 1024;
- std::uint64_t rd_size_ // total size of current message so far
- = 0;
- std::uint64_t rd_remain_ // message frame bytes left in current frame
- = 0;
- detail::frame_header rd_fh_; // current frame header
- detail::prepared_key rd_key_; // current stateful mask key
- detail::frame_buffer rd_fb_; // to write control frames (during reads)
- detail::utf8_checker rd_utf8_; // to validate utf8
- static_buffer<
- +tcp_frame_size> rd_buf_; // buffer for reads
- detail::opcode rd_op_ // current message binary or text
- = detail::opcode::text;
- bool rd_cont_ // `true` if the next frame is a continuation
- = false;
- bool rd_done_ // set when a message is done
- = true;
- bool rd_close_ // did we read a close frame?
- = false;
- detail::soft_mutex rd_block_; // op currently reading
-
- role_type role_ // server or client
- = role_type::client;
- status status_
- = status::closed;
-
- detail::soft_mutex wr_block_; // op currently writing
- bool wr_close_ // did we write a close frame?
- = false;
- bool wr_cont_ // next write is a continuation
- = false;
- bool wr_frag_ // autofrag the current message
- = false;
- bool wr_frag_opt_ // autofrag option setting
- = true;
- bool wr_compress_ // compress current message
- = false;
- detail::opcode wr_opcode_ // message type
- = detail::opcode::text;
- std::unique_ptr<
- std::uint8_t[]> wr_buf_; // write buffer
- std::size_t wr_buf_size_ // write buffer size (current message)
- = 0;
- std::size_t wr_buf_opt_ // write buffer size option setting
- = 4096;
- detail::fh_buffer wr_fb_; // header buffer used for writes
- detail::maskgen wr_gen_; // source of mask keys
-
- detail::pausation paused_rd_; // paused read op
- detail::pausation paused_wr_; // paused write op
- detail::pausation paused_ping_; // paused ping op
- detail::pausation paused_close_; // paused close op
- detail::pausation paused_r_rd_; // paused read op (async read)
- detail::pausation paused_r_close_;// paused close op (async read)
+ return (time_point::max)();
+ }
public:
/// Indicates if the permessage-deflate extension is supported
using next_layer_type =
typename std::remove_reference<NextLayer>::type;
- /// The type of the lowest layer.
- using lowest_layer_type = get_lowest_layer<next_layer_type>;
-
/// The type of the executor associated with the object.
- using executor_type = typename next_layer_type::executor_type;
+ using executor_type =
+ beast::executor_type<next_layer_type>;
/** Destructor
@note A stream object must not be destroyed while there
are pending asynchronous operations associated with it.
*/
- ~stream() = default;
+ ~stream();
/** Constructor
If `NextLayer` is move constructible, this function
will move-construct a new stream from the existing stream.
- @note The behavior of move assignment on or from streams
- with active or pending operations is undefined.
+ After the move, the only valid operation on the moved-from
+ object is destruction.
*/
stream(stream&&) = default;
- /** Assignment
-
- If `NextLayer` is move assignable, this function
- will move-assign a new stream from the existing stream.
-
- @note The behavior of move assignment on or from streams
- with active or pending operations is undefined.
- */
- stream& operator=(stream&&) = default;
+ /// Move assignment (deleted)
+ stream& operator=(stream&&) = delete;
/** Constructor
//--------------------------------------------------------------------------
/** Get the executor associated with the object.
-
+
This function may be used to obtain the executor object that the
stream uses to dispatch handlers for asynchronous operations.
@return A copy of the executor that stream will use to dispatch handlers.
*/
executor_type
- get_executor() noexcept
- {
- return stream_.get_executor();
- }
+ get_executor() noexcept;
/** Get a reference to the next layer
stream layers.
*/
next_layer_type&
- next_layer()
- {
- return stream_;
- }
+ next_layer() noexcept;
/** Get a reference to the next layer
stream layers.
*/
next_layer_type const&
- next_layer() const
- {
- return stream_;
- }
-
- /** Get a reference to the lowest layer
-
- This function returns a reference to the lowest layer
- in a stack of stream layers.
-
- @return A reference to the lowest layer in the stack of
- stream layers.
- */
- lowest_layer_type&
- lowest_layer()
- {
- return stream_.lowest_layer();
- }
-
- /** Get a reference to the lowest layer
-
- This function returns a reference to the lowest layer
- in a stack of stream layers.
-
- @return A reference to the lowest layer in the stack of
- stream layers. Ownership is not transferred to the caller.
- */
- lowest_layer_type const&
- lowest_layer() const
- {
- return stream_.lowest_layer();
- }
+ next_layer() const noexcept;
//--------------------------------------------------------------------------
//
no error has occurred.
*/
bool
- is_open() const
- {
- return status_ == status::open;
- }
+ is_open() const noexcept;
/** Returns `true` if the latest message data indicates binary.
undefined.
*/
bool
- got_binary() const
- {
- return rd_op_ == detail::opcode::binary;
- }
+ got_binary() const noexcept;
/** Returns `true` if the latest message data indicates text.
/// Returns `true` if the last completed read finished the current message.
bool
- is_message_done() const
- {
- return rd_done_;
- }
+ is_message_done() const noexcept;
- /** Returns the close reason received from the peer.
+ /** Returns the close reason received from the remote peer.
This is only valid after a read completes with error::closed.
*/
close_reason const&
- reason() const
- {
- return cr_;
- }
+ reason() const noexcept;
/** Returns a suggested maximum buffer size for the next call to read.
*/
std::size_t
read_size_hint(
- std::size_t initial_size = +tcp_frame_size) const
- {
- return read_size_hint(initial_size,
- is_deflate_supported{});
- }
+ std::size_t initial_size = +tcp_frame_size) const;
/** Returns a suggested maximum buffer size for the next call to read.
//
//--------------------------------------------------------------------------
+#if BOOST_BEAST_DOXYGEN
+ template<class Option>
+ void
+ get_option(Option& opt);
+
+ template<class Option>
+ void
+ set_option(Option opt);
+#else
+
+ void set_option(decorator opt);
+
+ void get_option(timeout& opt);
+ void set_option(timeout const& opt);
+#endif
+
/** Set the permessage-deflate extension options
@throws invalid_argument if `deflateSupported == false`, and either
`client_enable` or `server_enable` is `true`.
*/
void
- set_option(permessage_deflate const& o)
- {
- set_option(o, is_deflate_supported{});
- }
+ set_option(permessage_deflate const& o);
/// Get the permessage-deflate extension options
void
- get_option(permessage_deflate& o)
- {
- get_option(o, is_deflate_supported{});
- }
+ get_option(permessage_deflate& o);
/** Set the automatic fragmentation option.
@endcode
*/
void
- auto_fragment(bool value)
- {
- wr_frag_opt_ = value;
- }
+ auto_fragment(bool value);
/// Returns `true` if the automatic fragmentation option is set.
bool
- auto_fragment() const
- {
- return wr_frag_opt_;
- }
+ auto_fragment() const;
- /** Set the binary message option.
+ /** Set the binary message write option.
This controls whether or not outgoing message opcodes
are set to binary or text. The setting is only applied
@endcode
*/
void
- binary(bool value)
- {
- wr_opcode_ = value ?
- detail::opcode::binary :
- detail::opcode::text;
- }
+ binary(bool value);
- /// Returns `true` if the binary message option is set.
+ /// Returns `true` if the binary message write option is set.
bool
- binary() const
- {
- return wr_opcode_ == detail::opcode::binary;
- }
+ binary() const;
/** Set a callback to be invoked on each incoming control frame.
);
@endcode
The implementation type-erases the callback which may require
- a dynamic allocation. To prevent the possiblity of a dynamic
+ a dynamic allocation. To prevent the possibility of a dynamic
allocation, use `std::ref` to wrap the callback.
If the read operation which receives the control frame is
an asynchronous operation, the callback will be invoked using
in undefined behavior.
*/
void
- control_callback(std::function<void(frame_type, string_view)> cb)
- {
- ctrl_cb_ = std::move(cb);
- }
+ control_callback(std::function<void(frame_type, string_view)> cb);
/** Reset the control frame callback.
This function removes any previously set control frame callback.
*/
void
- control_callback()
- {
- ctrl_cb_ = {};
- }
+ control_callback();
/** Set the maximum incoming message size option.
@param amount The limit on the size of incoming messages.
*/
void
- read_message_max(std::size_t amount)
- {
- rd_msg_max_ = amount;
- }
+ read_message_max(std::size_t amount);
/// Returns the maximum incoming message size setting.
std::size_t
- read_message_max() const
- {
- return rd_msg_max_;
- }
+ read_message_max() const;
+
+ /** Set whether the PRNG is cryptographically secure
+
+ This controls whether or not the source of pseudo-random
+ numbers used to produce the masks required by the WebSocket
+ protocol are of cryptographic quality. When the setting is
+ `true`, a strong algorithm is used which cannot be guessed
+ by observing outputs. When the setting is `false`, a much
+ faster algorithm is used.
+ Masking is only performed by streams operating in the client
+ mode. For streams operating in the server mode, this setting
+ has no effect.
+ By default, newly constructed streams use a secure PRNG.
+
+ If the WebSocket stream is used with an encrypted SSL or TLS
+ next layer, if it is known to the application that intermediate
+ proxies are not vulnerable to cache poisoning, or if the
+ application is designed such that an attacker cannot send
+ arbitrary inputs to the stream interface, then the faster
+ algorithm may be used.
+
+ For more information please consult the WebSocket protocol RFC.
+
+ @param value `true` if the PRNG algorithm should be
+ cryptographically secure.
+ */
+ void
+ secure_prng(bool value);
/** Set the write buffer size option.
@par Example
Setting the write buffer size.
@code
- ws.write_buffer_size(8192);
+ ws.write_buffer_bytes(8192);
@endcode
@param amount The size of the write buffer in bytes.
*/
void
- write_buffer_size(std::size_t amount)
- {
- if(amount < 8)
- BOOST_THROW_EXCEPTION(std::invalid_argument{
- "write buffer size underflow"});
- wr_buf_opt_ = amount;
- };
+ write_buffer_bytes(std::size_t amount);
/// Returns the size of the write buffer.
std::size_t
- write_buffer_size() const
- {
- return wr_buf_opt_;
- }
+ write_buffer_bytes() const;
- /** Set the text message option.
+ /** Set the text message write option.
This controls whether or not outgoing message opcodes
are set to binary or text. The setting is only applied
@endcode
*/
void
- text(bool value)
- {
- wr_opcode_ = value ?
- detail::opcode::text :
- detail::opcode::binary;
- }
+ text(bool value);
- /// Returns `true` if the text message option is set.
+ /// Returns `true` if the text message write option is set.
bool
- text() const
- {
- return wr_opcode_ == detail::opcode::text;
- }
+ text() const;
+
+ /*
+ timer settings
+
+ * Timer is disabled
+ * Close on timeout
+ - no complete frame received, OR
+ - no complete frame sent
+ * Ping on timeout
+ - ping on no complete frame received
+ * if can't ping?
+ */
//--------------------------------------------------------------------------
//
//
//--------------------------------------------------------------------------
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ /** Perform the WebSocket handshake in the client role.
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
+
+ The call blocks until one of the following conditions is true:
@li The request is sent and the response is received.
- @li An error occurs on the stream
+ @li An error occurs.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
- @param host The name of the remote host,
- required by the HTTP protocol.
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
@throws system_error Thrown on failure.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- try
- {
- ws.handshake("localhost", "/");
- }
- catch(...)
- {
- // An error occurred.
- }
+ ws.handshake("localhost", "/");
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
void
handshake(
string_view host,
string_view target);
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ /** Perform the WebSocket handshake in the client role.
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
+
+ The call blocks until one of the following conditions is true:
@li The request is sent and the response is received.
- @li An error occurs on the stream
+ @li An error occurs.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
@param res The HTTP Upgrade response returned by the remote
- endpoint.
+ endpoint. The caller may use the response to access any
+ additional information sent by the server.
- @param host The name of the remote host,
- required by the HTTP protocol.
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
@throws system_error Thrown on failure.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- try
- {
- response_type res;
- ws.handshake(res, "localhost", "/");
- }
- catch(...)
- {
- // An error occurred.
- }
+ response_type res;
+ ws.handshake(res, "localhost", "/");
+ std::cout << res;
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
void
handshake(
string_view host,
string_view target);
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ /** Perform the WebSocket handshake in the client role.
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- @li The request is sent and the response is received.
+ The call blocks until one of the following conditions is true:
- @li An error occurs on the stream
+ @li The request is sent and the response is received.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ @li An error occurs.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- @param host The name of the remote host,
- required by the HTTP protocol.
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
- @throws system_error Thrown on failure.
+ @param ec Set to indicate what error occurred, if any.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- try
- {
- ws.handshake("localhost", "/",
- [](request_type& req)
- {
- req.set(field::user_agent, "Beast");
- });
- }
- catch(...)
- {
- // An error occurred.
- }
+ error_code ec;
+ ws.handshake("localhost", "/", ec);
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
- template<class RequestDecorator>
void
- handshake_ex(
+ handshake(
string_view host,
string_view target,
- RequestDecorator const& decorator);
+ error_code& ec);
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ /** Perform the WebSocket handshake in the client role.
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
+
+ The call blocks until one of the following conditions is true:
@li The request is sent and the response is received.
- @li An error occurs on the stream
+ @li An error occurs.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
@param res The HTTP Upgrade response returned by the remote
- endpoint.
-
- @param host The name of the remote host,
- required by the HTTP protocol.
+ endpoint. The caller may use the response to access any
+ additional information sent by the server.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
- @throws system_error Thrown on failure.
+ @param ec Set to indicate what error occurred, if any.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- try
- {
- response_type res;
- ws.handshake(res, "localhost", "/",
- [](request_type& req)
- {
- req.set(field::user_agent, "Beast");
- });
- }
- catch(...)
- {
- // An error occurred.
- }
+ error_code ec;
+ response_type res;
+ ws.handshake(res, "localhost", "/", ec);
+ if(! ec)
+ std::cout << res;
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
- template<class RequestDecorator>
void
- handshake_ex(
+ handshake(
response_type& res,
string_view host,
string_view target,
- RequestDecorator const& decorator);
-
- /** Send an HTTP WebSocket Upgrade request and receive the response.
-
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
-
- @li The request is sent and the response is received.
+ error_code& ec);
- @li An error occurs on the stream
+ /** Perform the WebSocket handshake asynchronously in the client role.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ This initiating function is used to asynchronously begin performing the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @param host The name of the remote host,
- required by the HTTP protocol.
+ @li The request is sent and the response is received.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ @li An error occurs.
- @param ec Set to indicate what error occurred, if any.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. No other operation may be performed
+ on the stream until this operation completes.
+
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
+
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
+ The implementation will not access the string data after the
+ initiating function returns.
+
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
+ The implementation will not access the string data after the
+ initiating function returns.
+
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
+ error_code const& ec // Result of operation
+ );
+ @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `net::post`.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- error_code ec;
- ws.handshake(host, target, ec);
- if(ec)
- {
- // An error occurred.
- }
+ ws.async_handshake("localhost", "/",
+ [](error_code ec)
+ {
+ if(ec)
+ std::cerr << "Error: " << ec.message() << "\n";
+ });
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
- void
- handshake(
+ template<
+ BOOST_BEAST_ASYNC_TPARAM1 HandshakeHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
+ async_handshake(
string_view host,
string_view target,
- error_code& ec);
+ HandshakeHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ /** Perform the WebSocket handshake asynchronously in the client role.
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ This initiating function is used to asynchronously begin performing the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
+
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
@li The request is sent and the response is received.
- @li An error occurs on the stream
+ @li An error occurs.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. No other operation may be performed
+ on the stream until this operation completes.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The handshake is successful if the received HTTP response
+ indicates the upgrade was accepted by the server, represented by a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols.
@param res The HTTP Upgrade response returned by the remote
- endpoint. If `ec` is set, the returned value is undefined.
-
- @param host The name of the remote host,
- required by the HTTP protocol.
-
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
-
- @param ec Set to indicate what error occurred, if any.
+ endpoint. The caller may use the response to access any
+ additional information sent by the server. This object will
+ be assigned before the completion handler is invoked.
+
+ @param host The name of the remote host. This is required by
+ the HTTP protocol to set the "Host" header field.
+ The implementation will not access the string data after the
+ initiating function returns.
+
+ @param target The request-target, in origin-form. The server may use the
+ target to distinguish different services on the same listening port.
+ The implementation will not access the string data after the
+ initiating function returns.
+
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
+ error_code const& ec // Result of operation
+ );
+ @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `net::post`.
@par Example
@code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- error_code ec;
response_type res;
- ws.handshake(res, host, target, ec);
- if(ec)
- {
- // An error occurred.
- }
+ ws.async_handshake(res, "localhost", "/",
+ [&res](error_code ec)
+ {
+ if(ec)
+ std::cerr << "Error: " << ec.message() << "\n";
+ else
+ std::cout << res;
+
+ });
@endcode
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
+ @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
*/
- void
- handshake(
+ template<
+ BOOST_BEAST_ASYNC_TPARAM1 HandshakeHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
+ async_handshake(
response_type& res,
string_view host,
string_view target,
- error_code& ec);
+ HandshakeHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
- /** Send an HTTP WebSocket Upgrade request and receive the response.
+ //--------------------------------------------------------------------------
+ //
+ // Handshaking (Server)
+ //
+ //--------------------------------------------------------------------------
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ /** Perform the WebSocket handshake in the server role.
- @li The request is sent and the response is received.
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- @li An error occurs on the stream
+ The call blocks until one of the following conditions is true:
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ @li The request is received and the response is sent.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ @li An error occurs.
- @param host The name of the remote host,
- required by the HTTP protocol.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
- @param ec Set to indicate what error occurred, if any.
+ @throws system_error Thrown on failure.
- @par Example
- @code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- error_code ec;
- ws.handshake("localhost", "/",
- [](request_type& req)
- {
- req.set(field::user_agent, "Beast");
- },
- ec);
- if(ec)
- {
- // An error occurred.
- }
- @endcode
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
- template<class RequestDecorator>
void
- handshake_ex(
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- error_code& ec);
-
- /** Send an HTTP WebSocket Upgrade request and receive the response.
-
- This function is used to synchronously send the WebSocket
- upgrade HTTP request. The call blocks until one of the
- following conditions is true:
+ accept();
- @li The request is sent and the response is received.
+ /** Read and respond to a WebSocket HTTP Upgrade request.
- @li An error occurs on the stream
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- This function is implemented in terms of one or more calls to the
- next layer's `read_some` and `write_some` functions.
+ The call blocks until one of the following conditions is true:
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ @li The request is received and the response is sent.
- @param res The HTTP Upgrade response returned by the remote
- endpoint.
+ @li An error occurs.
- @param host The name of the remote host,
- required by the HTTP protocol.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
@param ec Set to indicate what error occurred, if any.
- @par Example
- @code
- websocket::stream<ip::tcp::socket> ws{io_context};
- ...
- error_code ec;
- response_type res;
- ws.handshake(res, "localhost", "/",
- [](request_type& req)
- {
- req.set(field::user_agent, "Beast");
- },
- ec);
- if(ec)
- {
- // An error occurred.
- }
- @endcode
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
- template<class RequestDecorator>
void
- handshake_ex(
- response_type& res,
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- error_code& ec);
+ accept(error_code& ec);
- /** Start an asynchronous operation to send an upgrade request and receive the response.
+ /** Read and respond to a WebSocket HTTP Upgrade request.
- This function is used to asynchronously send the HTTP WebSocket
- upgrade request and receive the HTTP WebSocket Upgrade response.
- This function call always returns immediately. The asynchronous
- operation will continue until one of the following conditions is
- true:
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- @li The request is sent and the response is received.
+ The call blocks until one of the following conditions is true:
- @li An error occurs on the stream
+ @li The request is received and the response is sent.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions, and
- is known as a <em>composed operation</em>. The program must ensure
- that the stream performs no other operations until this operation
- completes.
+ @li An error occurs.
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- @param host The name of the remote host, required by
- the HTTP protocol. Copies may be made as needed.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol. Copies of this parameter may
- be made as needed.
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<class HandshakeHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- HandshakeHandler, void(error_code))
- async_handshake(
- string_view host,
- string_view target,
- HandshakeHandler&& handler);
+ @param buffers Caller provided data that has already been
+ received on the stream. The implementation will copy the
+ caller provided data before the function returns.
- /** Start an asynchronous operation to send an upgrade request and receive the response.
+ @throws system_error Thrown on failure.
- This function is used to asynchronously send the HTTP WebSocket
- upgrade request and receive the HTTP WebSocket Upgrade response.
- This function call always returns immediately. The asynchronous
- operation will continue until one of the following conditions is
- true:
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
+ */
+ template<class ConstBufferSequence>
+#if BOOST_BEAST_DOXYGEN
+ void
+#else
+ typename std::enable_if<! http::detail::is_header<
+ ConstBufferSequence>::value>::type
+#endif
+ accept(ConstBufferSequence const& buffers);
- @li The request is sent and the response is received.
+ /** Read and respond to a WebSocket HTTP Upgrade request.
- @li An error occurs on the stream
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions, and
- is known as a <em>composed operation</em>. The program must ensure
- that the stream performs no other operations until this operation
- completes.
+ The call blocks until one of the following conditions is true:
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
+ @li The request is received and the response is sent.
- @param res The HTTP Upgrade response returned by the remote
- endpoint. The caller must ensure this object is valid for at
- least until the completion handler is invoked.
-
- @param host The name of the remote host, required by
- the HTTP protocol. Copies may be made as needed.
-
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol. Copies of this parameter may
- be made as needed.
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<class HandshakeHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- HandshakeHandler, void(error_code))
- async_handshake(
- response_type& res,
- string_view host,
- string_view target,
- HandshakeHandler&& handler);
-
- /** Start an asynchronous operation to send an upgrade request and receive the response.
-
- This function is used to asynchronously send the HTTP WebSocket
- upgrade request and receive the HTTP WebSocket Upgrade response.
- This function call always returns immediately. The asynchronous
- operation will continue until one of the following conditions is
- true:
-
- @li The request is sent and the response is received.
-
- @li An error occurs on the stream
-
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions, and
- is known as a <em>composed operation</em>. The program must ensure
- that the stream performs no other operations until this operation
- completes.
-
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
-
- @param host The name of the remote host, required by
- the HTTP protocol. Copies may be made as needed.
-
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol. Copies of this parameter may
- be made as needed.
-
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<class RequestDecorator, class HandshakeHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- HandshakeHandler, void(error_code))
- async_handshake_ex(
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- HandshakeHandler&& handler);
-
- /** Start an asynchronous operation to send an upgrade request and receive the response.
-
- This function is used to asynchronously send the HTTP WebSocket
- upgrade request and receive the HTTP WebSocket Upgrade response.
- This function call always returns immediately. The asynchronous
- operation will continue until one of the following conditions is
- true:
-
- @li The request is sent and the response is received.
-
- @li An error occurs on the stream
-
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions, and
- is known as a <em>composed operation</em>. The program must ensure
- that the stream performs no other operations until this operation
- completes.
-
- The operation is successful if the received HTTP response indicates
- a successful HTTP Upgrade (represented by a Status-Code of 101,
- "switching protocols").
-
- @param res The HTTP Upgrade response returned by the remote
- endpoint. The caller must ensure this object is valid for at
- least until the completion handler is invoked.
-
- @param host The name of the remote host, required by
- the HTTP protocol. Copies may be made as needed.
-
- @param target The Request Target, which may not be empty,
- required by the HTTP protocol. Copies of this parameter may
- be made as needed.
-
- @param decorator A function object which will be called to modify
- the HTTP request object generated by the implementation. This
- could be used to set the User-Agent field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- request_type& req
- ); @endcode
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<class RequestDecorator, class HandshakeHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- HandshakeHandler, void(error_code))
- async_handshake_ex(
- response_type& res,
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- HandshakeHandler&& handler);
-
- //--------------------------------------------------------------------------
- //
- // Handshaking (Server)
- //
- //--------------------------------------------------------------------------
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @throws system_error Thrown on failure.
- */
- void
- accept();
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @throws system_error Thrown on failure.
- */
- template<class ResponseDecorator>
- void
- accept_ex(ResponseDecorator const& decorator);
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param ec Set to indicate what error occurred, if any.
- */
- void
- accept(error_code& ec);
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @param ec Set to indicate what error occurred, if any.
- */
- template<class ResponseDecorator>
- void
- accept_ex(
- ResponseDecorator const& decorator,
- error_code& ec);
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param buffers Caller provided data that has already been
- received on the stream. The implementation will copy the
- caller provided data before the function returns.
-
- @throws system_error Thrown on failure.
- */
- template<class ConstBufferSequence>
-#if BOOST_BEAST_DOXYGEN
- void
-#else
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
-#endif
- accept(ConstBufferSequence const& buffers);
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param buffers Caller provided data that has already been
- received on the stream. The implementation will copy the
- caller provided data before the function returns.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @throws system_error Thrown on failure.
- */
- template<class ConstBufferSequence,
- class ResponseDecorator>
-#if BOOST_BEAST_DOXYGEN
- void
-#else
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
-#endif
- accept_ex(
- ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator);
-
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
+ @li An error occurs.
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
@param buffers Caller provided data that has already been
received on the stream. The implementation will copy the
caller provided data before the function returns.
@param ec Set to indicate what error occurred, if any.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<class ConstBufferSequence>
#if BOOST_BEAST_DOXYGEN
ConstBufferSequence const& buffers,
error_code& ec);
- /** Read and respond to a WebSocket HTTP Upgrade request.
-
- This function is used to synchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The call blocks
- until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param buffers Caller provided data that has already been
- received on the stream. The implementation will copy the
- caller provided data before the function returns.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @param ec Set to indicate what error occurred, if any.
- */
- template<class ConstBufferSequence, class ResponseDecorator>
-#if BOOST_BEAST_DOXYGEN
- void
-#else
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
-#endif
- accept_ex(
- ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator,
- error_code& ec);
-
/** Respond to a WebSocket HTTP Upgrade request
- This function is used to synchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade.
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
+
The call blocks until one of the following conditions is true:
- @li The response finishes sending.
+ @li The response is sent.
- @li An error occurs on the stream.
+ @li An error occurs.
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
@param req An object containing the HTTP Upgrade request.
Ownership is not transferred, the implementation will not
access this object from other threads.
@throws system_error Thrown on failure.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<class Body, class Allocator>
void
/** Respond to a WebSocket HTTP Upgrade request
- This function is used to synchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade.
- The call blocks until one of the following conditions is true:
-
- @li The response finishes sending.
-
- @li An error occurs on the stream.
+ This function is used to perform the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
-
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not
- access this object from other threads.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @throws system_error Thrown on failure.
- */
- template<class Body, class Allocator,
- class ResponseDecorator>
- void
- accept_ex(http::request<Body,
- http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator);
-
- /** Respond to a WebSocket HTTP Upgrade request
-
- This function is used to synchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade.
The call blocks until one of the following conditions is true:
- @li The response finishes sending.
+ @li The response is sent.
- @li An error occurs on the stream.
+ @li An error occurs.
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
@param req An object containing the HTTP Upgrade request.
Ownership is not transferred, the implementation will not
access this object from other threads.
@param ec Set to indicate what error occurred, if any.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<class Body, class Allocator>
void
http::basic_fields<Allocator>> const& req,
error_code& ec);
- /** Respond to a WebSocket HTTP Upgrade request
-
- This function is used to synchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade.
- The call blocks until one of the following conditions is true:
-
- @li The response finishes sending.
-
- @li An error occurs on the stream.
+ /** Perform the WebSocket handshake asynchronously in the server role.
- This function is implemented in terms of one or more calls to
- the next layer's `read_some` and `write_some` functions.
+ This initiating function is used to asynchronously begin performing the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When this call returns, the stream is then ready to send and
- receive WebSocket protocol frames and messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure.
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not
- access this object from other threads.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
+ @li The request is received and the response is sent.
- @param ec Set to indicate what error occurred, if any.
- */
- template<class Body, class Allocator,
- class ResponseDecorator>
- void
- accept_ex(http::request<Body,
- http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator,
- error_code& ec);
+ @li An error occurs.
- /** Start reading and responding to a WebSocket HTTP Upgrade request.
-
- This function is used to asynchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The function call
- always returns immediately. The asynchronous operation will
- continue until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This operation is implemented in terms of one or more calls to
- the next layer's `async_read_some` and `async_write_some`
- functions, and is known as a <em>composed operation</em>. The
- program must ensure that the stream performs no other
- asynchronous operations until this operation completes.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<class AcceptHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))
- async_accept(AcceptHandler&& handler);
-
- /** Start reading and responding to a WebSocket HTTP Upgrade request.
-
- This function is used to asynchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The function call
- always returns immediately. The asynchronous operation will
- continue until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This operation is implemented in terms of one or more calls to
- the next layer's `async_read_some` and `async_write_some`
- functions, and is known as a <em>composed operation</em>. The
- program must ensure that the stream performs no other
- asynchronous operations until this operation completes.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
-
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. No other operation may be performed
+ on the stream until this operation completes.
+
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
+
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::async_read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
+
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
error_code const& ec // Result of operation
- ); @endcode
+ );
+ @endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<
- class ResponseDecorator,
- class AcceptHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))
- async_accept_ex(
- ResponseDecorator const& decorator,
- AcceptHandler&& handler);
+ BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept(
+ AcceptHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
- /** Start reading and responding to a WebSocket HTTP Upgrade request.
-
- This function is used to asynchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The function call
- always returns immediately. The asynchronous operation will
- continue until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This operation is implemented in terms of one or more calls to
- the next layer's `async_read_some` and `async_write_some`
- functions, and is known as a <em>composed operation</em>. The
- program must ensure that the stream performs no other
- asynchronous operations until this operation completes.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
+ /** Perform the WebSocket handshake asynchronously in the server role.
- @param buffers Caller provided data that has already been
- received on the stream. This may be used for implementations
- allowing multiple protocols on the same stream. The
- buffered data will first be applied to the handshake, and
- then to received WebSocket frames. The implementation will
- copy the caller provided data before the function returns.
+ This initiating function is used to asynchronously begin performing the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<
- class ConstBufferSequence,
- class AcceptHandler>
-#if BOOST_BEAST_DOXYGEN
- void_or_deduced
-#else
- typename std::enable_if<
- ! http::detail::is_header<ConstBufferSequence>::value,
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))>::type
-#endif
- async_accept(
- ConstBufferSequence const& buffers,
- AcceptHandler&& handler);
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- /** Start reading and responding to a WebSocket HTTP Upgrade request.
-
- This function is used to asynchronously read an HTTP WebSocket
- Upgrade request and send the HTTP response. The function call
- always returns immediately. The asynchronous operation will
- continue until one of the following conditions is true:
-
- @li The request is received and the response finishes sending.
-
- @li An error occurs on the stream.
-
- This operation is implemented in terms of one or more calls to
- the next layer's `async_read_some` and `async_write_some`
- functions, and is known as a <em>composed operation</em>. The
- program must ensure that the stream performs no other
- asynchronous operations until this operation completes.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
-
- The implementation uses fixed size internal storage to
- receive the request. If the request is too large, the error
- @ref error::buffer_overflow will be indicated. Applications
- that wish to receive larger requests should first read the
- request using their own buffer and a suitable overload of
- @ref http::read or @ref http::async_read, then call @ref accept
- or @ref async_accept with the request.
+ @li The request is received and the response is sent.
+
+ @li An error occurs.
+
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. No other operation may be performed
+ on the stream until this operation completes.
+
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
+
+ If the request size exceeds the capacity of the stream's
+ internal buffer, the error @ref error::buffer_overflow will be
+ indicated. To handle larger requests, an application should
+ read the HTTP request directly using @ref http::async_read and then
+ pass the request to the appropriate overload of @ref accept or
+ @ref async_accept
@param buffers Caller provided data that has already been
received on the stream. This may be used for implementations
then to received WebSocket frames. The implementation will
copy the caller provided data before the function returns.
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
error_code const& ec // Result of operation
- ); @endcode
+ );
+ @endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<
class ConstBufferSequence,
- class ResponseDecorator,
- class AcceptHandler>
-#if BOOST_BEAST_DOXYGEN
- void_or_deduced
-#else
- typename std::enable_if<
- ! http::detail::is_header<ConstBufferSequence>::value,
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))>::type
-#endif
- async_accept_ex(
+ BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept(
ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator,
- AcceptHandler&& handler);
-
- /** Start responding to a WebSocket HTTP Upgrade request.
-
- This function is used to asynchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade
- request. The function call always returns immediately. The
- asynchronous operation will continue until one of the following
- conditions is true:
-
- @li The response finishes sending.
-
- @li An error occurs on the stream.
-
- This operation is implemented in terms of one or more calls to
- the next layer's `async_write_some` functions, and is known as
- a <em>composed operation</em>. The program must ensure that the
- stream performs no other operations until this operation
- completes.
-
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
-
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not access
- this object from other threads.
+ AcceptHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{}
+#ifndef BOOST_BEAST_DOXYGEN
+ , typename std::enable_if<
+ ! http::detail::is_header<
+ ConstBufferSequence>::value>::type* = 0
+#endif
+ );
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
- error_code const& ec // Result of operation
- ); @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
- */
- template<
- class Body, class Allocator,
- class AcceptHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))
- async_accept(
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- AcceptHandler&& handler);
+ /** Perform the WebSocket handshake asynchronously in the server role.
- /** Start responding to a WebSocket HTTP Upgrade request.
+ This initiating function is used to asynchronously begin performing the
+ <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
+ required before messages can be sent and received. During the handshake,
+ the client sends the Websocket Upgrade HTTP request, and the server
+ replies with an HTTP response indicating the result of the handshake.
- This function is used to asynchronously send the HTTP response
- to an HTTP request possibly containing a WebSocket Upgrade
- request. The function call always returns immediately. The
- asynchronous operation will continue until one of the following
- conditions is true:
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @li The response finishes sending.
+ @li The request is received and the response is sent.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to
- the next layer's `async_write_some` functions, and is known as
- a <em>composed operation</em>. The program must ensure that the
- stream performs no other operations until this operation
- completes.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. No other operation may be performed
+ on the stream until this operation completes.
- If the stream receives a valid HTTP WebSocket Upgrade request,
- an HTTP response is sent back indicating a successful upgrade.
- When the completion handler is invoked, the stream is then
- ready to send and receive WebSocket protocol frames and
- messages.
- If the HTTP Upgrade request is invalid or cannot be satisfied,
- an HTTP response is sent indicating the reason and status code
- (typically 400, "Bad Request"). This counts as a failure, and
- the completion handler will be invoked with a suitable error
- code set.
+ If a valid upgrade request is received, an HTTP response with a
+ <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
+ of @ref beast::http::status::switching_protocols is sent to
+ the peer, otherwise a non-successful error is associated with
+ the operation.
@param req An object containing the HTTP Upgrade request.
Ownership is not transferred, the implementation will not access
this object from other threads.
- @param decorator A function object which will be called to modify
- the HTTP response object delivered by the implementation. This
- could be used to set the Server field, subprotocols, or other
- application or HTTP specific fields. The object will be called
- with this equivalent signature:
- @code void decorator(
- response_type& res
- ); @endcode
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
error_code const& ec // Result of operation
- ); @endcode
+ );
+ @endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<
class Body, class Allocator,
- class ResponseDecorator,
- class AcceptHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- AcceptHandler, void(error_code))
- async_accept_ex(
+ BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept(
http::request<Body,
http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator,
- AcceptHandler&& handler);
+ AcceptHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
//--------------------------------------------------------------------------
//
- // Control Frames
+ // Close Frames
//
//--------------------------------------------------------------------------
- /** Send a WebSocket close frame.
+ /** Send a websocket close control frame.
- This function is used to synchronously send a close frame on
- the stream. The call blocks until one of the following is true:
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
+ which begins the websocket closing handshake. The session ends when
+ both ends of the connection have sent and received a close frame.
- @li The close frame finishes sending.
+ The call blocks until one of the following conditions is true:
+
+ @li The close frame is written.
+
+ @li An error occurs.
- @li An error occurs on the stream.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
- This function is implemented in terms of one or more calls
- to the next layer's `write_some` functions.
+ After beginning the closing handshake, the program should not write
+ further message data, pings, or pongs. Instead, the program should
+ continue reading message data until an error occurs. A read returning
+ @ref error::closed indicates a successful connection closure.
+ @param cr The reason for the close.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
- Callers should not attempt to write WebSocket data after
- initiating the close. Instead, callers should continue
- reading until an error occurs. A read returning @ref error::closed
- indicates a successful connection closure.
-
- @param cr The reason for the close.
-
@throws system_error Thrown on failure.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
*/
void
close(close_reason const& cr);
- /** Send a WebSocket close frame.
+ /** Send a websocket close control frame.
- This function is used to synchronously send a close frame on
- the stream. The call blocks until one of the following is true:
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
+ which begins the websocket closing handshake. The session ends when
+ both ends of the connection have sent and received a close frame.
- @li The close frame finishes sending.
+ The call blocks until one of the following conditions is true:
+
+ @li The close frame is written.
- @li An error occurs on the stream.
+ @li An error occurs.
- This function is implemented in terms of one or more calls
- to the next layer's `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
+ After beginning the closing handshake, the program should not write
+ further message data, pings, or pongs. Instead, the program should
+ continue reading message data until an error occurs. A read returning
+ @ref error::closed indicates a successful connection closure.
+
+ @param cr The reason for the close.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
- Callers should not attempt to write WebSocket data after
- initiating the close. Instead, callers should continue
- reading until an error occurs. A read returning @ref error::closed
- indicates a successful connection closure.
-
- @param cr The reason for the close.
-
@param ec Set to indicate what error occurred, if any.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
*/
void
close(close_reason const& cr, error_code& ec);
- /** Start an asynchronous operation to send a WebSocket close frame.
+ /** Send a websocket close control frame asynchronously.
- This function is used to asynchronously send a close frame on
- the stream. This function call always returns immediately. The
- asynchronous operation will continue until one of the following
- conditions is true:
+ This function is used to asynchronously send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
+ which begins the websocket closing handshake. The session ends when
+ both ends of the connection have sent and received a close frame.
+
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
@li The close frame finishes sending.
- @li An error occurs on the stream.
+ @li An error occurs.
+
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_write_some`
+ function. No other operations except for message reading operations
+ should be initiated on the stream after a close operation is started.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_write_some` functions, and is known as a
- <em>composed operation</em>. The program must ensure that the
- stream performs no other write operations (such as @ref async_ping,
- @ref async_write, @ref async_write_some, or @ref async_close)
- until this operation completes.
+ After beginning the closing handshake, the program should not write
+ further message data, pings, or pongs. Instead, the program should
+ continue reading message data until an error occurs. A read returning
+ @ref error::closed indicates a successful connection closure.
+ @param cr The reason for the close.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
sent with the close code and optional reason string. Otherwise,
the close frame is sent with no payload.
- Callers should not attempt to write WebSocket data after
- initiating the close. Instead, callers should continue
- reading until an error occurs. A read returning @ref error::closed
- indicates a successful connection closure.
-
- @param cr The reason for the close.
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec // Result of operation
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
+
+ @see
+ @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
*/
- template<class CloseHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- CloseHandler, void(error_code))
- async_close(close_reason const& cr, CloseHandler&& handler);
+ template<
+ BOOST_BEAST_ASYNC_TPARAM1 CloseHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(CloseHandler)
+ async_close(
+ close_reason const& cr,
+ CloseHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
+
+ //--------------------------------------------------------------------------
+ //
+ // Ping/Pong Frames
+ //
+ //--------------------------------------------------------------------------
- /** Send a WebSocket ping frame.
+ /** Send a websocket ping control frame.
- This function is used to synchronously send a ping frame on
- the stream. The call blocks until one of the following is true:
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
+ which usually elicits an automatic pong control frame response from
+ the peer.
- @li The ping frame finishes sending.
+ The call blocks until one of the following conditions is true:
- @li An error occurs on the stream.
+ @li The ping frame is written.
- This function is implemented in terms of one or more calls to the
- next layer's `write_some` functions.
+ @li An error occurs.
+
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
@param payload The payload of the ping message, which may be empty.
void
ping(ping_data const& payload);
- /** Send a WebSocket ping frame.
+ /** Send a websocket ping control frame.
- This function is used to synchronously send a ping frame on
- the stream. The call blocks until one of the following is true:
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
+ which usually elicits an automatic pong control frame response from
+ the peer.
- @li The ping frame finishes sending.
+ The call blocks until one of the following conditions is true:
- @li An error occurs on the stream.
+ @li The ping frame is written.
- This function is implemented in terms of one or more calls to the
- next layer's `write_some` functions.
+ @li An error occurs.
+
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
@param payload The payload of the ping message, which may be empty.
void
ping(ping_data const& payload, error_code& ec);
- /** Start an asynchronous operation to send a WebSocket ping frame.
+ /** Send a websocket ping control frame asynchronously.
- This function is used to asynchronously send a ping frame to
- the stream. The function call always returns immediately. The
- asynchronous operation will continue until one of the following
- is true:
+ This function is used to asynchronously send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
+ which usually elicits an automatic pong control frame response from
+ the peer.
- @li The entire ping frame is sent.
+ @li The ping frame is written.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_write_some` functions, and is known as a
- <em>composed operation</em>. The program must ensure that the
- stream performs no other writes until this operation completes.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_write_some`
+ function. The program must ensure that no other calls to @ref ping,
+ @ref pong, @ref async_ping, or @ref async_pong are performed until
+ this operation completes.
If a close frame is sent or received before the ping frame is
- sent, the completion handler will be called with the error
- set to `boost::asio::error::operation_aborted`.
+ sent, the error received by this completion handler will be
+ `net::error::operation_aborted`.
@param payload The payload of the ping message, which may be empty.
+ The implementation will not access the contents of this object after
+ the initiating function returns.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec // Result of operation
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
- template<class WriteHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- WriteHandler, void(error_code))
- async_ping(ping_data const& payload, WriteHandler&& handler);
+ template<
+ BOOST_BEAST_ASYNC_TPARAM1 WriteHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(WriteHandler)
+ async_ping(
+ ping_data const& payload,
+ WriteHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
+
+ /** Send a websocket pong control frame.
- /** Send a WebSocket pong frame.
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
+ which is usually sent automatically in response to a ping frame
+ from the remote peer.
- This function is used to synchronously send a pong frame on
- the stream. The call blocks until one of the following is true:
+ The call blocks until one of the following conditions is true:
- @li The pong frame finishes sending.
+ @li The pong frame is written.
- @li An error occurs on the stream.
+ @li An error occurs.
- This function is implemented in terms of one or more calls to the
- next layer's `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
- The WebSocket protocol allows pong frames to be sent from either
- end at any time. It is not necessary to first receive a ping in
- order to send a pong. The remote peer may use the receipt of a
- pong frame as an indication that the connection is not dead.
+ WebSocket allows pong frames to be sent at any time, without first
+ receiving a ping. An unsolicited pong sent in this fashion may
+ indicate to the remote peer that the connection is still active.
@param payload The payload of the pong message, which may be empty.
void
pong(ping_data const& payload);
- /** Send a WebSocket pong frame.
+ /** Send a websocket pong control frame.
- This function is used to synchronously send a pong frame on
- the stream. The call blocks until one of the following is true:
+ This function is used to send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
+ which is usually sent automatically in response to a ping frame
+ from the remote peer.
- @li The pong frame finishes sending.
+ The call blocks until one of the following conditions is true:
- @li An error occurs on the stream.
+ @li The pong frame is written.
- This function is implemented in terms of one or more calls to the
- next layer's `write_some` functions.
+ @li An error occurs.
- The WebSocket protocol allows pong frames to be sent from either
- end at any time. It is not necessary to first receive a ping in
- order to send a pong. The remote peer may use the receipt of a
- pong frame as an indication that the connection is not dead.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
+
+ WebSocket allows pong frames to be sent at any time, without first
+ receiving a ping. An unsolicited pong sent in this fashion may
+ indicate to the remote peer that the connection is still active.
@param payload The payload of the pong message, which may be empty.
void
pong(ping_data const& payload, error_code& ec);
- /** Start an asynchronous operation to send a WebSocket pong frame.
-
- This function is used to asynchronously send a pong frame to
- the stream. The function call always returns immediately. The
- asynchronous operation will continue until one of the following
- is true:
+ /** Send a websocket pong control frame asynchronously.
- @li The entire pong frame is sent.
+ This function is used to asynchronously send a
+ <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
+ which is usually sent automatically in response to a ping frame
+ from the remote peer.
- @li An error occurs on the stream.
+ @li The pong frame is written.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_write_some` functions, and is known as a
- <em>composed operation</em>. The program must ensure that the
- stream performs no other writes until this operation completes.
+ @li An error occurs.
- The WebSocket protocol allows pong frames to be sent from either
- end at any time. It is not necessary to first receive a ping in
- order to send a pong. The remote peer may use the receipt of a
- pong frame as an indication that the connection is not dead.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_write_some`
+ function. The program must ensure that no other calls to @ref ping,
+ @ref pong, @ref async_ping, or @ref async_pong are performed until
+ this operation completes.
If a close frame is sent or received before the pong frame is
- sent, the completion handler will be called with the error
- set to `boost::asio::error::operation_aborted`.
+ sent, the error received by this completion handler will be
+ `net::error::operation_aborted`.
+
+ WebSocket allows pong frames to be sent at any time, without first
+ receiving a ping. An unsolicited pong sent in this fashion may
+ indicate to the remote peer that the connection is still active.
@param payload The payload of the pong message, which may be empty.
+ The implementation will not access the contents of this object after
+ the initiating function returns.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec // Result of operation
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
- template<class WriteHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- WriteHandler, void(error_code))
- async_pong(ping_data const& payload, WriteHandler&& handler);
+ template<
+ BOOST_BEAST_ASYNC_TPARAM1 WriteHandler =
+ net::default_completion_token_t<executor_type>
+ >
+ BOOST_BEAST_ASYNC_RESULT1(WriteHandler)
+ async_pong(
+ ping_data const& payload,
+ WriteHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
//--------------------------------------------------------------------------
//
//
//--------------------------------------------------------------------------
- /** Read a message
+ /** Read a complete message.
+
+ This function is used to read a complete message.
- This function is used to synchronously read a complete
- message from the stream.
The call blocks until one of the following is true:
@li A complete message is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
@return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to hold the message data after any
- masking or decompression has been applied.
+ @param buffer A dynamic buffer to append message data to.
- @throws system_error Thrown to indicate an error. The corresponding
- error code may be retrieved from the exception object for inspection.
+ @throws system_error Thrown on failure.
*/
template<class DynamicBuffer>
std::size_t
read(DynamicBuffer& buffer);
- /** Read a message
+ /** Read a complete message.
+
+ This function is used to read a complete message.
- This function is used to synchronously read a complete
- message from the stream.
The call blocks until one of the following is true:
@li A complete message is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
@return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to hold the message data after any
- masking or decompression has been applied.
+ @param buffer A dynamic buffer to append message data to.
@param ec Set to indicate what error occurred, if any.
*/
std::size_t
read(DynamicBuffer& buffer, error_code& ec);
- /** Read a message asynchronously
+ /** Read a complete message asynchronously.
+
+ This function is used to asynchronously read a complete message.
- This function is used to asynchronously read a complete
- message from the stream.
- The function call always returns immediately.
- The asynchronous operation will continue until one of the
- following is true:
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
@li A complete message is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions,
- and is known as a <em>composed operation</em>. The program must
- ensure that the stream performs no other reads until this operation
- completes.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. The program must ensure that no other
+ calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
+ are performed until this operation completes.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
- While this operation is active, the implementation will read incoming
+ Until the operation completes, the implementation will read incoming
control frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
- Because of the need to handle control frames, asynchronous read
- operations can cause writes to take place. These writes are managed
- transparently; callers can still have one active asynchronous
- read and asynchronous write operation pending simultaneously
- (a user initiated call to @ref async_close counts as a write).
+ Pong frames and close frames sent by the implementation while the
+ read operation is outstanding do not prevent the application from
+ also writing message data, sending pings, sending pongs, or sending
+ close frames.
- @param buffer A dynamic buffer to hold the message data after
- any masking or decompression has been applied. This object must
- remain valid until the handler is called.
+ @param buffer A dynamic buffer to append message data to.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec, // Result of operation
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
- template<class DynamicBuffer, class ReadHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- ReadHandler, void(error_code, std::size_t))
+ template<
+ class DynamicBuffer,
+ BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
+ net::default_completion_token_t<
+ executor_type>>
+ BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
async_read(
DynamicBuffer& buffer,
- ReadHandler&& handler);
+ ReadHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
//--------------------------------------------------------------------------
- /** Read part of a message
+ /** Read some message data.
+
+ This function is used to read some message data.
- This function is used to synchronously read some
- message data from the stream.
The call blocks until one of the following is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
The function @ref is_message_done may be called to determine if the
message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
@return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to hold the message data after any
- masking or decompression has been applied.
+ @param buffer A dynamic buffer to append message data to.
@param limit An upper limit on the number of bytes this function
will append into the buffer. If this value is zero, then a reasonable
size will be chosen automatically.
- @throws system_error Thrown to indicate an error. The corresponding
- error code may be retrieved from the exception object for inspection.
+ @throws system_error Thrown on failure.
*/
template<class DynamicBuffer>
std::size_t
DynamicBuffer& buffer,
std::size_t limit);
- /** Read part of a message
+ /** Read some message data.
+
+ This function is used to read some message data.
- This function is used to synchronously read some
- message data from the stream.
The call blocks until one of the following is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
The function @ref is_message_done may be called to determine if the
message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
@return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to hold the message data after any
- masking or decompression has been applied.
+ @param buffer A dynamic buffer to append message data to.
@param limit An upper limit on the number of bytes this function
will append into the buffer. If this value is zero, then a reasonable
std::size_t limit,
error_code& ec);
- /** Read part of a message asynchronously
+ /** Read some message data asynchronously.
+
+ This function is used to asynchronously read some message data.
- This function is used to asynchronously read part of a
- message from the stream.
- The function call always returns immediately.
- The asynchronous operation will continue until one of the
- following is true:
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions,
- and is known as a <em>composed operation</em>. The program must
- ensure that the stream performs no other reads until this operation
- completes.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. The program must ensure that no other
+ calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
+ are performed until this operation completes.
- Received message data, if any, is appended to the input area of the
- buffer. The functions @ref got_binary and @ref got_text may be used
+ Received message data is appended to the buffer.
+ The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
+ Until the operation completes, the implementation will read incoming
control frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
- Because of the need to handle control frames, asynchronous read
- operations can cause writes to take place. These writes are managed
- transparently; callers can still have one active asynchronous
- read and asynchronous write operation pending simultaneously
- (a user initiated call to @ref async_close counts as a write).
+ Pong frames and close frames sent by the implementation while the
+ read operation is outstanding do not prevent the application from
+ also writing message data, sending pings, sending pongs, or sending
+ close frames.
- @param buffer A dynamic buffer to hold the message data after
- any masking or decompression has been applied. This object must
- remain valid until the handler is called.
+ @param buffer A dynamic buffer to append message data to.
@param limit An upper limit on the number of bytes this function
will append into the buffer. If this value is zero, then a reasonable
size will be chosen automatically.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec, // Result of operation
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
- template<class DynamicBuffer, class ReadHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- ReadHandler, void(error_code, std::size_t))
+ template<
+ class DynamicBuffer,
+ BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
+ net::default_completion_token_t<
+ executor_type>>
+ BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
async_read_some(
DynamicBuffer& buffer,
std::size_t limit,
- ReadHandler&& handler);
+ ReadHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
//--------------------------------------------------------------------------
- /** Read part of a message
+ /** Read some message data.
+
+ This function is used to read some message data.
- This function is used to synchronously read some
- message data from the stream.
The call blocks until one of the following is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is written to the buffer sequence.
The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
The function @ref is_message_done may be called to determine if the
message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
- @return The number of message payload bytes written to the
- buffer sequence.
+ @return The number of message payload bytes appended to the buffer.
- @param buffers A buffer sequence to hold the message data after any
- masking or decompression has been applied.
+ @param buffers A buffer sequence to write message data into.
+ The previous contents of the buffers will be overwritten, starting
+ from the beginning.
- @throws system_error Thrown to indicate an error. The corresponding
- error code may be retrieved from the exception object for inspection.
+ @throws system_error Thrown on failure.
*/
template<class MutableBufferSequence>
std::size_t
read_some(
MutableBufferSequence const& buffers);
- /** Read part of a message
+ /** Read some message data.
+
+ This function is used to read some message data.
- This function is used to synchronously read some
- message data from the stream.
The call blocks until one of the following is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the next
- layer's `read_some` and `write_some` functions.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `read_some` and `write_some`
+ functions.
- Received message data, if any, is written to the buffer sequence.
The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
The function @ref is_message_done may be called to determine if the
message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
- control frames and handle them automatically as follows:
+ Until the call returns, the implementation will read incoming control
+ frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
@li For each received ping frame, a pong frame will be
automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
+ @li If a close frame is received, the WebSocket closing handshake is
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
- @return The number of message payload bytes written to the
- buffer sequence.
+ @return The number of message payload bytes appended to the buffer.
- @param buffers A buffer sequence to hold the message data after any
- masking or decompression has been applied.
+ @param buffers A buffer sequence to write message data into.
+ The previous contents of the buffers will be overwritten, starting
+ from the beginning.
@param ec Set to indicate what error occurred, if any.
*/
MutableBufferSequence const& buffers,
error_code& ec);
- /** Read part of a message asynchronously
+ /** Read some message data asynchronously.
+
+ This function is used to asynchronously read some message data.
- This function is used to asynchronously read part of a
- message from the stream.
- The function call always returns immediately.
- The asynchronous operation will continue until one of the
- following is true:
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @li Some or all of the message is received.
+ @li Some message data is received.
@li A close frame is received. In this case the error indicated by
the function will be @ref error::closed.
- @li An error occurs on the stream.
+ @li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `async_read_some` and `async_write_some` functions,
- and is known as a <em>composed operation</em>. The program must
- ensure that the stream performs no other reads until this operation
- completes.
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's `async_read_some`
+ and `async_write_some` functions. The program must ensure that no other
+ calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
+ are performed until this operation completes.
- Received message data, if any, is written to the buffer sequence.
+ Received message data is appended to the buffer.
The functions @ref got_binary and @ref got_text may be used
to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- While this operation is active, the implementation will read incoming
+ Until the operation completes, the implementation will read incoming
control frames and handle them automatically as follows:
@li The @ref control_callback will be invoked for each control frame.
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
- Because of the need to handle control frames, asynchronous read
- operations can cause writes to take place. These writes are managed
- transparently; callers can still have one active asynchronous
- read and asynchronous write operation pending simultaneously
- (a user initiated call to @ref async_close counts as a write).
-
- @param buffers The buffer sequence into which message data will
- be placed after any masking or decompresison has been applied.
- The implementation will make copies of this object as needed,
- but ownership of the underlying memory is not transferred.
- The caller is responsible for ensuring that the memory
- locations pointed to by the buffer sequence remains valid
- until the completion handler is called.
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
+ Pong frames and close frames sent by the implementation while the
+ read operation is outstanding do not prevent the application from
+ also writing message data, sending pings, sending pongs, or sending
+ close frames.
+
+ @param buffers A buffer sequence to write message data into.
+ The previous contents of the buffers will be overwritten, starting
+ from the beginning.
+ The implementation will make copies of this object as needed, but
+ but ownership of the underlying memory is not transferred. The
+ caller is responsible for ensuring that the memory locations
+ pointed to by the buffer sequence remain valid until the
+ completion handler is called.
+
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec, // Result of operation
- std::size_t bytes_written // Number of bytes written to the buffer sequence
+ std::size_t bytes_written // Number of bytes written to the buffers
);
@endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
- template<class MutableBufferSequence, class ReadHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- ReadHandler, void(error_code, std::size_t))
+ template<
+ class MutableBufferSequence,
+ BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
+ net::default_completion_token_t<
+ executor_type>>
+ BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
async_read_some(
MutableBufferSequence const& buffers,
- ReadHandler&& handler);
+ ReadHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
//--------------------------------------------------------------------------
//
//
//--------------------------------------------------------------------------
- /** Write a message to the stream.
+ /** Write a complete message.
- This function is used to synchronously write a message to
- the stream. The call blocks until one of the following conditions
- is met:
+ This function is used to write a complete message.
+
+ The call blocks until one of the following is true:
- @li The entire message is sent.
+ @li The message is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `write_some` function.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
The current setting of the @ref binary option controls
whether the message opcode is set to text or binary. If the
into one or more frames as necessary. The actual payload contents
sent may be transformed as per the WebSocket protocol settings.
- @param buffers The buffers containing the entire message
- payload. The implementation will make copies of this object
- as needed, but ownership of the underlying memory is not
- transferred. The caller is responsible for ensuring that
- the memory locations pointed to by buffers remains valid
- until the completion handler is called.
+ @param buffers The buffers containing the message to send.
- @return The number of bytes written from the buffers.
- If an error occurred, this will be less than the sum
- of the buffer sizes.
+ @return The number of bytes sent from the buffers.
@throws system_error Thrown on failure.
-
- @note This function always sends an entire message. To
- send a message in fragments, use @ref write_some.
*/
template<class ConstBufferSequence>
std::size_t
write(ConstBufferSequence const& buffers);
- /** Write a message to the stream.
+ /** Write a complete message.
- This function is used to synchronously write a message to
- the stream. The call blocks until one of the following conditions
- is met:
+ This function is used to write a complete message.
+
+ The call blocks until one of the following is true:
- @li The entire message is sent.
+ @li The complete message is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls to the
- next layer's `write_some` function.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
The current setting of the @ref binary option controls
whether the message opcode is set to text or binary. If the
into one or more frames as necessary. The actual payload contents
sent may be transformed as per the WebSocket protocol settings.
- @param buffers The buffers containing the entire message
- payload. The implementation will make copies of this object
- as needed, but ownership of the underlying memory is not
- transferred. The caller is responsible for ensuring that
- the memory locations pointed to by buffers remains valid
- until the completion handler is called.
-
- @return The number of bytes written from the buffers.
- If an error occurred, this will be less than the sum
- of the buffer sizes.
+ @param buffers The buffers containing the message to send.
@param ec Set to indicate what error occurred, if any.
- @throws system_error Thrown on failure.
-
- @note This function always sends an entire message. To
- send a message in fragments, use @ref write_some.
+ @return The number of bytes sent from the buffers.
*/
template<class ConstBufferSequence>
std::size_t
write(ConstBufferSequence const& buffers, error_code& ec);
- /** Start an asynchronous operation to write a message to the stream.
+ /** Write a complete message asynchronously.
- This function is used to asynchronously write a message to
- the stream. The function call always returns immediately.
- The asynchronous operation will continue until one of the
- following conditions is true:
+ This function is used to asynchronously write a complete message.
- @li The entire message is sent.
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
+
+ @li The complete message is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls
- to the next layer's `async_write_some` functions, and is known
- as a <em>composed operation</em>. The program must ensure that
- the stream performs no other write operations (such as
- @ref async_write, @ref async_write_some, or
- @ref async_close).
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's
+ `async_write_some` function. The program must ensure that no other
+ calls to @ref write, @ref write_some, @ref async_write, or
+ @ref async_write_some are performed until this operation completes.
The current setting of the @ref binary option controls
whether the message opcode is set to text or binary. If the
into one or more frames as necessary. The actual payload contents
sent may be transformed as per the WebSocket protocol settings.
- @param buffers The buffers containing the entire message
+ @param buffers A buffer sequence containing the entire message
payload. The implementation will make copies of this object
as needed, but ownership of the underlying memory is not
transferred. The caller is responsible for ensuring that
the memory locations pointed to by buffers remains valid
until the completion handler is called.
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The function signature of the handler must be:
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
@code
void handler(
error_code const& ec, // Result of operation
- std::size_t bytes_transferred // Number of bytes written from the
+ std::size_t bytes_transferred // Number of bytes sent from the
// buffers. If an error occurred,
- // this will be less than the sum
- // of the buffer sizes.
+ // this will be less than the buffer_size.
);
@endcode
Regardless of whether the asynchronous operation completes
immediately or not, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
- manner equivalent to using `boost::asio::io_context::post`.
+ manner equivalent to using `net::post`.
*/
template<
class ConstBufferSequence,
- class WriteHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- WriteHandler, void(error_code, std::size_t))
+ BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
+ net::default_completion_token_t<
+ executor_type>>
+ BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write(
ConstBufferSequence const& buffers,
- WriteHandler&& handler);
+ WriteHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
- /** Write partial message data on the stream.
+ /** Write some message data.
- This function is used to write some or all of a message's
- payload to the stream. The call will block until one of the
- following conditions is true:
+ This function is used to send part of a message.
- @li A frame is sent.
+ The call blocks until one of the following is true:
- @li Message data is transferred to the write buffer.
+ @li The message data is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls
- to the stream's `write_some` function.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
If this is the beginning of a new message, the message opcode
- will be set to text or binary as per the current setting of
- the @ref binary option. The actual payload sent may be
- transformed as per the WebSocket protocol settings.
+ will be set to text or binary based on the current setting of
+ the @ref binary (or @ref text) option. The actual payload sent
+ may be transformed as per the WebSocket protocol settings.
@param fin `true` if this is the last part of the message.
- @param buffers The input buffer sequence holding the data to write.
+ @param buffers The buffers containing the message part to send.
- @return The number of bytes written from the buffers.
- If an error occurred, this will be less than the sum
- of the buffer sizes.
+ @return The number of bytes sent from the buffers.
@throws system_error Thrown on failure.
*/
std::size_t
write_some(bool fin, ConstBufferSequence const& buffers);
- /** Write partial message data on the stream.
+ /** Write some message data.
- This function is used to write some or all of a message's
- payload to the stream. The call will block until one of the
- following conditions is true:
+ This function is used to send part of a message.
- @li A frame is sent.
+ The call blocks until one of the following is true:
- @li Message data is transferred to the write buffer.
+ @li The message data is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls
- to the stream's `write_some` function.
+ The algorithm, known as a <em>composed operation</em>, is implemented
+ in terms of calls to the next layer's `write_some` function.
If this is the beginning of a new message, the message opcode
- will be set to text or binary as per the current setting of
- the @ref binary option. The actual payload sent may be
- transformed as per the WebSocket protocol settings.
+ will be set to text or binary based on the current setting of
+ the @ref binary (or @ref text) option. The actual payload sent
+ may be transformed as per the WebSocket protocol settings.
@param fin `true` if this is the last part of the message.
- @param buffers The input buffer sequence holding the data to write.
+ @param buffers The buffers containing the message part to send.
@param ec Set to indicate what error occurred, if any.
- @return The number of bytes written from the buffers.
- If an error occurred, this will be less than the sum
- of the buffer sizes.
+ @return The number of bytes sent from the buffers.
@return The number of bytes consumed in the input buffers.
*/
write_some(bool fin,
ConstBufferSequence const& buffers, error_code& ec);
- /** Start an asynchronous operation to send a message frame on the stream.
+ /** Write some message data asynchronously.
+
+ This function is used to asynchronously write part of a message.
- This function is used to asynchronously write a message frame
- on the stream. This function call always returns immediately.
- The asynchronous operation will continue until one of the following
- conditions is true:
+ This call always returns immediately. The asynchronous operation
+ will continue until one of the following conditions is true:
- @li The entire frame is sent.
+ @li The message data is written.
@li An error occurs.
- This operation is implemented in terms of one or more calls
- to the next layer's `async_write_some` functions, and is known
- as a <em>composed operation</em>. The actual payload sent
- may be transformed as per the WebSocket protocol settings. The
- program must ensure that the stream performs no other write
- operations (such as @ref async_write, @ref async_write_some,
- or @ref async_close).
+ The algorithm, known as a <em>composed asynchronous operation</em>,
+ is implemented in terms of calls to the next layer's
+ `async_write_some` function. The program must ensure that no other
+ calls to @ref write, @ref write_some, @ref async_write, or
+ @ref async_write_some are performed until this operation completes.
If this is the beginning of a new message, the message opcode
- will be set to text or binary as per the current setting of
- the @ref binary option. The actual payload sent may be
- transformed as per the WebSocket protocol settings.
+ will be set to text or binary based on the current setting of
+ the @ref binary (or @ref text) option. The actual payload sent
+ may be transformed as per the WebSocket protocol settings.
@param fin `true` if this is the last part of the message.
- @param buffers A object meeting the requirements of
- ConstBufferSequence which holds the payload data before any
- masking or compression. Although the buffers object may be copied
- as necessary, ownership of the underlying buffers is retained by
- the caller, which must guarantee that they remain valid until
- the handler is called.
-
- @param handler Invoked when the operation completes.
- The handler may be moved or copied as needed.
- The equivalent function signature of the handler must be:
- @code void handler(
+ @param buffers The buffers containing the message part to send.
+ The implementation will make copies of this object
+ as needed, but ownership of the underlying memory is not
+ transferred. The caller is responsible for ensuring that
+ the memory locations pointed to by buffers remains valid
+ until the completion handler is called.
+
+ @param handler The completion handler to invoke when the operation
+ completes. The implementation takes ownership of the handler by
+ performing a decay-copy. The equivalent function signature of
+ the handler must be:
+ @code
+ void handler(
error_code const& ec, // Result of operation
- std::size_t bytes_transferred // Number of bytes written from the
+ std::size_t bytes_transferred // Number of bytes sent from the
// buffers. If an error occurred,
- // this will be less than the sum
- // of the buffer sizes.
- ); @endcode
+ // this will be less than the buffer_size.
+ );
+ @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `net::post`.
*/
- template<class ConstBufferSequence, class WriteHandler>
- BOOST_ASIO_INITFN_RESULT_TYPE(
- WriteHandler, void(error_code, std::size_t))
- async_write_some(bool fin,
- ConstBufferSequence const& buffers, WriteHandler&& handler);
-
-private:
- template<class, class> class accept_op;
- template<class> class close_op;
- template<class> class handshake_op;
- template<class> class ping_op;
- template<class, class> class read_some_op;
- template<class, class> class read_op;
- template<class> class response_op;
- template<class, class> class write_some_op;
- template<class, class> class write_op;
+ template<
+ class ConstBufferSequence,
+ BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
+ net::default_completion_token_t<
+ executor_type>>
+ BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
+ async_write_some(
+ bool fin,
+ ConstBufferSequence const& buffers,
+ WriteHandler&& handler =
+ net::default_completion_token_t<
+ executor_type>{});
- static void default_decorate_req(request_type&) {}
- static void default_decorate_res(response_type&) {}
+ //
+ // Deprecated
+ //
+#if ! BOOST_BEAST_DOXYGEN
+ template<class RequestDecorator>
void
- set_option(permessage_deflate const& o, std::true_type);
+ handshake_ex(
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator);
+ template<class RequestDecorator>
void
- set_option(permessage_deflate const&, std::false_type);
+ handshake_ex(
+ response_type& res,
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator);
+ template<class RequestDecorator>
void
- get_option(permessage_deflate& o, std::true_type)
- {
- o = this->pmd_opts_;
- }
+ handshake_ex(
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator,
+ error_code& ec);
+ template<class RequestDecorator>
void
- get_option(permessage_deflate& o, std::false_type)
- {
- o = {};
- o.client_enable = false;
- o.server_enable = false;
- }
-
- void open(role_type role);
-
- void open_pmd(std::true_type);
-
- void open_pmd(std::false_type)
- {
- }
-
- void close();
-
- void close_pmd(std::true_type)
- {
- this->pmd_.reset();
- }
-
- void close_pmd(std::false_type)
- {
- }
-
- void reset();
-
- void begin_msg()
- {
- begin_msg(is_deflate_supported{});
- }
-
- void begin_msg(std::true_type);
-
- void begin_msg(std::false_type);
-
- std::size_t
- read_size_hint(
- std::size_t initial_size,
- std::true_type) const;
-
- std::size_t
- read_size_hint(
- std::size_t initial_size,
- std::false_type) const;
-
- bool
- check_open(error_code& ec)
- {
- if(status_ != status::open)
- {
- ec = boost::asio::error::operation_aborted;
- return false;
- }
- ec.assign(0, ec.category());
- return true;
- }
+ handshake_ex(
+ response_type& res,
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator,
+ error_code& ec);
- bool
- check_ok(error_code& ec)
- {
- if(ec)
- {
- if(status_ != status::closed)
- status_ = status::failed;
- return false;
- }
- return true;
- }
+ template<class RequestDecorator, class HandshakeHandler>
+ BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
+ async_handshake_ex(
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator,
+ HandshakeHandler&& handler);
- template<class DynamicBuffer>
- bool
- parse_fh(
- detail::frame_header& fh,
- DynamicBuffer& b,
- error_code& ec);
+ template<class RequestDecorator, class HandshakeHandler>
+ BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
+ async_handshake_ex(
+ response_type& res,
+ string_view host,
+ string_view target,
+ RequestDecorator const& decorator,
+ HandshakeHandler&& handler);
- template<class DynamicBuffer>
+ template<class ResponseDecorator>
void
- write_close(DynamicBuffer& b, close_reason const& rc);
+ accept_ex(ResponseDecorator const& decorator);
- template<class DynamicBuffer>
+ template<class ResponseDecorator>
void
- write_ping(DynamicBuffer& b,
- detail::opcode op, ping_data const& data);
+ accept_ex(
+ ResponseDecorator const& decorator,
+ error_code& ec);
- //
- // upgrade
- //
+ template<class ConstBufferSequence,
+ class ResponseDecorator>
+ typename std::enable_if<! http::detail::is_header<
+ ConstBufferSequence>::value>::type
+ accept_ex(
+ ConstBufferSequence const& buffers,
+ ResponseDecorator const& decorator);
- template<class Decorator>
- request_type
- build_request(detail::sec_ws_key_type& key,
- string_view host,
- string_view target,
- Decorator const& decorator);
+ template<class ConstBufferSequence, class ResponseDecorator>
+ typename std::enable_if<! http::detail::is_header<
+ ConstBufferSequence>::value>::type
+ accept_ex(
+ ConstBufferSequence const& buffers,
+ ResponseDecorator const& decorator,
+ error_code& ec);
+ template<class Body, class Allocator,
+ class ResponseDecorator>
void
- build_request_pmd(request_type& req, std::true_type);
+ accept_ex(http::request<Body,
+ http::basic_fields<Allocator>> const& req,
+ ResponseDecorator const& decorator);
+ template<class Body, class Allocator,
+ class ResponseDecorator>
void
- build_request_pmd(request_type&, std::false_type)
- {
- }
+ accept_ex(http::request<Body,
+ http::basic_fields<Allocator>> const& req,
+ ResponseDecorator const& decorator,
+ error_code& ec);
template<
- class Body, class Allocator, class Decorator>
- response_type
- build_response(
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- Decorator const& decorator,
- error_code& ec);
+ class ResponseDecorator,
+ class AcceptHandler>
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept_ex(
+ ResponseDecorator const& decorator,
+ AcceptHandler&& handler);
- template<class Body, class Allocator>
- void
- build_response_pmd(
- response_type& res,
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- std::true_type);
+ template<
+ class ConstBufferSequence,
+ class ResponseDecorator,
+ class AcceptHandler>
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept_ex(
+ ConstBufferSequence const& buffers,
+ ResponseDecorator const& decorator,
+ AcceptHandler&& handler,
+ typename std::enable_if<
+ ! http::detail::is_header<
+ ConstBufferSequence>::value>::type* = 0);
- template<class Body, class Allocator>
- void
- build_response_pmd(
- response_type&,
+ template<
+ class Body, class Allocator,
+ class ResponseDecorator,
+ class AcceptHandler>
+ BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
+ async_accept_ex(
http::request<Body,
- http::basic_fields<Allocator>> const&,
- std::false_type)
- {
- }
+ http::basic_fields<Allocator>> const& req,
+ ResponseDecorator const& decorator,
+ AcceptHandler&& handler);
+#endif
- void
- on_response(
- response_type const& res,
- detail::sec_ws_key_type const& key,
- error_code& ec);
+private:
+ template<class, class> class accept_op;
+ template<class> class close_op;
+ template<class> class handshake_op;
+ template<class> class ping_op;
+ template<class> class idle_ping_op;
+ template<class, class> class read_some_op;
+ template<class, class> class read_op;
+ template<class> class response_op;
+ template<class, class> class write_some_op;
+ template<class, class> class write_op;
- void
- on_response_pmd(
- response_type const& res,
- std::true_type);
+ struct run_accept_op;
+ struct run_close_op;
+ struct run_handshake_op;
+ struct run_ping_op;
+ struct run_idle_ping_op;
+ struct run_read_some_op;
+ struct run_read_op;
+ struct run_response_op;
+ struct run_write_some_op;
+ struct run_write_op;
- void
- on_response_pmd(
- response_type const&,
- std::false_type)
- {
- }
+ static void default_decorate_req(request_type&) {}
+ static void default_decorate_res(response_type&) {}
//
// accept / handshake
//
- template<class Allocator>
- void
- do_pmd_config(
- http::basic_fields<Allocator> const& h,
- std::true_type)
- {
- pmd_read(this->pmd_config_, h);
- }
-
- template<class Allocator>
- void
- do_pmd_config(
- http::basic_fields<Allocator> const&,
- std::false_type)
- {
- }
-
- template<class Decorator>
+ template<class Buffers, class Decorator>
void
do_accept(
+ Buffers const& buffers,
Decorator const& decorator,
error_code& ec);
error_code& ec);
};
+/** Manually provide a one-time seed to initialize the PRNG
+
+ This function invokes the specified seed sequence to produce a seed
+ suitable for use with the pseudo-random number generator used to
+ create masks and perform WebSocket protocol handshakes.
+
+ If a seed is not manually provided, the implementation will
+ perform a one-time seed generation using `std::random_device`. This
+ function may be used when the application runs in an environment
+ where the random device is unreliable or does not provide sufficient
+ entropy.
+
+ @par Preconditions
+
+ This function may not be called after any websocket @ref stream objects
+ have been constructed.
+
+ @param ss A reference to a `std::seed_seq` which will be used to seed
+ the pseudo-random number generator. The seed sequence should have at
+ least 256 bits of entropy.
+
+ @see stream::secure_prng
+*/
+inline
+void
+seed_prng(std::seed_seq& ss)
+{
+ detail::prng_seed(&ss);
+}
+
} // websocket
} // beast
} // boost
-#include <boost/beast/websocket/impl/accept.ipp>
-#include <boost/beast/websocket/impl/close.ipp>
-#include <boost/beast/websocket/impl/handshake.ipp>
-#include <boost/beast/websocket/impl/ping.ipp>
-#include <boost/beast/websocket/impl/read.ipp>
-#include <boost/beast/websocket/impl/stream.ipp>
-#include <boost/beast/websocket/impl/write.ipp>
+#include <boost/beast/websocket/impl/stream_impl.hpp> // must be first
+#include <boost/beast/websocket/impl/accept.hpp>
+#include <boost/beast/websocket/impl/close.hpp>
+#include <boost/beast/websocket/impl/handshake.hpp>
+#include <boost/beast/websocket/impl/ping.hpp>
+#include <boost/beast/websocket/impl/read.hpp>
+#include <boost/beast/websocket/impl/stream.hpp>
+#include <boost/beast/websocket/impl/write.hpp>
#endif
projects / ceph.git / blobdiff