EIC code displayed by LXR master/​include/​boost/​beast/​websocket/​stream.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 09:29:35

 //
 // 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::make_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)>;
 
 #ifndef BOOST_BEAST_DOXYGEN
     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;
 #endif
 
     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>;
 
     /// Rebinds the stream type to another executor.
     template<class Executor1>
     struct rebind_executor
     {
         /// The stream type when rebound to the specified executor.
         using other = stream<
                 typename next_layer_type::template rebind_executor<Executor1>::other,
                 deflateSupported>;
     };
 
     /** 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);
 
     /** Rebinding constructor
      *
      *  This constructor creates a the websocket stream from a
      *  websocket stream with a different executor.
      *
      *  @throw Any exception thrown by the NextLayer rebind constructor.
      *
      *  @param other The other websocket stream to construct from.
      */
     template<class Other>
     explicit
     stream(stream<Other> && other);
 
 
     //--------------------------------------------------------------------------
 
     /** 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
     /// Get the option value
     template<class Option>
     void
     get_option(Option& opt);
 
     /// Set the option value
     template<class Option>
     void
     set_option(Option opt);
 #else
     void set_option(decorator opt);
 #endif
 
     /** Set the timeout option
 
         @throws system_error on failure to reset the
         timer.
     */
     void
     set_option(timeout const& opt);
 
     /// Get the timeout option
     void
     get_option(timeout& opt);
 
     /** 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;
 
     /** Set the compress message write option.
 
         This controls whether or not outgoing messages should be
         compressed. The setting is only applied when
 
         @li The template parameter `deflateSupported` is true
         @li Compression is enable. This is controlled with `stream::set_option`
         @li Client and server have negotiated permessage-deflate settings
         @li The message is larger than `permessage_deflate::msg_size_threshold`
 
         This function permits adjusting per-message compression.
         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 compress messages whenever the conditions
         above are true.
 
         @param value `true` if outgoing messages should be compressed
 
         @par Example
         Disabling compression for a single message.
         @code
             ws.compress(false);
             ws.write(net::buffer(s), ec);
             ws.compress(true);
         @endcode
     */
     void
     compress(bool value);
 
     /// Returns `true` if the compress message write option is set.
     bool
     compress() 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. Note that the response object
         referenced by this parameter will be updated as long as the stream has
         received a valid HTTP response. If not (for example because of a communications
         error), the response contents will be undefined except for the result() which
         will bet set to 500, Internal Server Error.
 
         @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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
          @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         @note `terminal` cancellation will may close the underlying socket.
 
         @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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     template<
         BOOST_BEAST_ASYNC_TPARAM1 PingHandler =
             net::default_completion_token_t<executor_type>
     >
     BOOST_BEAST_ASYNC_RESULT1(PingHandler)
     async_ping(
         ping_data const& payload,
         PingHandler&& 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     template<
         BOOST_BEAST_ASYNC_TPARAM1 PongHandler =
             net::default_completion_token_t<executor_type>
     >
     BOOST_BEAST_ASYNC_RESULT1(PongHandler)
     async_pong(
         ping_data const& payload,
         PongHandler&& 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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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.
 
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
 
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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.
 
         This function always writes a complete WebSocket frame (not WebSocket
         message) upon successful completion, so it is well defined to perform
         ping, pong, and close operations after this operation completes.
 
         @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.
 
         This function always writes a complete WebSocket frame (not WebSocket
         message) upon successful completion, so it is well defined to perform
         ping, pong, and close operations in parallel to this operation.
 
         @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
         If the handler has an associated immediate executor,
         an immediate completion will be dispatched to it.
         Otherwise, the handler will not be invoked from within
         this function. Invocation of the handler will be performed
         by dispatching to the immediate executor. If no
         immediate executor is specified, this is equivalent
         to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
         net::cancellation_type values:
 
         @li @c net::cancellation_type::terminal
         @li @c net::cancellation_type::total
 
         `total` cancellation succeeds if the operation is suspended due to ongoing
         control operations such as a ping/pong.
         `terminal` cancellation succeeds when supported by the underlying stream.
 
         `terminal` cancellation leaves the stream in an undefined state,
         so that only closing it is guaranteed to succeed.
     */
     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>{});
 
 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

This page was automatically generated by the 2.3.7 LXR engine. The LXR team