PurpleI2P/Boost-for-Android-Prebuilt
1
0
Fork 0
mirror of https://github.com/PurpleI2P/Boost-for-Android-Prebuilt synced 2025-01-10 14:57:52 +00:00
Code Issues Releases Wiki Activity
8c917088ef
Boost-for-Android-Prebuilt/boost-1_72_0/include/boost/beast/websocket/stream.hpp
r4sas 93de5720b8
add boost 1.72.0 
Signed-off-by: r4sas <r4sas@i2pmail.org>
2020-02-29 22:43:48 +00:00

2777 lines
104 KiB
C++
Raw Blame History

//
// Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/beast
//
#ifndef BOOST_BEAST_WEBSOCKET_STREAM_HPP
#define BOOST_BEAST_WEBSOCKET_STREAM_HPP
#include <boost/beast/core/detail/config.hpp>
#include <boost/beast/websocket/error.hpp>
#include <boost/beast/websocket/option.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/hybi13.hpp>
#include <boost/beast/websocket/detail/impl_base.hpp>
#include <boost/beast/websocket/detail/pmd_extension.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/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 received control frame.
Values of this type are passed to the control frame
callback set using @ref stream::control_callback.
*/
enum class frame_type
{
/// A close frame was received
close,
/// A ping frame was received
ping,
/// A pong frame was received
pong
};
namespace detail {
class frame_test;
} // detail
//--------------------------------------------------------------------
/** Provides message-oriented functionality using WebSocket.
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.
@par Thread Safety
@e Distinct @e objects: Safe.@n
@e Shared @e objects: Unsafe.
The application must also ensure that all asynchronous
operations are performed within the same implicit or explicit strand.
@par Example
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<tcp_stream> ws{net::io_context::strand(ioc)};
@endcode
Alternatively, for a single-threaded or synchronous application
you may write:
@code
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 <em>SyncStream</em> concept.
For asynchronous operations, the type must support the
<em>AsyncStream</em> concept.
@tparam deflateSupported A `bool` indicating whether or not the
stream will be capable of negotiating the permessage-deflate websocket
extension. Note that even if this is set to `true`, the permessage
deflate options (set by the caller at runtime) must still have the
feature enabled for a successful negotiation to occur.
@note A stream object must not be moved or destroyed while there
are pending asynchronous operations associated with it.
@par Concepts
@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
#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 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;
static time_point never() noexcept
{
return (time_point::max)();
}
public:
/// Indicates if the permessage-deflate extension is supported
using is_deflate_supported =
std::integral_constant<bool, deflateSupported>;
/// The type of the next layer.
using next_layer_type =
typename std::remove_reference<NextLayer>::type;
/// The type of the executor associated with the object.
using executor_type =
beast::executor_type<next_layer_type>;
/** Destructor
Destroys the stream and all associated resources.
@note A stream object must not be destroyed while there
are pending asynchronous operations associated with it.
*/
~stream();
/** Constructor
If `NextLayer` is move constructible, this function
will move-construct a new stream from the existing stream.
After the move, the only valid operation on the moved-from
object is destruction.
*/
stream(stream&&) = default;
/// Move assignment (deleted)
stream& operator=(stream&&) = delete;
/** Constructor
This constructor creates a websocket stream and initializes
the next layer object.
@throws Any exceptions thrown by the NextLayer constructor.
@param args The arguments to be passed to initialize the
next layer object. The arguments are forwarded to the next
layer's constructor.
*/
template<class... Args>
explicit
stream(Args&&... args);
//--------------------------------------------------------------------------
/** 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;
/** Get a reference to the next layer
This function returns a reference to the next layer
in a stack of stream layers.
@return A reference to the next layer in the stack of
stream layers.
*/
next_layer_type&
next_layer() noexcept;
/** Get a reference to the next layer
This function returns a reference to the next layer in a
stack of stream layers.
@return A reference to the next layer in the stack of
stream layers.
*/
next_layer_type const&
next_layer() const noexcept;
//--------------------------------------------------------------------------
//
// Observers
//
//--------------------------------------------------------------------------
/** Returns `true` if the stream is open.
The stream is open after a successful handshake, and when
no error has occurred.
*/
bool
is_open() const noexcept;
/** Returns `true` if the latest message data indicates binary.
This function informs the caller of whether the last
received message frame represents a message with the
binary opcode.
If there is no last message frame, the return value is
undefined.
*/
bool
got_binary() const noexcept;
/** Returns `true` if the latest message data indicates text.
This function informs the caller of whether the last
received message frame represents a message with the
text opcode.
If there is no last message frame, the return value is
undefined.
*/
bool
got_text() const
{
return ! got_binary();
}
/// Returns `true` if the last completed read finished the current message.
bool
is_message_done() const noexcept;
/** 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 noexcept;
/** Returns a suggested maximum buffer size for the next call to read.
This function returns a reasonable upper limit on the number
of bytes for the size of the buffer passed in the next call
to read. The number is determined by the state of the current
frame and whether or not the permessage-deflate extension is
enabled.
@param initial_size A non-zero size representing the caller's
desired buffer size for when there is no information which may
be used to calculate a more specific value. For example, when
reading the first frame header of a message.
*/
std::size_t
read_size_hint(
std::size_t initial_size = +tcp_frame_size) const;
/** Returns a suggested maximum buffer size for the next call to read.
This function returns a reasonable upper limit on the number
of bytes for the size of the buffer passed in the next call
to read. The number is determined by the state of the current
frame and whether or not the permessage-deflate extension is
enabled.
@param buffer The buffer which will be used for reading. The
implementation will query the buffer to obtain the optimum
size of a subsequent call to `buffer.prepare` based on the
state of the current frame, if any.
*/
template<class DynamicBuffer
#if ! BOOST_BEAST_DOXYGEN
, class = typename std::enable_if<
! std::is_integral<DynamicBuffer>::value>::type
#endif
>
std::size_t
read_size_hint(
DynamicBuffer& buffer) const;
//--------------------------------------------------------------------------
//
// Settings
//
//--------------------------------------------------------------------------
#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);
/// Get the permessage-deflate extension options
void
get_option(permessage_deflate& o);
/** Set the automatic fragmentation option.
Determines if outgoing message payloads are broken up into
multiple pieces.
When the automatic fragmentation size is turned on, outgoing
message payloads are broken up into multiple frames no larger
than the write buffer size.
The default setting is to fragment messages.
@param value A `bool` indicating if auto fragmentation should be on.
@par Example
Setting the automatic fragmentation option:
@code
ws.auto_fragment(true);
@endcode
*/
void
auto_fragment(bool value);
/// Returns `true` if the automatic fragmentation option is set.
bool
auto_fragment() const;
/** 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
at the start when a caller begins a new message. Changing
the opcode after a message is started will only take effect
after the current message being sent is complete.
The default setting is to send text messages.
@param value `true` if outgoing messages should indicate
binary, or `false` if they should indicate text.
@par Example
Setting the message type to binary.
@code
ws.binary(true);
@endcode
*/
void
binary(bool value);
/// Returns `true` if the binary message write option is set.
bool
binary() const;
/** Set a callback to be invoked on each incoming control frame.
Sets the callback to be invoked whenever a ping, pong,
or close control frame is received during a call to one
of the following functions:
@li @ref beast::websocket::stream::read
@li @ref beast::websocket::stream::read_some
@li @ref beast::websocket::stream::async_read
@li @ref beast::websocket::stream::async_read_some
Unlike completion handlers, the callback will be invoked
for each control frame during a call to any synchronous
or asynchronous read function. The operation is passive,
with no associated error code, and triggered by reads.
For close frames, the close reason code may be obtained by
calling the function @ref reason.
@param cb The function object to call, which must be
invocable with this equivalent signature:
@code
void
callback(
frame_type kind, // The type of frame
string_view payload // The payload in the frame
);
@endcode
The implementation type-erases the callback which may require
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
the same method as that used to invoke the final handler.
@note Incoming ping and close frames are automatically
handled. Pings are responded to with pongs, and a close frame
is responded to with a close frame leading to the closure of
the stream. It is not necessary to manually send pings, pongs,
or close frames from inside the control callback.
Attempting to manually send a close frame from inside the
control callback after receiving a close frame will result
in undefined behavior.
*/
void
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();
/** Set the maximum incoming message size option.
Sets the largest permissible incoming message size. Message
frame fields indicating a size that would bring the total
message size over this limit will cause a protocol failure.
The default setting is 16 megabytes. A value of zero indicates
a limit of the maximum value of a `std::uint64_t`.
@par Example
Setting the maximum read message size.
@code
ws.read_message_max(65536);
@endcode
@param amount The limit on the size of incoming messages.
*/
void
read_message_max(std::size_t amount);
/// Returns the maximum incoming message size setting.
std::size_t
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.
Sets the size of the write buffer used by the implementation to
send frames. The write buffer is needed when masking payload data
in the client role, compressing frames, or auto-fragmenting message
data.
Lowering the size of the buffer can decrease the memory requirements
for each connection, while increasing the size of the buffer can reduce
the number of calls made to the next layer to write data.
The default setting is 4096. The minimum value is 8.
The write buffer size can only be changed when the stream is not
open. Undefined behavior results if the option is modified after a
successful WebSocket handshake.
@par Example
Setting the write buffer size.
@code
ws.write_buffer_bytes(8192);
@endcode
@param amount The size of the write buffer in bytes.
*/
void
write_buffer_bytes(std::size_t amount);
/// Returns the size of the write buffer.
std::size_t
write_buffer_bytes() const;
/** 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
at the start when a caller begins a new message. Changing
the opcode after a message is started will only take effect
after the current message being sent is complete.
The default setting is to send text messages.
@param value `true` if outgoing messages should indicate
text, or `false` if they should indicate binary.
@par Example
Setting the message type to text.
@code
ws.text(true);
@endcode
*/
void
text(bool value);
/// Returns `true` if the text message write option is set.
bool
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?
*/
//--------------------------------------------------------------------------
//
// Handshaking (Client)
//
//--------------------------------------------------------------------------
/** Perform the WebSocket handshake in the client role.
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.
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 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.
@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
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);
/** Perform the WebSocket handshake in the client role.
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.
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 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. The caller may use the response to access any
additional information sent by the server.
@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, 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
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(
response_type& res,
string_view host,
string_view target);
/** Perform the WebSocket handshake in the client role.
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.
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 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.
@param target The request-target, in origin-form. The server may use the
target to distinguish different services on the same listening port.
@param ec Set to indicate what error occurred, if any.
@par Example
@code
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>
*/
void
handshake(
string_view host,
string_view target,
error_code& ec);
/** Perform the WebSocket handshake in the client role.
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.
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 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. The caller may use the response to access any
additional information sent by the server.
@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, in origin-form. The server may use the
target to distinguish different services on the same listening port.
@param ec Set to indicate what error occurred, if any.
@par Example
@code
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>
*/
void
handshake(
response_type& res,
string_view host,
string_view target,
error_code& ec);
/** Perform the WebSocket handshake asynchronously in the client role.
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.
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
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>
*/
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,
HandshakeHandler&& handler =
net::default_completion_token_t<
executor_type>{});
/** Perform the WebSocket handshake asynchronously in the client role.
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.
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 res The HTTP Upgrade response returned by the remote
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
response_type res;
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>
*/
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,
HandshakeHandler&& handler =
net::default_completion_token_t<
executor_type>{});
//--------------------------------------------------------------------------
//
// Handshaking (Server)
//
//--------------------------------------------------------------------------
/** Perform the WebSocket handshake in the server role.
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 received and the response is sent.
@li An error occurs.
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 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::read and then
pass the request to the appropriate overload of @ref accept or
@ref async_accept
@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>
*/
void
accept();
/** Read and respond to a WebSocket HTTP Upgrade request.
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 received and the response is sent.
@li An error occurs.
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 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::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.
@see
@li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
void
accept(error_code& ec);
/** Read and respond to a WebSocket HTTP Upgrade request.
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 received and the response is sent.
@li An error occurs.
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 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::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.
@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 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 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 received and the response is sent.
@li An error occurs.
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 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::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
void
#else
typename std::enable_if<! http::detail::is_header<
ConstBufferSequence>::value>::type
#endif
accept(
ConstBufferSequence const& buffers,
error_code& ec);
/** Respond to a WebSocket HTTP Upgrade request
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 is sent.
@li An error occurs.
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 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
accept(http::request<Body,
http::basic_fields<Allocator>> const& req);
/** Respond to a WebSocket HTTP Upgrade request
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 is sent.
@li An error occurs.
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 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
accept(http::request<Body,
http::basic_fields<Allocator>> const& req,
error_code& ec);
/** Perform the WebSocket handshake asynchronously in the server role.
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 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 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`.
@see
@li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<
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>{});
/** Perform the WebSocket handshake asynchronously in the server role.
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 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
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.
@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`.
@see
@li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
*/
template<
class ConstBufferSequence,
BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
net::default_completion_token_t<executor_type>
>
BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
async_accept(
ConstBufferSequence const& buffers,
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
);
/** Perform the WebSocket handshake asynchronously in the server role.
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 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.
@param req An object containing the HTTP Upgrade request.
Ownership is not transferred, the implementation will not access
this object from other threads.
@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`.
@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,
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,
AcceptHandler&& handler =
net::default_completion_token_t<
executor_type>{});
//--------------------------------------------------------------------------
//
// Close Frames
//
//--------------------------------------------------------------------------
/** Send a websocket close control frame.
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.
The call blocks until one of the following conditions is true:
@li The close frame is written.
@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.
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.
@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 control frame.
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.
The call blocks until one of the following conditions is true:
@li The close frame is written.
@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.
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.
@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);
/** Send a websocket close control frame asynchronously.
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.
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.
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.
@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`.
@see
@li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
*/
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 control frame.
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.
The call blocks until one of the following conditions is true:
@li The ping frame is written.
@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.
@throws system_error Thrown on failure.
*/
void
ping(ping_data const& payload);
/** Send a websocket ping control frame.
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.
The call blocks until one of the following conditions is true:
@li The ping frame is written.
@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.
@param ec Set to indicate what error occurred, if any.
*/
void
ping(ping_data const& payload, error_code& ec);
/** Send a websocket ping control frame asynchronously.
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 ping frame is written.
@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. 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 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 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`.
*/
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.
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.
The call blocks until one of the following conditions is true:
@li The pong frame is written.
@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.
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.
@throws system_error Thrown on failure.
*/
void
pong(ping_data const& payload);
/** Send a websocket pong control 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.
The call blocks until one of the following conditions is true:
@li The pong frame is written.
@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.
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.
@param ec Set to indicate what error occurred, if any.
*/
void
pong(ping_data const& payload, error_code& ec);
/** Send a websocket pong control frame asynchronously.
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 The pong frame is written.
@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. 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 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 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`.
*/
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>{});
//--------------------------------------------------------------------------
//
// Reading
//
//--------------------------------------------------------------------------
/** Read a complete message.
This function is used to read a complete message.
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.
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 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.
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 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 append message data to.
@throws system_error Thrown on failure.
*/
template<class DynamicBuffer>
std::size_t
read(DynamicBuffer& buffer);
/** Read a complete message.
This function is used to read a complete message.
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.
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 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.
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 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 append message data to.
@param ec Set to indicate what error occurred, if any.
*/
template<class DynamicBuffer>
std::size_t
read(DynamicBuffer& buffer, error_code& ec);
/** Read a complete message asynchronously.
This function is used to asynchronously read a complete message.
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.
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 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.
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.
@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
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
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 append message data to.
@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 appended to buffer
);
@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 DynamicBuffer,
BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
net::default_completion_token_t<
executor_type>>
BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
async_read(
DynamicBuffer& buffer,
ReadHandler&& handler =
net::default_completion_token_t<
executor_type>{});
//--------------------------------------------------------------------------
/** Read some message data.
This function is used to read some message data.
The call blocks until one of the following is true:
@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.
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 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.
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 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 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 on failure.
*/
template<class DynamicBuffer>
std::size_t
read_some(
DynamicBuffer& buffer,
std::size_t limit);
/** Read some message data.
This function is used to read some message data.
The call blocks until one of the following is true:
@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.
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 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.
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 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 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 ec Set to indicate what error occurred, if any.
*/
template<class DynamicBuffer>
std::size_t
read_some(
DynamicBuffer& buffer,
std::size_t limit,
error_code& ec);
/** Read some message data asynchronously.
This function is used to asynchronously read some message data.
This call always returns immediately. The asynchronous operation
will continue until one of the following conditions is true:
@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.
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 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.
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.
@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
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
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 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 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 appended to buffer
);
@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 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 =
net::default_completion_token_t<
executor_type>{});
//--------------------------------------------------------------------------
/** Read some message data.
This function is used to read some message data.
The call blocks until one of the following is true:
@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.
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 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.
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 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 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 on failure.
*/
template<class MutableBufferSequence>
std::size_t
read_some(
MutableBufferSequence const& buffers);
/** Read some message data.
This function is used to read some message data.
The call blocks until one of the following is true:
@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.
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 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.
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 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 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.
*/
template<class MutableBufferSequence>
std::size_t
read_some(
MutableBufferSequence const& buffers,
error_code& ec);
/** Read some message data asynchronously.
This function is used to asynchronously read some message data.
This call always returns immediately. The asynchronous operation
will continue until one of the following conditions is true:
@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.
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 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.
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.
@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
performed. In this case, when the function returns, the error
@ref error::closed will be indicated.
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 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 `net::post`.
*/
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 =
net::default_completion_token_t<
executor_type>{});
//--------------------------------------------------------------------------
//
// Writing
//
//--------------------------------------------------------------------------
/** Write a complete message.
This function is used to write a complete message.
The call blocks until one of the following is true:
@li The message is written.
@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.
The current setting of the @ref binary option controls
whether the message opcode is set to text or binary. If the
@ref auto_fragment option is set, the message will be split
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 message to send.
@return The number of bytes sent from the buffers.
@throws system_error Thrown on failure.
*/
template<class ConstBufferSequence>
std::size_t
write(ConstBufferSequence const& buffers);
/** Write a complete message.
This function is used to write a complete message.
The call blocks until one of the following is true:
@li The complete message is written.
@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.
The current setting of the @ref binary option controls
whether the message opcode is set to text or binary. If the
@ref auto_fragment option is set, the message will be split
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 message to send.
@param ec Set to indicate what error occurred, if any.
@return The number of bytes sent from the buffers.
*/
template<class ConstBufferSequence>
std::size_t
write(ConstBufferSequence const& buffers, error_code& ec);
/** Write a complete message asynchronously.
This function is used to asynchronously write a complete message.
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.
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
@ref auto_fragment option is set, the message will be split
into one or more frames as necessary. The actual payload contents
sent may be transformed as per the WebSocket protocol settings.
@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 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 sent from the
// buffers. If an error occurred,
// 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,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write(
ConstBufferSequence const& buffers,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type>{});
/** Write some message data.
This function is used to send part of a message.
The call blocks until one of the following is true:
@li The message data is written.
@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.
If this is the beginning of a new message, the message opcode
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 buffers containing the message part to send.
@return The number of bytes sent from the buffers.
@throws system_error Thrown on failure.
*/
template<class ConstBufferSequence>
std::size_t
write_some(bool fin, ConstBufferSequence const& buffers);
/** Write some message data.
This function is used to send part of a message.
The call blocks until one of the following is true:
@li The message data is written.
@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.
If this is the beginning of a new message, the message opcode
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 buffers containing the message part to send.
@param ec Set to indicate what error occurred, if any.
@return The number of bytes sent from the buffers.
@return The number of bytes consumed in the input buffers.
*/
template<class ConstBufferSequence>
std::size_t
write_some(bool fin,
ConstBufferSequence const& buffers, error_code& ec);
/** Write some message data asynchronously.
This function is used to asynchronously write part of a message.
This call always returns immediately. The asynchronous operation
will continue until one of the following conditions is true:
@li The message data is written.
@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. 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 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 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 sent from the
// buffers. If an error occurred,
// 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,
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>{});
//
// Deprecated
//
#if ! BOOST_BEAST_DOXYGEN
template<class RequestDecorator>
void
handshake_ex(
string_view host,
string_view target,
RequestDecorator const& decorator);
template<class RequestDecorator>
void
handshake_ex(
response_type& res,
string_view host,
string_view target,
RequestDecorator const& decorator);
template<class RequestDecorator>
void
handshake_ex(
string_view host,
string_view target,
RequestDecorator const& decorator,
error_code& ec);
template<class RequestDecorator>
void
handshake_ex(
response_type& res,
string_view host,
string_view target,
RequestDecorator const& decorator,
error_code& ec);
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 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 ResponseDecorator>
void
accept_ex(ResponseDecorator const& decorator);
template<class ResponseDecorator>
void
accept_ex(
ResponseDecorator const& decorator,
error_code& ec);
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 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
accept_ex(http::request<Body,
http::basic_fields<Allocator>> const& req,
ResponseDecorator const& decorator);
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);
template<
class ResponseDecorator,
class AcceptHandler>
BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
async_accept_ex(
ResponseDecorator const& decorator,
AcceptHandler&& handler);
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,
class ResponseDecorator,
class AcceptHandler>
BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
async_accept_ex(
http::request<Body,
http::basic_fields<Allocator>> const& req,
ResponseDecorator const& decorator,
AcceptHandler&& handler);
#endif
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;
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;
static void default_decorate_req(request_type&) {}
static void default_decorate_res(response_type&) {}
//
// accept / handshake
//
template<class Buffers, class Decorator>
void
do_accept(
Buffers const& buffers,
Decorator const& decorator,
error_code& ec);
template<
class Body, class Allocator,
class Decorator>
void
do_accept(
http::request<Body,
http::basic_fields<Allocator>> const& req,
Decorator const& decorator,
error_code& ec);
template<class RequestDecorator>
void
do_handshake(response_type* res_p,
string_view host, string_view target,
RequestDecorator const& decorator,
error_code& ec);
//
// fail
//
void
do_fail(
std::uint16_t code,
error_code ev,
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/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
Reference in New Issue View Git Blame Copy Permalink