2 // Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 // Official repository: https://github.com/boostorg/beast
10 #ifndef BOOST_BEAST_WEBSOCKET_STREAM_HPP
11 #define BOOST_BEAST_WEBSOCKET_STREAM_HPP
13 #include <boost/beast/core/detail/config.hpp>
14 #include <boost/beast/websocket/error.hpp>
15 #include <boost/beast/websocket/option.hpp>
16 #include <boost/beast/websocket/role.hpp>
17 #include <boost/beast/websocket/rfc6455.hpp>
18 #include <boost/beast/websocket/detail/frame.hpp>
19 #include <boost/beast/websocket/detail/hybi13.hpp>
20 #include <boost/beast/websocket/detail/mask.hpp>
21 #include <boost/beast/websocket/detail/pausation.hpp>
22 #include <boost/beast/websocket/detail/pmd_extension.hpp>
23 #include <boost/beast/websocket/detail/utf8_checker.hpp>
24 #include <boost/beast/core/static_buffer.hpp>
25 #include <boost/beast/core/string.hpp>
26 #include <boost/beast/core/detail/type_traits.hpp>
27 #include <boost/beast/http/empty_body.hpp>
28 #include <boost/beast/http/message.hpp>
29 #include <boost/beast/http/string_body.hpp>
30 #include <boost/beast/http/detail/type_traits.hpp>
31 #include <boost/beast/zlib/deflate_stream.hpp>
32 #include <boost/beast/zlib/inflate_stream.hpp>
33 #include <boost/asio/async_result.hpp>
34 #include <boost/asio/error.hpp>
39 #include <type_traits>
41 #include <boost/asio/io_context.hpp> // DEPRECATED
51 /// The type of object holding HTTP Upgrade requests
52 using request_type = http::request<http::empty_body>;
54 /// The type of object holding HTTP Upgrade responses
55 using response_type = http::response<http::string_body>;
57 /** The type of received control frame.
59 Values of this type are passed to the control frame
60 callback set using @ref stream::control_callback.
64 /// A close frame was received
67 /// A ping frame was received
70 /// A pong frame was received
74 //--------------------------------------------------------------------
76 /** Provides message-oriented functionality using WebSocket.
78 The @ref stream class template provides asynchronous and blocking
79 message-oriented functionality necessary for clients and servers
80 to utilize the WebSocket protocol.
82 For asynchronous operations, the application must ensure
83 that they are are all performed within the same implicit
87 @e Distinct @e objects: Safe.@n
88 @e Shared @e objects: Unsafe.
89 The application must also ensure that all asynchronous
90 operations are performed within the same implicit or explicit strand.
94 To use the @ref stream template with an `ip::tcp::socket`,
98 websocket::stream<ip::tcp::socket> ws{io_context};
100 Alternatively, you can write:
102 ip::tcp::socket sock{io_context};
103 websocket::stream<ip::tcp::socket&> ws{sock};
106 @tparam NextLayer The type representing the next layer, to which
107 data will be read and written during operations. For synchronous
108 operations, the type must support the @b SyncStream concept.
109 For asynchronous operations, the type must support the
110 @b AsyncStream concept.
112 @note A stream object must not be moved or destroyed while there
113 are pending asynchronous operations associated with it.
120 template<class NextLayer>
123 friend class close_test;
124 friend class frame_test;
125 friend class ping_test;
126 friend class read_test;
127 friend class stream_test;
128 friend class write_test;
130 /* The read buffer has to be at least as large
131 as the largest possible control frame including
134 static std::size_t constexpr max_control_frame_size = 2 + 8 + 4 + 125;
135 static std::size_t constexpr tcp_frame_size = 1536;
139 using control_cb_type =
140 std::function<void(frame_type, string_view)>;
142 // tokens are used to order reads and writes
145 unsigned char id_ = 0;
148 token(token const&) = default;
149 explicit token(unsigned char id) : id_(id) {}
150 operator bool() const { return id_ != 0; }
151 bool operator==(token const& t) { return id_ == t.id_; }
152 bool operator!=(token const& t) { return id_ != t.id_; }
153 token unique() { token t{id_++}; if(id_ == 0) ++id_; return t; }
154 void reset() { id_ = 0; }
157 // State information for the permessage-deflate extension
160 // `true` if current read message is compressed
163 zlib::deflate_stream zo;
164 zlib::inflate_stream zi;
175 NextLayer stream_; // the wrapped stream
176 close_reason cr_; // set from received close frame
177 control_cb_type ctrl_cb_; // control callback
179 std::size_t rd_msg_max_ // max message size
181 std::uint64_t rd_size_ // total size of current message so far
183 std::uint64_t rd_remain_ // message frame bytes left in current frame
185 detail::frame_header rd_fh_; // current frame header
186 detail::prepared_key rd_key_ // current stateful mask key
188 detail::frame_buffer rd_fb_; // to write control frames (during reads)
189 detail::utf8_checker rd_utf8_; // to validate utf8
191 +tcp_frame_size> rd_buf_; // buffer for reads
192 detail::opcode rd_op_ // current message binary or text
193 = detail::opcode::text;
194 bool rd_cont_ // `true` if the next frame is a continuation
196 bool rd_done_ // set when a message is done
198 bool rd_close_ // did we read a close frame?
200 token rd_block_; // op currenly reading
202 token tok_; // used to order asynchronous ops
203 role_type role_ // server or client
208 token wr_block_; // op currenly writing
209 bool wr_close_ // did we write a close frame?
211 bool wr_cont_ // next write is a continuation
213 bool wr_frag_ // autofrag the current message
215 bool wr_frag_opt_ // autofrag option setting
217 bool wr_compress_ // compress current message
219 detail::opcode wr_opcode_ // message type
220 = detail::opcode::text;
222 std::uint8_t[]> wr_buf_; // write buffer
223 std::size_t wr_buf_size_ // write buffer size (current message)
225 std::size_t wr_buf_opt_ // write buffer size option setting
227 detail::fh_buffer wr_fb_; // header buffer used for writes
228 detail::maskgen wr_gen_; // source of mask keys
230 detail::pausation paused_rd_; // paused read op
231 detail::pausation paused_wr_; // paused write op
232 detail::pausation paused_ping_; // paused ping op
233 detail::pausation paused_close_; // paused close op
234 detail::pausation paused_r_rd_; // paused read op (read)
235 detail::pausation paused_r_close_;// paused close op (read)
237 std::unique_ptr<pmd_t> pmd_; // pmd settings or nullptr
238 permessage_deflate pmd_opts_; // local pmd options
239 detail::pmd_offer pmd_config_; // offer (client) or negotiation (server)
242 /// The type of the next layer.
243 using next_layer_type =
244 typename std::remove_reference<NextLayer>::type;
246 /// The type of the lowest layer.
247 using lowest_layer_type =
248 typename get_lowest_layer<next_layer_type>::type;
250 /// The type of the executor associated with the object.
251 using executor_type = typename next_layer_type::executor_type;
255 Destroys the stream and all associated resources.
257 @note A stream object must not be destroyed while there
258 are pending asynchronous operations associated with it.
264 If `NextLayer` is move constructible, this function
265 will move-construct a new stream from the existing stream.
267 @note The behavior of move assignment on or from streams
268 with active or pending operations is undefined.
270 stream(stream&&) = default;
274 If `NextLayer` is move assignable, this function
275 will move-assign a new stream from the existing stream.
277 @note The behavior of move assignment on or from streams
278 with active or pending operations is undefined.
280 stream& operator=(stream&&) = default;
284 This constructor creates a websocket stream and initializes
285 the next layer object.
287 @throws Any exceptions thrown by the NextLayer constructor.
289 @param args The arguments to be passed to initialize the
290 next layer object. The arguments are forwarded to the next
293 template<class... Args>
295 stream(Args&&... args);
297 //--------------------------------------------------------------------------
299 /** Get the executor associated with the object.
301 This function may be used to obtain the executor object that the
302 stream uses to dispatch handlers for asynchronous operations.
304 @return A copy of the executor that stream will use to dispatch handlers.
307 get_executor() noexcept
309 return stream_.get_executor();
312 /** Get a reference to the next layer
314 This function returns a reference to the next layer
315 in a stack of stream layers.
317 @return A reference to the next layer in the stack of
326 /** Get a reference to the next layer
328 This function returns a reference to the next layer in a
329 stack of stream layers.
331 @return A reference to the next layer in the stack of
334 next_layer_type const&
340 /** Get a reference to the lowest layer
342 This function returns a reference to the lowest layer
343 in a stack of stream layers.
345 @return A reference to the lowest layer in the stack of
351 return stream_.lowest_layer();
354 /** Get a reference to the lowest layer
356 This function returns a reference to the lowest layer
357 in a stack of stream layers.
359 @return A reference to the lowest layer in the stack of
360 stream layers. Ownership is not transferred to the caller.
362 lowest_layer_type const&
365 return stream_.lowest_layer();
368 //--------------------------------------------------------------------------
372 //--------------------------------------------------------------------------
374 /** Returns `true` if the stream is open.
376 The stream is open after a successful handshake, and when
377 no error has occurred.
382 return status_ == status::open;
385 /** Returns `true` if the latest message data indicates binary.
387 This function informs the caller of whether the last
388 received message frame represents a message with the
391 If there is no last message frame, the return value is
397 return rd_op_ == detail::opcode::binary;
400 /** Returns `true` if the latest message data indicates text.
402 This function informs the caller of whether the last
403 received message frame represents a message with the
406 If there is no last message frame, the return value is
412 return ! got_binary();
415 /// Returns `true` if the last completed read finished the current message.
417 is_message_done() const
422 /** Returns the close reason received from the peer.
424 This is only valid after a read completes with error::closed.
432 /** Returns a suggested maximum buffer size for the next call to read.
434 This function returns a reasonable upper limit on the number
435 of bytes for the size of the buffer passed in the next call
436 to read. The number is determined by the state of the current
437 frame and whether or not the permessage-deflate extension is
440 @param initial_size A non-zero size representing the caller's
441 desired buffer size for when there is no information which may
442 be used to calculate a more specific value. For example, when
443 reading the first frame header of a message.
447 std::size_t initial_size = +tcp_frame_size) const;
449 /** Returns a suggested maximum buffer size for the next call to read.
451 This function returns a reasonable upper limit on the number
452 of bytes for the size of the buffer passed in the next call
453 to read. The number is determined by the state of the current
454 frame and whether or not the permessage-deflate extension is
457 @param buffer The buffer which will be used for reading. The
458 implementation will query the buffer to obtain the optimum
459 size of a subsequent call to `buffer.prepare` based on the
460 state of the current frame, if any.
462 template<class DynamicBuffer
463 #if ! BOOST_BEAST_DOXYGEN
464 , class = typename std::enable_if<
465 ! std::is_integral<DynamicBuffer>::value>::type
470 DynamicBuffer& buffer) const;
472 //--------------------------------------------------------------------------
476 //--------------------------------------------------------------------------
478 /// Set the permessage-deflate extension options
480 set_option(permessage_deflate const& o);
482 /// Get the permessage-deflate extension options
484 get_option(permessage_deflate& o)
489 /** Set the automatic fragmentation option.
491 Determines if outgoing message payloads are broken up into
494 When the automatic fragmentation size is turned on, outgoing
495 message payloads are broken up into multiple frames no larger
496 than the write buffer size.
498 The default setting is to fragment messages.
500 @param value A `bool` indicating if auto fragmentation should be on.
503 Setting the automatic fragmentation option:
505 ws.auto_fragment(true);
509 auto_fragment(bool value)
511 wr_frag_opt_ = value;
514 /// Returns `true` if the automatic fragmentation option is set.
516 auto_fragment() const
521 /** Set the binary message option.
523 This controls whether or not outgoing message opcodes
524 are set to binary or text. The setting is only applied
525 at the start when a caller begins a new message. Changing
526 the opcode after a message is started will only take effect
527 after the current message being sent is complete.
529 The default setting is to send text messages.
531 @param value `true` if outgoing messages should indicate
532 binary, or `false` if they should indicate text.
535 Setting the message type to binary.
544 detail::opcode::binary :
545 detail::opcode::text;
548 /// Returns `true` if the binary message option is set.
552 return wr_opcode_ == detail::opcode::binary;
555 /** Set a callback to be invoked on each incoming control frame.
557 Sets the callback to be invoked whenever a ping, pong,
558 or close control frame is received during a call to one
559 of the following functions:
561 @li @ref beast::websocket::stream::read
562 @li @ref beast::websocket::stream::read_some
563 @li @ref beast::websocket::stream::async_read
564 @li @ref beast::websocket::stream::async_read_some
566 Unlike completion handlers, the callback will be invoked
567 for each control frame during a call to any synchronous
568 or asynchronous read function. The operation is passive,
569 with no associated error code, and triggered by reads.
571 For close frames, the close reason code may be obtained by
572 calling the function @ref reason.
574 @param cb The function object to call, which must be
575 invocable with this equivalent signature:
579 frame_type kind, // The type of frame
580 string_view payload // The payload in the frame
583 The implementation type-erases the callback without requiring
584 a dynamic allocation. For this reason, the callback object is
585 passed by a non-constant reference.
586 If the read operation which receives the control frame is
587 an asynchronous operation, the callback will be invoked using
588 the same method as that used to invoke the final handler.
590 @note It is not necessary to send a close frame upon receipt
591 of a close frame. The implementation does this automatically.
592 Attempting to send a close frame after a close frame is
593 received will result in undefined behavior.
595 template<class Callback>
597 control_callback(Callback& cb)
599 // Callback may not be constant, caller is responsible for
600 // managing the lifetime of the callback. Copies are not made.
601 BOOST_STATIC_ASSERT(! std::is_const<Callback>::value);
603 ctrl_cb_ = std::ref(cb);
606 /** Reset the control frame callback.
608 This function removes any previously set control frame callback.
616 /** Set the maximum incoming message size option.
618 Sets the largest permissible incoming message size. Message
619 frame fields indicating a size that would bring the total
620 message size over this limit will cause a protocol failure.
622 The default setting is 16 megabytes. A value of zero indicates
623 a limit of the maximum value of a `std::uint64_t`.
626 Setting the maximum read message size.
628 ws.read_message_max(65536);
631 @param amount The limit on the size of incoming messages.
634 read_message_max(std::size_t amount)
636 rd_msg_max_ = amount;
639 /// Returns the maximum incoming message size setting.
641 read_message_max() const
646 /** Set the write buffer size option.
648 Sets the size of the write buffer used by the implementation to
649 send frames. The write buffer is needed when masking payload data
650 in the client role, compressing frames, or auto-fragmenting message
653 Lowering the size of the buffer can decrease the memory requirements
654 for each connection, while increasing the size of the buffer can reduce
655 the number of calls made to the next layer to write data.
657 The default setting is 4096. The minimum value is 8.
659 The write buffer size can only be changed when the stream is not
660 open. Undefined behavior results if the option is modified after a
661 successful WebSocket handshake.
664 Setting the write buffer size.
666 ws.write_buffer_size(8192);
669 @param amount The size of the write buffer in bytes.
672 write_buffer_size(std::size_t amount)
675 BOOST_THROW_EXCEPTION(std::invalid_argument{
676 "write buffer size underflow"});
677 wr_buf_opt_ = amount;
680 /// Returns the size of the write buffer.
682 write_buffer_size() const
687 /** Set the text message option.
689 This controls whether or not outgoing message opcodes
690 are set to binary or text. The setting is only applied
691 at the start when a caller begins a new message. Changing
692 the opcode after a message is started will only take effect
693 after the current message being sent is complete.
695 The default setting is to send text messages.
697 @param value `true` if outgoing messages should indicate
698 text, or `false` if they should indicate binary.
701 Setting the message type to text.
710 detail::opcode::text :
711 detail::opcode::binary;
714 /// Returns `true` if the text message option is set.
718 return wr_opcode_ == detail::opcode::text;
721 //--------------------------------------------------------------------------
723 // Handshaking (Client)
725 //--------------------------------------------------------------------------
727 /** Send an HTTP WebSocket Upgrade request and receive the response.
729 This function is used to synchronously send the WebSocket
730 upgrade HTTP request. The call blocks until one of the
731 following conditions is true:
733 @li The request is sent and the response is received.
735 @li An error occurs on the stream
737 This function is implemented in terms of one or more calls to the
738 next layer's `read_some` and `write_some` functions.
740 The operation is successful if the received HTTP response indicates
741 a successful HTTP Upgrade (represented by a Status-Code of 101,
742 "switching protocols").
744 @param host The name of the remote host,
745 required by the HTTP protocol.
747 @param target The Request Target, which may not be empty,
748 required by the HTTP protocol.
750 @throws system_error Thrown on failure.
754 websocket::stream<ip::tcp::socket> ws{io_context};
758 ws.handshake("localhost", "/");
762 // An error occurred.
771 /** Send an HTTP WebSocket Upgrade request and receive the response.
773 This function is used to synchronously send the WebSocket
774 upgrade HTTP request. The call blocks until one of the
775 following conditions is true:
777 @li The request is sent and the response is received.
779 @li An error occurs on the stream
781 This function is implemented in terms of one or more calls to the
782 next layer's `read_some` and `write_some` functions.
784 The operation is successful if the received HTTP response indicates
785 a successful HTTP Upgrade (represented by a Status-Code of 101,
786 "switching protocols").
788 @param res The HTTP Upgrade response returned by the remote
791 @param host The name of the remote host,
792 required by the HTTP protocol.
794 @param target The Request Target, which may not be empty,
795 required by the HTTP protocol.
797 @throws system_error Thrown on failure.
801 websocket::stream<ip::tcp::socket> ws{io_context};
806 ws.handshake(res, "localhost", "/");
810 // An error occurred.
820 /** Send an HTTP WebSocket Upgrade request and receive the response.
822 This function is used to synchronously send the WebSocket
823 upgrade HTTP request. The call blocks until one of the
824 following conditions is true:
826 @li The request is sent and the response is received.
828 @li An error occurs on the stream
830 This function is implemented in terms of one or more calls to the
831 next layer's `read_some` and `write_some` functions.
833 The operation is successful if the received HTTP response indicates
834 a successful HTTP Upgrade (represented by a Status-Code of 101,
835 "switching protocols").
837 @param host The name of the remote host,
838 required by the HTTP protocol.
840 @param target The Request Target, which may not be empty,
841 required by the HTTP protocol.
843 @param decorator A function object which will be called to modify
844 the HTTP request object generated by the implementation. This
845 could be used to set the User-Agent field, subprotocols, or other
846 application or HTTP specific fields. The object will be called
847 with this equivalent signature:
848 @code void decorator(
852 @throws system_error Thrown on failure.
856 websocket::stream<ip::tcp::socket> ws{io_context};
860 ws.handshake("localhost", "/",
861 [](request_type& req)
863 req.set(field::user_agent, "Beast");
868 // An error occurred.
872 template<class RequestDecorator>
877 RequestDecorator const& decorator);
879 /** Send an HTTP WebSocket Upgrade request and receive the response.
881 This function is used to synchronously send the WebSocket
882 upgrade HTTP request. The call blocks until one of the
883 following conditions is true:
885 @li The request is sent and the response is received.
887 @li An error occurs on the stream
889 This function is implemented in terms of one or more calls to the
890 next layer's `read_some` and `write_some` functions.
892 The operation is successful if the received HTTP response indicates
893 a successful HTTP Upgrade (represented by a Status-Code of 101,
894 "switching protocols").
896 @param res The HTTP Upgrade response returned by the remote
899 @param host The name of the remote host,
900 required by the HTTP protocol.
902 @param target The Request Target, which may not be empty,
903 required by the HTTP protocol.
905 @param decorator A function object which will be called to modify
906 the HTTP request object generated by the implementation. This
907 could be used to set the User-Agent field, subprotocols, or other
908 application or HTTP specific fields. The object will be called
909 with this equivalent signature:
910 @code void decorator(
914 @throws system_error Thrown on failure.
918 websocket::stream<ip::tcp::socket> ws{io_context};
923 ws.handshake(res, "localhost", "/",
924 [](request_type& req)
926 req.set(field::user_agent, "Beast");
931 // An error occurred.
935 template<class RequestDecorator>
941 RequestDecorator const& decorator);
943 /** Send an HTTP WebSocket Upgrade request and receive the response.
945 This function is used to synchronously send the WebSocket
946 upgrade HTTP request. The call blocks until one of the
947 following conditions is true:
949 @li The request is sent and the response is received.
951 @li An error occurs on the stream
953 This function is implemented in terms of one or more calls to the
954 next layer's `read_some` and `write_some` functions.
956 The operation is successful if the received HTTP response indicates
957 a successful HTTP Upgrade (represented by a Status-Code of 101,
958 "switching protocols").
960 @param host The name of the remote host,
961 required by the HTTP protocol.
963 @param target The Request Target, which may not be empty,
964 required by the HTTP protocol.
966 @param ec Set to indicate what error occurred, if any.
970 websocket::stream<ip::tcp::socket> ws{io_context};
973 ws.handshake(host, target, ec);
976 // An error occurred.
986 /** Send an HTTP WebSocket Upgrade request and receive the response.
988 This function is used to synchronously send the WebSocket
989 upgrade HTTP request. The call blocks until one of the
990 following conditions is true:
992 @li The request is sent and the response is received.
994 @li An error occurs on the stream
996 This function is implemented in terms of one or more calls to the
997 next layer's `read_some` and `write_some` functions.
999 The operation is successful if the received HTTP response indicates
1000 a successful HTTP Upgrade (represented by a Status-Code of 101,
1001 "switching protocols").
1003 @param res The HTTP Upgrade response returned by the remote
1004 endpoint. If `ec` is set, the returned value is undefined.
1006 @param host The name of the remote host,
1007 required by the HTTP protocol.
1009 @param target The Request Target, which may not be empty,
1010 required by the HTTP protocol.
1012 @param ec Set to indicate what error occurred, if any.
1016 websocket::stream<ip::tcp::socket> ws{io_context};
1020 ws.handshake(res, host, target, ec);
1023 // An error occurred.
1034 /** Send an HTTP WebSocket Upgrade request and receive the response.
1036 This function is used to synchronously send the WebSocket
1037 upgrade HTTP request. The call blocks until one of the
1038 following conditions is true:
1040 @li The request is sent and the response is received.
1042 @li An error occurs on the stream
1044 This function is implemented in terms of one or more calls to the
1045 next layer's `read_some` and `write_some` functions.
1047 The operation is successful if the received HTTP response indicates
1048 a successful HTTP Upgrade (represented by a Status-Code of 101,
1049 "switching protocols").
1051 @param host The name of the remote host,
1052 required by the HTTP protocol.
1054 @param target The Request Target, which may not be empty,
1055 required by the HTTP protocol.
1057 @param decorator A function object which will be called to modify
1058 the HTTP request object generated by the implementation. This
1059 could be used to set the User-Agent field, subprotocols, or other
1060 application or HTTP specific fields. The object will be called
1061 with this equivalent signature:
1062 @code void decorator(
1066 @param ec Set to indicate what error occurred, if any.
1070 websocket::stream<ip::tcp::socket> ws{io_context};
1073 ws.handshake("localhost", "/",
1074 [](request_type& req)
1076 req.set(field::user_agent, "Beast");
1081 // An error occurred.
1085 template<class RequestDecorator>
1090 RequestDecorator const& decorator,
1093 /** Send an HTTP WebSocket Upgrade request and receive the response.
1095 This function is used to synchronously send the WebSocket
1096 upgrade HTTP request. The call blocks until one of the
1097 following conditions is true:
1099 @li The request is sent and the response is received.
1101 @li An error occurs on the stream
1103 This function is implemented in terms of one or more calls to the
1104 next layer's `read_some` and `write_some` functions.
1106 The operation is successful if the received HTTP response indicates
1107 a successful HTTP Upgrade (represented by a Status-Code of 101,
1108 "switching protocols").
1110 @param res The HTTP Upgrade response returned by the remote
1113 @param host The name of the remote host,
1114 required by the HTTP protocol.
1116 @param target The Request Target, which may not be empty,
1117 required by the HTTP protocol.
1119 @param decorator A function object which will be called to modify
1120 the HTTP request object generated by the implementation. This
1121 could be used to set the User-Agent field, subprotocols, or other
1122 application or HTTP specific fields. The object will be called
1123 with this equivalent signature:
1124 @code void decorator(
1128 @param ec Set to indicate what error occurred, if any.
1132 websocket::stream<ip::tcp::socket> ws{io_context};
1136 ws.handshake(res, "localhost", "/",
1137 [](request_type& req)
1139 req.set(field::user_agent, "Beast");
1144 // An error occurred.
1148 template<class RequestDecorator>
1154 RequestDecorator const& decorator,
1157 /** Start an asynchronous operation to send an upgrade request and receive the response.
1159 This function is used to asynchronously send the HTTP WebSocket
1160 upgrade request and receive the HTTP WebSocket Upgrade response.
1161 This function call always returns immediately. The asynchronous
1162 operation will continue until one of the following conditions is
1165 @li The request is sent and the response is received.
1167 @li An error occurs on the stream
1169 This operation is implemented in terms of one or more calls to the
1170 next layer's `async_read_some` and `async_write_some` functions, and
1171 is known as a <em>composed operation</em>. The program must ensure
1172 that the stream performs no other operations until this operation
1175 The operation is successful if the received HTTP response indicates
1176 a successful HTTP Upgrade (represented by a Status-Code of 101,
1177 "switching protocols").
1179 @param host The name of the remote host, required by
1180 the HTTP protocol. Copies may be made as needed.
1182 @param target The Request Target, which may not be empty,
1183 required by the HTTP protocol. Copies of this parameter may
1186 @param handler The handler to be called when the request completes.
1187 Copies will be made of the handler as required. The equivalent
1188 function signature of the handler must be:
1190 error_code const& ec // Result of operation
1192 Regardless of whether the asynchronous operation completes
1193 immediately or not, the handler will not be invoked from within
1194 this function. Invocation of the handler will be performed in a
1195 manner equivalent to using `boost::asio::io_context::post`.
1197 template<class HandshakeHandler>
1198 BOOST_ASIO_INITFN_RESULT_TYPE(
1199 HandshakeHandler, void(error_code))
1203 HandshakeHandler&& handler);
1205 /** Start an asynchronous operation to send an upgrade request and receive the response.
1207 This function is used to asynchronously send the HTTP WebSocket
1208 upgrade request and receive the HTTP WebSocket Upgrade response.
1209 This function call always returns immediately. The asynchronous
1210 operation will continue until one of the following conditions is
1213 @li The request is sent and the response is received.
1215 @li An error occurs on the stream
1217 This operation is implemented in terms of one or more calls to the
1218 next layer's `async_read_some` and `async_write_some` functions, and
1219 is known as a <em>composed operation</em>. The program must ensure
1220 that the stream performs no other operations until this operation
1223 The operation is successful if the received HTTP response indicates
1224 a successful HTTP Upgrade (represented by a Status-Code of 101,
1225 "switching protocols").
1227 @param res The HTTP Upgrade response returned by the remote
1228 endpoint. The caller must ensure this object is valid for at
1229 least until the completion handler is invoked.
1231 @param host The name of the remote host, required by
1232 the HTTP protocol. Copies may be made as needed.
1234 @param target The Request Target, which may not be empty,
1235 required by the HTTP protocol. Copies of this parameter may
1238 @param handler The handler to be called when the request completes.
1239 Copies will be made of the handler as required. The equivalent
1240 function signature of the handler must be:
1242 error_code const& ec // Result of operation
1244 Regardless of whether the asynchronous operation completes
1245 immediately or not, the handler will not be invoked from within
1246 this function. Invocation of the handler will be performed in a
1247 manner equivalent to using `boost::asio::io_context::post`.
1249 template<class HandshakeHandler>
1250 BOOST_ASIO_INITFN_RESULT_TYPE(
1251 HandshakeHandler, void(error_code))
1256 HandshakeHandler&& handler);
1258 /** Start an asynchronous operation to send an upgrade request and receive the response.
1260 This function is used to asynchronously send the HTTP WebSocket
1261 upgrade request and receive the HTTP WebSocket Upgrade response.
1262 This function call always returns immediately. The asynchronous
1263 operation will continue until one of the following conditions is
1266 @li The request is sent and the response is received.
1268 @li An error occurs on the stream
1270 This operation is implemented in terms of one or more calls to the
1271 next layer's `async_read_some` and `async_write_some` functions, and
1272 is known as a <em>composed operation</em>. The program must ensure
1273 that the stream performs no other operations until this operation
1276 The operation is successful if the received HTTP response indicates
1277 a successful HTTP Upgrade (represented by a Status-Code of 101,
1278 "switching protocols").
1280 @param host The name of the remote host, required by
1281 the HTTP protocol. Copies may be made as needed.
1283 @param target The Request Target, which may not be empty,
1284 required by the HTTP protocol. Copies of this parameter may
1287 @param decorator A function object which will be called to modify
1288 the HTTP request object generated by the implementation. This
1289 could be used to set the User-Agent field, subprotocols, or other
1290 application or HTTP specific fields. The object will be called
1291 with this equivalent signature:
1292 @code void decorator(
1296 @param handler The handler to be called when the request completes.
1297 Copies will be made of the handler as required. The equivalent
1298 function signature of the handler must be:
1300 error_code const& ec // Result of operation
1302 Regardless of whether the asynchronous operation completes
1303 immediately or not, the handler will not be invoked from within
1304 this function. Invocation of the handler will be performed in a
1305 manner equivalent to using `boost::asio::io_context::post`.
1307 template<class RequestDecorator, class HandshakeHandler>
1308 BOOST_ASIO_INITFN_RESULT_TYPE(
1309 HandshakeHandler, void(error_code))
1313 RequestDecorator const& decorator,
1314 HandshakeHandler&& handler);
1316 /** Start an asynchronous operation to send an upgrade request and receive the response.
1318 This function is used to asynchronously send the HTTP WebSocket
1319 upgrade request and receive the HTTP WebSocket Upgrade response.
1320 This function call always returns immediately. The asynchronous
1321 operation will continue until one of the following conditions is
1324 @li The request is sent and the response is received.
1326 @li An error occurs on the stream
1328 This operation is implemented in terms of one or more calls to the
1329 next layer's `async_read_some` and `async_write_some` functions, and
1330 is known as a <em>composed operation</em>. The program must ensure
1331 that the stream performs no other operations until this operation
1334 The operation is successful if the received HTTP response indicates
1335 a successful HTTP Upgrade (represented by a Status-Code of 101,
1336 "switching protocols").
1338 @param res The HTTP Upgrade response returned by the remote
1339 endpoint. The caller must ensure this object is valid for at
1340 least until the completion handler is invoked.
1342 @param host The name of the remote host, required by
1343 the HTTP protocol. Copies may be made as needed.
1345 @param target The Request Target, which may not be empty,
1346 required by the HTTP protocol. Copies of this parameter may
1349 @param decorator A function object which will be called to modify
1350 the HTTP request object generated by the implementation. This
1351 could be used to set the User-Agent field, subprotocols, or other
1352 application or HTTP specific fields. The object will be called
1353 with this equivalent signature:
1354 @code void decorator(
1358 @param handler The handler to be called when the request completes.
1359 Copies will be made of the handler as required. The equivalent
1360 function signature of the handler must be:
1362 error_code const& ec // Result of operation
1364 Regardless of whether the asynchronous operation completes
1365 immediately or not, the handler will not be invoked from within
1366 this function. Invocation of the handler will be performed in a
1367 manner equivalent to using `boost::asio::io_context::post`.
1369 template<class RequestDecorator, class HandshakeHandler>
1370 BOOST_ASIO_INITFN_RESULT_TYPE(
1371 HandshakeHandler, void(error_code))
1376 RequestDecorator const& decorator,
1377 HandshakeHandler&& handler);
1379 //--------------------------------------------------------------------------
1381 // Handshaking (Server)
1383 //--------------------------------------------------------------------------
1385 /** Read and respond to a WebSocket HTTP Upgrade request.
1387 This function is used to synchronously read an HTTP WebSocket
1388 Upgrade request and send the HTTP response. The call blocks
1389 until one of the following conditions is true:
1391 @li The request is received and the response finishes sending.
1393 @li An error occurs on the stream.
1395 This function is implemented in terms of one or more calls to
1396 the next layer's `read_some` and `write_some` functions.
1398 If the stream receives a valid HTTP WebSocket Upgrade request,
1399 an HTTP response is sent back indicating a successful upgrade.
1400 When this call returns, the stream is then ready to send and
1401 receive WebSocket protocol frames and messages.
1402 If the HTTP Upgrade request is invalid or cannot be satisfied,
1403 an HTTP response is sent indicating the reason and status code
1404 (typically 400, "Bad Request"). This counts as a failure.
1406 The implementation uses fixed size internal storage to
1407 receive the request. If the request is too large, the error
1408 @ref error::buffer_overflow will be indicated. Applications
1409 that wish to receive larger requests should first read the
1410 request using their own buffer and a suitable overload of
1411 @ref http::read or @ref http::async_read, then call @ref accept
1412 or @ref async_accept with the request.
1414 @throws system_error Thrown on failure.
1419 /** Read and respond to a WebSocket HTTP Upgrade request.
1421 This function is used to synchronously read an HTTP WebSocket
1422 Upgrade request and send the HTTP response. The call blocks
1423 until one of the following conditions is true:
1425 @li The request is received and the response finishes sending.
1427 @li An error occurs on the stream.
1429 This function is implemented in terms of one or more calls to
1430 the next layer's `read_some` and `write_some` functions.
1432 If the stream receives a valid HTTP WebSocket Upgrade request,
1433 an HTTP response is sent back indicating a successful upgrade.
1434 When this call returns, the stream is then ready to send and
1435 receive WebSocket protocol frames and messages.
1436 If the HTTP Upgrade request is invalid or cannot be satisfied,
1437 an HTTP response is sent indicating the reason and status code
1438 (typically 400, "Bad Request"). This counts as a failure.
1440 The implementation uses fixed size internal storage to
1441 receive the request. If the request is too large, the error
1442 @ref error::buffer_overflow will be indicated. Applications
1443 that wish to receive larger requests should first read the
1444 request using their own buffer and a suitable overload of
1445 @ref http::read or @ref http::async_read, then call @ref accept
1446 or @ref async_accept with the request.
1448 @param decorator A function object which will be called to modify
1449 the HTTP response object delivered by the implementation. This
1450 could be used to set the Server field, subprotocols, or other
1451 application or HTTP specific fields. The object will be called
1452 with this equivalent signature:
1453 @code void decorator(
1457 @throws system_error Thrown on failure.
1459 template<class ResponseDecorator>
1461 accept_ex(ResponseDecorator const& decorator);
1463 /** Read and respond to a WebSocket HTTP Upgrade request.
1465 This function is used to synchronously read an HTTP WebSocket
1466 Upgrade request and send the HTTP response. The call blocks
1467 until one of the following conditions is true:
1469 @li The request is received and the response finishes sending.
1471 @li An error occurs on the stream.
1473 This function is implemented in terms of one or more calls to
1474 the next layer's `read_some` and `write_some` functions.
1476 If the stream receives a valid HTTP WebSocket Upgrade request,
1477 an HTTP response is sent back indicating a successful upgrade.
1478 When this call returns, the stream is then ready to send and
1479 receive WebSocket protocol frames and messages.
1480 If the HTTP Upgrade request is invalid or cannot be satisfied,
1481 an HTTP response is sent indicating the reason and status code
1482 (typically 400, "Bad Request"). This counts as a failure.
1484 The implementation uses fixed size internal storage to
1485 receive the request. If the request is too large, the error
1486 @ref error::buffer_overflow will be indicated. Applications
1487 that wish to receive larger requests should first read the
1488 request using their own buffer and a suitable overload of
1489 @ref http::read or @ref http::async_read, then call @ref accept
1490 or @ref async_accept with the request.
1492 @param ec Set to indicate what error occurred, if any.
1495 accept(error_code& ec);
1497 /** Read and respond to a WebSocket HTTP Upgrade request.
1499 This function is used to synchronously read an HTTP WebSocket
1500 Upgrade request and send the HTTP response. The call blocks
1501 until one of the following conditions is true:
1503 @li The request is received and the response finishes sending.
1505 @li An error occurs on the stream.
1507 This function is implemented in terms of one or more calls to
1508 the next layer's `read_some` and `write_some` functions.
1510 If the stream receives a valid HTTP WebSocket Upgrade request,
1511 an HTTP response is sent back indicating a successful upgrade.
1512 When this call returns, the stream is then ready to send and
1513 receive WebSocket protocol frames and messages.
1514 If the HTTP Upgrade request is invalid or cannot be satisfied,
1515 an HTTP response is sent indicating the reason and status code
1516 (typically 400, "Bad Request"). This counts as a failure.
1518 The implementation uses fixed size internal storage to
1519 receive the request. If the request is too large, the error
1520 @ref error::buffer_overflow will be indicated. Applications
1521 that wish to receive larger requests should first read the
1522 request using their own buffer and a suitable overload of
1523 @ref http::read or @ref http::async_read, then call @ref accept
1524 or @ref async_accept with the request.
1526 @param decorator A function object which will be called to modify
1527 the HTTP response object delivered by the implementation. This
1528 could be used to set the Server field, subprotocols, or other
1529 application or HTTP specific fields. The object will be called
1530 with this equivalent signature:
1531 @code void decorator(
1535 @param ec Set to indicate what error occurred, if any.
1537 template<class ResponseDecorator>
1540 ResponseDecorator const& decorator,
1543 /** Read and respond to a WebSocket HTTP Upgrade request.
1545 This function is used to synchronously read an HTTP WebSocket
1546 Upgrade request and send the HTTP response. The call blocks
1547 until one of the following conditions is true:
1549 @li The request is received and the response finishes sending.
1551 @li An error occurs on the stream.
1553 This function is implemented in terms of one or more calls to
1554 the next layer's `read_some` and `write_some` functions.
1556 If the stream receives a valid HTTP WebSocket Upgrade request,
1557 an HTTP response is sent back indicating a successful upgrade.
1558 When this call returns, the stream is then ready to send and
1559 receive WebSocket protocol frames and messages.
1560 If the HTTP Upgrade request is invalid or cannot be satisfied,
1561 an HTTP response is sent indicating the reason and status code
1562 (typically 400, "Bad Request"). This counts as a failure.
1564 The implementation uses fixed size internal storage to
1565 receive the request. If the request is too large, the error
1566 @ref error::buffer_overflow will be indicated. Applications
1567 that wish to receive larger requests should first read the
1568 request using their own buffer and a suitable overload of
1569 @ref http::read or @ref http::async_read, then call @ref accept
1570 or @ref async_accept with the request.
1572 @param buffers Caller provided data that has already been
1573 received on the stream. The implementation will copy the
1574 caller provided data before the function returns.
1576 @throws system_error Thrown on failure.
1578 template<class ConstBufferSequence>
1579 #if BOOST_BEAST_DOXYGEN
1582 typename std::enable_if<! http::detail::is_header<
1583 ConstBufferSequence>::value>::type
1585 accept(ConstBufferSequence const& buffers);
1587 /** Read and respond to a WebSocket HTTP Upgrade request.
1589 This function is used to synchronously read an HTTP WebSocket
1590 Upgrade request and send the HTTP response. The call blocks
1591 until one of the following conditions is true:
1593 @li The request is received and the response finishes sending.
1595 @li An error occurs on the stream.
1597 This function is implemented in terms of one or more calls to
1598 the next layer's `read_some` and `write_some` functions.
1600 If the stream receives a valid HTTP WebSocket Upgrade request,
1601 an HTTP response is sent back indicating a successful upgrade.
1602 When this call returns, the stream is then ready to send and
1603 receive WebSocket protocol frames and messages.
1604 If the HTTP Upgrade request is invalid or cannot be satisfied,
1605 an HTTP response is sent indicating the reason and status code
1606 (typically 400, "Bad Request"). This counts as a failure.
1608 The implementation uses fixed size internal storage to
1609 receive the request. If the request is too large, the error
1610 @ref error::buffer_overflow will be indicated. Applications
1611 that wish to receive larger requests should first read the
1612 request using their own buffer and a suitable overload of
1613 @ref http::read or @ref http::async_read, then call @ref accept
1614 or @ref async_accept with the request.
1616 @param buffers Caller provided data that has already been
1617 received on the stream. The implementation will copy the
1618 caller provided data before the function returns.
1620 @param decorator A function object which will be called to modify
1621 the HTTP response object delivered by the implementation. This
1622 could be used to set the Server field, subprotocols, or other
1623 application or HTTP specific fields. The object will be called
1624 with this equivalent signature:
1625 @code void decorator(
1629 @throws system_error Thrown on failure.
1631 template<class ConstBufferSequence,
1632 class ResponseDecorator>
1633 #if BOOST_BEAST_DOXYGEN
1636 typename std::enable_if<! http::detail::is_header<
1637 ConstBufferSequence>::value>::type
1640 ConstBufferSequence const& buffers,
1641 ResponseDecorator const& decorator);
1643 /** Read and respond to a WebSocket HTTP Upgrade request.
1645 This function is used to synchronously read an HTTP WebSocket
1646 Upgrade request and send the HTTP response. The call blocks
1647 until one of the following conditions is true:
1649 @li The request is received and the response finishes sending.
1651 @li An error occurs on the stream.
1653 This function is implemented in terms of one or more calls to
1654 the next layer's `read_some` and `write_some` functions.
1656 If the stream receives a valid HTTP WebSocket Upgrade request,
1657 an HTTP response is sent back indicating a successful upgrade.
1658 When this call returns, the stream is then ready to send and
1659 receive WebSocket protocol frames and messages.
1660 If the HTTP Upgrade request is invalid or cannot be satisfied,
1661 an HTTP response is sent indicating the reason and status code
1662 (typically 400, "Bad Request"). This counts as a failure.
1664 The implementation uses fixed size internal storage to
1665 receive the request. If the request is too large, the error
1666 @ref error::buffer_overflow will be indicated. Applications
1667 that wish to receive larger requests should first read the
1668 request using their own buffer and a suitable overload of
1669 @ref http::read or @ref http::async_read, then call @ref accept
1670 or @ref async_accept with the request.
1672 @param buffers Caller provided data that has already been
1673 received on the stream. The implementation will copy the
1674 caller provided data before the function returns.
1676 @param ec Set to indicate what error occurred, if any.
1678 template<class ConstBufferSequence>
1679 #if BOOST_BEAST_DOXYGEN
1682 typename std::enable_if<! http::detail::is_header<
1683 ConstBufferSequence>::value>::type
1686 ConstBufferSequence const& buffers,
1689 /** Read and respond to a WebSocket HTTP Upgrade request.
1691 This function is used to synchronously read an HTTP WebSocket
1692 Upgrade request and send the HTTP response. The call blocks
1693 until one of the following conditions is true:
1695 @li The request is received and the response finishes sending.
1697 @li An error occurs on the stream.
1699 This function is implemented in terms of one or more calls to
1700 the next layer's `read_some` and `write_some` functions.
1702 If the stream receives a valid HTTP WebSocket Upgrade request,
1703 an HTTP response is sent back indicating a successful upgrade.
1704 When this call returns, the stream is then ready to send and
1705 receive WebSocket protocol frames and messages.
1706 If the HTTP Upgrade request is invalid or cannot be satisfied,
1707 an HTTP response is sent indicating the reason and status code
1708 (typically 400, "Bad Request"). This counts as a failure.
1710 The implementation uses fixed size internal storage to
1711 receive the request. If the request is too large, the error
1712 @ref error::buffer_overflow will be indicated. Applications
1713 that wish to receive larger requests should first read the
1714 request using their own buffer and a suitable overload of
1715 @ref http::read or @ref http::async_read, then call @ref accept
1716 or @ref async_accept with the request.
1718 @param buffers Caller provided data that has already been
1719 received on the stream. The implementation will copy the
1720 caller provided data before the function returns.
1722 @param decorator A function object which will be called to modify
1723 the HTTP response object delivered by the implementation. This
1724 could be used to set the Server field, subprotocols, or other
1725 application or HTTP specific fields. The object will be called
1726 with this equivalent signature:
1727 @code void decorator(
1731 @param ec Set to indicate what error occurred, if any.
1733 template<class ConstBufferSequence, class ResponseDecorator>
1734 #if BOOST_BEAST_DOXYGEN
1737 typename std::enable_if<! http::detail::is_header<
1738 ConstBufferSequence>::value>::type
1741 ConstBufferSequence const& buffers,
1742 ResponseDecorator const& decorator,
1745 /** Respond to a WebSocket HTTP Upgrade request
1747 This function is used to synchronously send the HTTP response
1748 to an HTTP request possibly containing a WebSocket Upgrade.
1749 The call blocks until one of the following conditions is true:
1751 @li The response finishes sending.
1753 @li An error occurs on the stream.
1755 This function is implemented in terms of one or more calls to
1756 the next layer's `read_some` and `write_some` functions.
1758 If the stream receives a valid HTTP WebSocket Upgrade request,
1759 an HTTP response is sent back indicating a successful upgrade.
1760 When this call returns, the stream is then ready to send and
1761 receive WebSocket protocol frames and messages.
1762 If the HTTP Upgrade request is invalid or cannot be satisfied,
1763 an HTTP response is sent indicating the reason and status code
1764 (typically 400, "Bad Request"). This counts as a failure.
1766 @param req An object containing the HTTP Upgrade request.
1767 Ownership is not transferred, the implementation will not
1768 access this object from other threads.
1770 @throws system_error Thrown on failure.
1772 template<class Body, class Allocator>
1774 accept(http::request<Body,
1775 http::basic_fields<Allocator>> const& req);
1777 /** Respond to a WebSocket HTTP Upgrade request
1779 This function is used to synchronously send the HTTP response
1780 to an HTTP request possibly containing a WebSocket Upgrade.
1781 The call blocks until one of the following conditions is true:
1783 @li The response finishes sending.
1785 @li An error occurs on the stream.
1787 This function is implemented in terms of one or more calls to
1788 the next layer's `read_some` and `write_some` functions.
1790 If the stream receives a valid HTTP WebSocket Upgrade request,
1791 an HTTP response is sent back indicating a successful upgrade.
1792 When this call returns, the stream is then ready to send and
1793 receive WebSocket protocol frames and messages.
1794 If the HTTP Upgrade request is invalid or cannot be satisfied,
1795 an HTTP response is sent indicating the reason and status code
1796 (typically 400, "Bad Request"). This counts as a failure.
1798 @param req An object containing the HTTP Upgrade request.
1799 Ownership is not transferred, the implementation will not
1800 access this object from other threads.
1802 @param decorator A function object which will be called to modify
1803 the HTTP response object delivered by the implementation. This
1804 could be used to set the Server field, subprotocols, or other
1805 application or HTTP specific fields. The object will be called
1806 with this equivalent signature:
1807 @code void decorator(
1811 @throws system_error Thrown on failure.
1813 template<class Body, class Allocator,
1814 class ResponseDecorator>
1816 accept_ex(http::request<Body,
1817 http::basic_fields<Allocator>> const& req,
1818 ResponseDecorator const& decorator);
1820 /** Respond to a WebSocket HTTP Upgrade request
1822 This function is used to synchronously send the HTTP response
1823 to an HTTP request possibly containing a WebSocket Upgrade.
1824 The call blocks until one of the following conditions is true:
1826 @li The response finishes sending.
1828 @li An error occurs on the stream.
1830 This function is implemented in terms of one or more calls to
1831 the next layer's `read_some` and `write_some` functions.
1833 If the stream receives a valid HTTP WebSocket Upgrade request,
1834 an HTTP response is sent back indicating a successful upgrade.
1835 When this call returns, the stream is then ready to send and
1836 receive WebSocket protocol frames and messages.
1837 If the HTTP Upgrade request is invalid or cannot be satisfied,
1838 an HTTP response is sent indicating the reason and status code
1839 (typically 400, "Bad Request"). This counts as a failure.
1841 @param req An object containing the HTTP Upgrade request.
1842 Ownership is not transferred, the implementation will not
1843 access this object from other threads.
1845 @param ec Set to indicate what error occurred, if any.
1847 template<class Body, class Allocator>
1849 accept(http::request<Body,
1850 http::basic_fields<Allocator>> const& req,
1853 /** Respond to a WebSocket HTTP Upgrade request
1855 This function is used to synchronously send the HTTP response
1856 to an HTTP request possibly containing a WebSocket Upgrade.
1857 The call blocks until one of the following conditions is true:
1859 @li The response finishes sending.
1861 @li An error occurs on the stream.
1863 This function is implemented in terms of one or more calls to
1864 the next layer's `read_some` and `write_some` functions.
1866 If the stream receives a valid HTTP WebSocket Upgrade request,
1867 an HTTP response is sent back indicating a successful upgrade.
1868 When this call returns, the stream is then ready to send and
1869 receive WebSocket protocol frames and messages.
1870 If the HTTP Upgrade request is invalid or cannot be satisfied,
1871 an HTTP response is sent indicating the reason and status code
1872 (typically 400, "Bad Request"). This counts as a failure.
1874 @param req An object containing the HTTP Upgrade request.
1875 Ownership is not transferred, the implementation will not
1876 access this object from other threads.
1878 @param decorator A function object which will be called to modify
1879 the HTTP response object delivered by the implementation. This
1880 could be used to set the Server field, subprotocols, or other
1881 application or HTTP specific fields. The object will be called
1882 with this equivalent signature:
1883 @code void decorator(
1887 @param ec Set to indicate what error occurred, if any.
1889 template<class Body, class Allocator,
1890 class ResponseDecorator>
1892 accept_ex(http::request<Body,
1893 http::basic_fields<Allocator>> const& req,
1894 ResponseDecorator const& decorator,
1897 /** Start reading and responding to a WebSocket HTTP Upgrade request.
1899 This function is used to asynchronously read an HTTP WebSocket
1900 Upgrade request and send the HTTP response. The function call
1901 always returns immediately. The asynchronous operation will
1902 continue until one of the following conditions is true:
1904 @li The request is received and the response finishes sending.
1906 @li An error occurs on the stream.
1908 This operation is implemented in terms of one or more calls to
1909 the next layer's `async_read_some` and `async_write_some`
1910 functions, and is known as a <em>composed operation</em>. The
1911 program must ensure that the stream performs no other
1912 asynchronous operations until this operation completes.
1914 If the stream receives a valid HTTP WebSocket Upgrade request,
1915 an HTTP response is sent back indicating a successful upgrade.
1916 When the completion handler is invoked, the stream is then
1917 ready to send and receive WebSocket protocol frames and
1919 If the HTTP Upgrade request is invalid or cannot be satisfied,
1920 an HTTP response is sent indicating the reason and status code
1921 (typically 400, "Bad Request"). This counts as a failure, and
1922 the completion handler will be invoked with a suitable error
1925 The implementation uses fixed size internal storage to
1926 receive the request. If the request is too large, the error
1927 @ref error::buffer_overflow will be indicated. Applications
1928 that wish to receive larger requests should first read the
1929 request using their own buffer and a suitable overload of
1930 @ref http::read or @ref http::async_read, then call @ref accept
1931 or @ref async_accept with the request.
1933 @param handler The handler to be called when the request
1934 completes. Copies will be made of the handler as required. The
1935 equivalent function signature of the handler must be:
1937 error_code const& ec // Result of operation
1939 Regardless of whether the asynchronous operation completes
1940 immediately or not, the handler will not be invoked from within
1941 this function. Invocation of the handler will be performed in a
1942 manner equivalent to using `boost::asio::io_context::post`.
1944 template<class AcceptHandler>
1945 BOOST_ASIO_INITFN_RESULT_TYPE(
1946 AcceptHandler, void(error_code))
1947 async_accept(AcceptHandler&& handler);
1949 /** Start reading and responding to a WebSocket HTTP Upgrade request.
1951 This function is used to asynchronously read an HTTP WebSocket
1952 Upgrade request and send the HTTP response. The function call
1953 always returns immediately. The asynchronous operation will
1954 continue until one of the following conditions is true:
1956 @li The request is received and the response finishes sending.
1958 @li An error occurs on the stream.
1960 This operation is implemented in terms of one or more calls to
1961 the next layer's `async_read_some` and `async_write_some`
1962 functions, and is known as a <em>composed operation</em>. The
1963 program must ensure that the stream performs no other
1964 asynchronous operations until this operation completes.
1966 If the stream receives a valid HTTP WebSocket Upgrade request,
1967 an HTTP response is sent back indicating a successful upgrade.
1968 When the completion handler is invoked, the stream is then
1969 ready to send and receive WebSocket protocol frames and
1971 If the HTTP Upgrade request is invalid or cannot be satisfied,
1972 an HTTP response is sent indicating the reason and status code
1973 (typically 400, "Bad Request"). This counts as a failure, and
1974 the completion handler will be invoked with a suitable error
1977 The implementation uses fixed size internal storage to
1978 receive the request. If the request is too large, the error
1979 @ref error::buffer_overflow will be indicated. Applications
1980 that wish to receive larger requests should first read the
1981 request using their own buffer and a suitable overload of
1982 @ref http::read or @ref http::async_read, then call @ref accept
1983 or @ref async_accept with the request.
1985 @param decorator A function object which will be called to modify
1986 the HTTP response object delivered by the implementation. This
1987 could be used to set the Server field, subprotocols, or other
1988 application or HTTP specific fields. The object will be called
1989 with this equivalent signature:
1990 @code void decorator(
1994 @param handler The handler to be called when the request
1995 completes. Copies will be made of the handler as required. The
1996 equivalent function signature of the handler must be:
1998 error_code const& ec // Result of operation
2000 Regardless of whether the asynchronous operation completes
2001 immediately or not, the handler will not be invoked from within
2002 this function. Invocation of the handler will be performed in a
2003 manner equivalent to using `boost::asio::io_context::post`.
2006 class ResponseDecorator,
2007 class AcceptHandler>
2008 BOOST_ASIO_INITFN_RESULT_TYPE(
2009 AcceptHandler, void(error_code))
2011 ResponseDecorator const& decorator,
2012 AcceptHandler&& handler);
2014 /** Start reading and responding to a WebSocket HTTP Upgrade request.
2016 This function is used to asynchronously read an HTTP WebSocket
2017 Upgrade request and send the HTTP response. The function call
2018 always returns immediately. The asynchronous operation will
2019 continue until one of the following conditions is true:
2021 @li The request is received and the response finishes sending.
2023 @li An error occurs on the stream.
2025 This operation is implemented in terms of one or more calls to
2026 the next layer's `async_read_some` and `async_write_some`
2027 functions, and is known as a <em>composed operation</em>. The
2028 program must ensure that the stream performs no other
2029 asynchronous operations until this operation completes.
2031 If the stream receives a valid HTTP WebSocket Upgrade request,
2032 an HTTP response is sent back indicating a successful upgrade.
2033 When the completion handler is invoked, the stream is then
2034 ready to send and receive WebSocket protocol frames and
2036 If the HTTP Upgrade request is invalid or cannot be satisfied,
2037 an HTTP response is sent indicating the reason and status code
2038 (typically 400, "Bad Request"). This counts as a failure, and
2039 the completion handler will be invoked with a suitable error
2042 The implementation uses fixed size internal storage to
2043 receive the request. If the request is too large, the error
2044 @ref error::buffer_overflow will be indicated. Applications
2045 that wish to receive larger requests should first read the
2046 request using their own buffer and a suitable overload of
2047 @ref http::read or @ref http::async_read, then call @ref accept
2048 or @ref async_accept with the request.
2050 @param buffers Caller provided data that has already been
2051 received on the stream. This may be used for implementations
2052 allowing multiple protocols on the same stream. The
2053 buffered data will first be applied to the handshake, and
2054 then to received WebSocket frames. The implementation will
2055 copy the caller provided data before the function returns.
2057 @param handler The handler to be called when the request
2058 completes. Copies will be made of the handler as required. The
2059 equivalent function signature of the handler must be:
2061 error_code const& ec // Result of operation
2063 Regardless of whether the asynchronous operation completes
2064 immediately or not, the handler will not be invoked from within
2065 this function. Invocation of the handler will be performed in a
2066 manner equivalent to using `boost::asio::io_context::post`.
2069 class ConstBufferSequence,
2070 class AcceptHandler>
2071 #if BOOST_BEAST_DOXYGEN
2074 typename std::enable_if<
2075 ! http::detail::is_header<ConstBufferSequence>::value,
2076 BOOST_ASIO_INITFN_RESULT_TYPE(
2077 AcceptHandler, void(error_code))>::type
2080 ConstBufferSequence const& buffers,
2081 AcceptHandler&& handler);
2083 /** Start reading and responding to a WebSocket HTTP Upgrade request.
2085 This function is used to asynchronously read an HTTP WebSocket
2086 Upgrade request and send the HTTP response. The function call
2087 always returns immediately. The asynchronous operation will
2088 continue until one of the following conditions is true:
2090 @li The request is received and the response finishes sending.
2092 @li An error occurs on the stream.
2094 This operation is implemented in terms of one or more calls to
2095 the next layer's `async_read_some` and `async_write_some`
2096 functions, and is known as a <em>composed operation</em>. The
2097 program must ensure that the stream performs no other
2098 asynchronous operations until this operation completes.
2100 If the stream receives a valid HTTP WebSocket Upgrade request,
2101 an HTTP response is sent back indicating a successful upgrade.
2102 When the completion handler is invoked, the stream is then
2103 ready to send and receive WebSocket protocol frames and
2105 If the HTTP Upgrade request is invalid or cannot be satisfied,
2106 an HTTP response is sent indicating the reason and status code
2107 (typically 400, "Bad Request"). This counts as a failure, and
2108 the completion handler will be invoked with a suitable error
2111 The implementation uses fixed size internal storage to
2112 receive the request. If the request is too large, the error
2113 @ref error::buffer_overflow will be indicated. Applications
2114 that wish to receive larger requests should first read the
2115 request using their own buffer and a suitable overload of
2116 @ref http::read or @ref http::async_read, then call @ref accept
2117 or @ref async_accept with the request.
2119 @param buffers Caller provided data that has already been
2120 received on the stream. This may be used for implementations
2121 allowing multiple protocols on the same stream. The
2122 buffered data will first be applied to the handshake, and
2123 then to received WebSocket frames. The implementation will
2124 copy the caller provided data before the function returns.
2126 @param decorator A function object which will be called to modify
2127 the HTTP response object delivered by the implementation. This
2128 could be used to set the Server field, subprotocols, or other
2129 application or HTTP specific fields. The object will be called
2130 with this equivalent signature:
2131 @code void decorator(
2135 @param handler The handler to be called when the request
2136 completes. Copies will be made of the handler as required. The
2137 equivalent function signature of the handler must be:
2139 error_code const& ec // Result of operation
2141 Regardless of whether the asynchronous operation completes
2142 immediately or not, the handler will not be invoked from within
2143 this function. Invocation of the handler will be performed in a
2144 manner equivalent to using `boost::asio::io_context::post`.
2147 class ConstBufferSequence,
2148 class ResponseDecorator,
2149 class AcceptHandler>
2150 #if BOOST_BEAST_DOXYGEN
2153 typename std::enable_if<
2154 ! http::detail::is_header<ConstBufferSequence>::value,
2155 BOOST_ASIO_INITFN_RESULT_TYPE(
2156 AcceptHandler, void(error_code))>::type
2159 ConstBufferSequence const& buffers,
2160 ResponseDecorator const& decorator,
2161 AcceptHandler&& handler);
2163 /** Start responding to a WebSocket HTTP Upgrade request.
2165 This function is used to asynchronously send the HTTP response
2166 to an HTTP request possibly containing a WebSocket Upgrade
2167 request. The function call always returns immediately. The
2168 asynchronous operation will continue until one of the following
2171 @li The response finishes sending.
2173 @li An error occurs on the stream.
2175 This operation is implemented in terms of one or more calls to
2176 the next layer's `async_write_some` functions, and is known as
2177 a <em>composed operation</em>. The program must ensure that the
2178 stream performs no other operations until this operation
2181 If the stream receives a valid HTTP WebSocket Upgrade request,
2182 an HTTP response is sent back indicating a successful upgrade.
2183 When the completion handler is invoked, the stream is then
2184 ready to send and receive WebSocket protocol frames and
2186 If the HTTP Upgrade request is invalid or cannot be satisfied,
2187 an HTTP response is sent indicating the reason and status code
2188 (typically 400, "Bad Request"). This counts as a failure, and
2189 the completion handler will be invoked with a suitable error
2192 @param req An object containing the HTTP Upgrade request.
2193 Ownership is not transferred, the implementation will not access
2194 this object from other threads.
2196 @param handler The handler to be called when the request
2197 completes. Copies will be made of the handler as required. The
2198 equivalent function signature of the handler must be:
2200 error_code const& ec // Result of operation
2202 Regardless of whether the asynchronous operation completes
2203 immediately or not, the handler will not be invoked from within
2204 this function. Invocation of the handler will be performed in a
2205 manner equivalent to using `boost::asio::io_context::post`.
2208 class Body, class Allocator,
2209 class AcceptHandler>
2210 BOOST_ASIO_INITFN_RESULT_TYPE(
2211 AcceptHandler, void(error_code))
2214 http::basic_fields<Allocator>> const& req,
2215 AcceptHandler&& handler);
2217 /** Start responding to a WebSocket HTTP Upgrade request.
2219 This function is used to asynchronously send the HTTP response
2220 to an HTTP request possibly containing a WebSocket Upgrade
2221 request. The function call always returns immediately. The
2222 asynchronous operation will continue until one of the following
2225 @li The response finishes sending.
2227 @li An error occurs on the stream.
2229 This operation is implemented in terms of one or more calls to
2230 the next layer's `async_write_some` functions, and is known as
2231 a <em>composed operation</em>. The program must ensure that the
2232 stream performs no other operations until this operation
2235 If the stream receives a valid HTTP WebSocket Upgrade request,
2236 an HTTP response is sent back indicating a successful upgrade.
2237 When the completion handler is invoked, the stream is then
2238 ready to send and receive WebSocket protocol frames and
2240 If the HTTP Upgrade request is invalid or cannot be satisfied,
2241 an HTTP response is sent indicating the reason and status code
2242 (typically 400, "Bad Request"). This counts as a failure, and
2243 the completion handler will be invoked with a suitable error
2246 @param req An object containing the HTTP Upgrade request.
2247 Ownership is not transferred, the implementation will not access
2248 this object from other threads.
2250 @param decorator A function object which will be called to modify
2251 the HTTP response object delivered by the implementation. This
2252 could be used to set the Server field, subprotocols, or other
2253 application or HTTP specific fields. The object will be called
2254 with this equivalent signature:
2255 @code void decorator(
2259 @param handler The handler to be called when the request
2260 completes. Copies will be made of the handler as required. The
2261 equivalent function signature of the handler must be:
2263 error_code const& ec // Result of operation
2265 Regardless of whether the asynchronous operation completes
2266 immediately or not, the handler will not be invoked from within
2267 this function. Invocation of the handler will be performed in a
2268 manner equivalent to using `boost::asio::io_context::post`.
2271 class Body, class Allocator,
2272 class ResponseDecorator,
2273 class AcceptHandler>
2274 BOOST_ASIO_INITFN_RESULT_TYPE(
2275 AcceptHandler, void(error_code))
2278 http::basic_fields<Allocator>> const& req,
2279 ResponseDecorator const& decorator,
2280 AcceptHandler&& handler);
2282 //--------------------------------------------------------------------------
2286 //--------------------------------------------------------------------------
2288 /** Send a WebSocket close frame.
2290 This function is used to synchronously send a close frame on
2291 the stream. The call blocks until one of the following is true:
2293 @li The close frame finishes sending.
2295 @li An error occurs on the stream.
2297 This function is implemented in terms of one or more calls
2298 to the next layer's `write_some` functions.
2300 If the close reason specifies a close code other than
2301 @ref beast::websocket::close_code::none, the close frame is
2302 sent with the close code and optional reason string. Otherwise,
2303 the close frame is sent with no payload.
2305 Callers should not attempt to write WebSocket data after
2306 initiating the close. Instead, callers should continue
2307 reading until an error occurs. A read returning @ref error::closed
2308 indicates a successful connection closure.
2310 @param cr The reason for the close.
2312 @throws system_error Thrown on failure.
2315 close(close_reason const& cr);
2317 /** Send a WebSocket close frame.
2319 This function is used to synchronously send a close frame on
2320 the stream. The call blocks until one of the following is true:
2322 @li The close frame finishes sending.
2324 @li An error occurs on the stream.
2326 This function is implemented in terms of one or more calls
2327 to the next layer's `write_some` functions.
2329 If the close reason specifies a close code other than
2330 @ref beast::websocket::close_code::none, the close frame is
2331 sent with the close code and optional reason string. Otherwise,
2332 the close frame is sent with no payload.
2334 Callers should not attempt to write WebSocket data after
2335 initiating the close. Instead, callers should continue
2336 reading until an error occurs. A read returning @ref error::closed
2337 indicates a successful connection closure.
2339 @param cr The reason for the close.
2341 @param ec Set to indicate what error occurred, if any.
2344 close(close_reason const& cr, error_code& ec);
2346 /** Start an asynchronous operation to send a WebSocket close frame.
2348 This function is used to asynchronously send a close frame on
2349 the stream. This function call always returns immediately. The
2350 asynchronous operation will continue until one of the following
2353 @li The close frame finishes sending.
2355 @li An error occurs on the stream.
2357 This operation is implemented in terms of one or more calls to the
2358 next layer's `async_write_some` functions, and is known as a
2359 <em>composed operation</em>. The program must ensure that the
2360 stream performs no other write operations (such as @ref async_ping,
2361 @ref stream::async_write, @ref stream::async_write_some, or
2362 @ref stream::async_close) until this operation completes.
2364 If the close reason specifies a close code other than
2365 @ref beast::websocket::close_code::none, the close frame is
2366 sent with the close code and optional reason string. Otherwise,
2367 the close frame is sent with no payload.
2369 Callers should not attempt to write WebSocket data after
2370 initiating the close. Instead, callers should continue
2371 reading until an error occurs. A read returning @ref error::closed
2372 indicates a successful connection closure.
2374 @param cr The reason for the close.
2376 @param handler The handler to be called when the close operation
2377 completes. Copies will be made of the handler as required. The
2378 function signature of the handler must be:
2381 error_code const& ec // Result of operation
2384 Regardless of whether the asynchronous operation completes
2385 immediately or not, the handler will not be invoked from within
2386 this function. Invocation of the handler will be performed in a
2387 manner equivalent to using `boost::asio::io_context::post`.
2389 template<class CloseHandler>
2390 BOOST_ASIO_INITFN_RESULT_TYPE(
2391 CloseHandler, void(error_code))
2392 async_close(close_reason const& cr, CloseHandler&& handler);
2394 /** Send a WebSocket ping frame.
2396 This function is used to synchronously send a ping frame on
2397 the stream. The call blocks until one of the following is true:
2399 @li The ping frame finishes sending.
2401 @li An error occurs on the stream.
2403 This function is implemented in terms of one or more calls to the
2404 next layer's `write_some` functions.
2406 @param payload The payload of the ping message, which may be empty.
2408 @throws system_error Thrown on failure.
2411 ping(ping_data const& payload);
2413 /** Send a WebSocket ping frame.
2415 This function is used to synchronously send a ping frame on
2416 the stream. The call blocks until one of the following is true:
2418 @li The ping frame finishes sending.
2420 @li An error occurs on the stream.
2422 This function is implemented in terms of one or more calls to the
2423 next layer's `write_some` functions.
2425 @param payload The payload of the ping message, which may be empty.
2427 @param ec Set to indicate what error occurred, if any.
2430 ping(ping_data const& payload, error_code& ec);
2432 /** Start an asynchronous operation to send a WebSocket ping frame.
2434 This function is used to asynchronously send a ping frame to
2435 the stream. The function call always returns immediately. The
2436 asynchronous operation will continue until one of the following
2439 @li The entire ping frame is sent.
2441 @li An error occurs on the stream.
2443 This operation is implemented in terms of one or more calls to the
2444 next layer's `async_write_some` functions, and is known as a
2445 <em>composed operation</em>. The program must ensure that the
2446 stream performs no other writes until this operation completes.
2448 If a close frame is sent or received before the ping frame is
2449 sent, the completion handler will be called with the error
2450 set to `boost::asio::error::operation_aborted`.
2452 @param payload The payload of the ping message, which may be empty.
2454 @param handler The handler to be called when the read operation
2455 completes. Copies will be made of the handler as required. The
2456 function signature of the handler must be:
2459 error_code const& ec // Result of operation
2462 Regardless of whether the asynchronous operation completes
2463 immediately or not, the handler will not be invoked from within
2464 this function. Invocation of the handler will be performed in a
2465 manner equivalent to using `boost::asio::io_context::post`.
2467 template<class WriteHandler>
2468 BOOST_ASIO_INITFN_RESULT_TYPE(
2469 WriteHandler, void(error_code))
2470 async_ping(ping_data const& payload, WriteHandler&& handler);
2472 /** Send a WebSocket pong frame.
2474 This function is used to synchronously send a pong frame on
2475 the stream. The call blocks until one of the following is true:
2477 @li The pong frame finishes sending.
2479 @li An error occurs on the stream.
2481 This function is implemented in terms of one or more calls to the
2482 next layer's `write_some` functions.
2484 The WebSocket protocol allows pong frames to be sent from either
2485 end at any time. It is not necessary to first receive a ping in
2486 order to send a pong. The remote peer may use the receipt of a
2487 pong frame as an indication that the connection is not dead.
2489 @param payload The payload of the pong message, which may be empty.
2491 @throws system_error Thrown on failure.
2494 pong(ping_data const& payload);
2496 /** Send a WebSocket pong frame.
2498 This function is used to synchronously send a pong frame on
2499 the stream. The call blocks until one of the following is true:
2501 @li The pong frame finishes sending.
2503 @li An error occurs on the stream.
2505 This function is implemented in terms of one or more calls to the
2506 next layer's `write_some` functions.
2508 The WebSocket protocol allows pong frames to be sent from either
2509 end at any time. It is not necessary to first receive a ping in
2510 order to send a pong. The remote peer may use the receipt of a
2511 pong frame as an indication that the connection is not dead.
2513 @param payload The payload of the pong message, which may be empty.
2515 @param ec Set to indicate what error occurred, if any.
2518 pong(ping_data const& payload, error_code& ec);
2520 /** Start an asynchronous operation to send a WebSocket pong frame.
2522 This function is used to asynchronously send a pong frame to
2523 the stream. The function call always returns immediately. The
2524 asynchronous operation will continue until one of the following
2527 @li The entire pong frame is sent.
2529 @li An error occurs on the stream.
2531 This operation is implemented in terms of one or more calls to the
2532 next layer's `async_write_some` functions, and is known as a
2533 <em>composed operation</em>. The program must ensure that the
2534 stream performs no other writes until this operation completes.
2536 The WebSocket protocol allows pong frames to be sent from either
2537 end at any time. It is not necessary to first receive a ping in
2538 order to send a pong. The remote peer may use the receipt of a
2539 pong frame as an indication that the connection is not dead.
2541 If a close frame is sent or received before the pong frame is
2542 sent, the completion handler will be called with the error
2543 set to `boost::asio::error::operation_aborted`.
2545 @param payload The payload of the pong message, which may be empty.
2547 @param handler The handler to be called when the read operation
2548 completes. Copies will be made of the handler as required. The
2549 function signature of the handler must be:
2552 error_code const& ec // Result of operation
2555 Regardless of whether the asynchronous operation completes
2556 immediately or not, the handler will not be invoked from within
2557 this function. Invocation of the handler will be performed in a
2558 manner equivalent to using `boost::asio::io_context::post`.
2560 template<class WriteHandler>
2561 BOOST_ASIO_INITFN_RESULT_TYPE(
2562 WriteHandler, void(error_code))
2563 async_pong(ping_data const& payload, WriteHandler&& handler);
2565 //--------------------------------------------------------------------------
2569 //--------------------------------------------------------------------------
2573 This function is used to synchronously read a complete
2574 message from the stream.
2575 The call blocks until one of the following is true:
2577 @li A complete message is received.
2579 @li A close frame is received. In this case the error indicated by
2580 the function will be @ref error::closed.
2582 @li An error occurs on the stream.
2584 This operation is implemented in terms of one or more calls to the next
2585 layer's `read_some` and `write_some` functions.
2587 Received message data, if any, is appended to the input area of the
2588 buffer. The functions @ref got_binary and @ref got_text may be used
2589 to query the stream and determine the type of the last received message.
2591 While this operation is active, the implementation will read incoming
2592 control frames and handle them automatically as follows:
2594 @li The @ref control_callback will be invoked for each control frame.
2596 @li For each received ping frame, a pong frame will be
2599 @li If a close frame is received, the WebSocket close procedure is
2600 performed. In this case, when the function returns, the error
2601 @ref error::closed will be indicated.
2603 @return The number of message payload bytes appended to the buffer.
2605 @param buffer A dynamic buffer to hold the message data after any
2606 masking or decompression has been applied.
2608 @throws system_error Thrown to indicate an error. The corresponding
2609 error code may be retrieved from the exception object for inspection.
2611 template<class DynamicBuffer>
2613 read(DynamicBuffer& buffer);
2617 This function is used to synchronously read a complete
2618 message from the stream.
2619 The call blocks until one of the following is true:
2621 @li A complete message is received.
2623 @li A close frame is received. In this case the error indicated by
2624 the function will be @ref error::closed.
2626 @li An error occurs on the stream.
2628 This operation is implemented in terms of one or more calls to the next
2629 layer's `read_some` and `write_some` functions.
2631 Received message data, if any, is appended to the input area of the
2632 buffer. The functions @ref got_binary and @ref got_text may be used
2633 to query the stream and determine the type of the last received message.
2635 While this operation is active, the implementation will read incoming
2636 control frames and handle them automatically as follows:
2638 @li The @ref control_callback will be invoked for each control frame.
2640 @li For each received ping frame, a pong frame will be
2643 @li If a close frame is received, the WebSocket close procedure is
2644 performed. In this case, when the function returns, the error
2645 @ref error::closed will be indicated.
2647 @return The number of message payload bytes appended to the buffer.
2649 @param buffer A dynamic buffer to hold the message data after any
2650 masking or decompression has been applied.
2652 @param ec Set to indicate what error occurred, if any.
2654 template<class DynamicBuffer>
2656 read(DynamicBuffer& buffer, error_code& ec);
2658 /** Read a message asynchronously
2660 This function is used to asynchronously read a complete
2661 message from the stream.
2662 The function call always returns immediately.
2663 The asynchronous operation will continue until one of the
2666 @li A complete message is received.
2668 @li A close frame is received. In this case the error indicated by
2669 the function will be @ref error::closed.
2671 @li An error occurs on the stream.
2673 This operation is implemented in terms of one or more calls to the
2674 next layer's `async_read_some` and `async_write_some` functions,
2675 and is known as a <em>composed operation</em>. The program must
2676 ensure that the stream performs no other reads until this operation
2679 Received message data, if any, is appended to the input area of the
2680 buffer. The functions @ref got_binary and @ref got_text may be used
2681 to query the stream and determine the type of the last received message.
2683 While this operation is active, the implementation will read incoming
2684 control frames and handle them automatically as follows:
2686 @li The @ref control_callback will be invoked for each control frame.
2688 @li For each received ping frame, a pong frame will be
2691 @li If a close frame is received, the WebSocket close procedure is
2692 performed. In this case, when the function returns, the error
2693 @ref error::closed will be indicated.
2695 Because of the need to handle control frames, asynchronous read
2696 operations can cause writes to take place. These writes are managed
2697 transparently; callers can still have one active asynchronous
2698 read and asynchronous write operation pending simultaneously
2699 (a user initiated call to @ref async_close counts as a write).
2701 @param buffer A dynamic buffer to hold the message data after
2702 any masking or decompression has been applied. This object must
2703 remain valid until the handler is called.
2705 @param handler The handler to be called when the read operation
2706 completes. Copies will be made of the handler as required. The
2707 equivalent function signature of the handler must be:
2710 error_code const& ec, // Result of operation
2711 std::size_t bytes_written // Number of bytes appended to buffer
2714 Regardless of whether the asynchronous operation completes
2715 immediately or not, the handler will not be invoked from within
2716 this function. Invocation of the handler will be performed in a
2717 manner equivalent to using `boost::asio::io_context::post`.
2719 template<class DynamicBuffer, class ReadHandler>
2720 BOOST_ASIO_INITFN_RESULT_TYPE(
2721 ReadHandler, void(error_code, std::size_t))
2723 DynamicBuffer& buffer,
2724 ReadHandler&& handler);
2726 //--------------------------------------------------------------------------
2728 /** Read part of a message
2730 This function is used to synchronously read some
2731 message data from the stream.
2732 The call blocks until one of the following is true:
2734 @li Some or all of the message is received.
2736 @li A close frame is received. In this case the error indicated by
2737 the function will be @ref error::closed.
2739 @li An error occurs on the stream.
2741 This operation is implemented in terms of one or more calls to the next
2742 layer's `read_some` and `write_some` functions.
2744 Received message data, if any, is appended to the input area of the
2745 buffer. The functions @ref got_binary and @ref got_text may be used
2746 to query the stream and determine the type of the last received message.
2747 The function @ref is_message_done may be called to determine if the
2748 message received by the last read operation is complete.
2750 While this operation is active, the implementation will read incoming
2751 control frames and handle them automatically as follows:
2753 @li The @ref control_callback will be invoked for each control frame.
2755 @li For each received ping frame, a pong frame will be
2758 @li If a close frame is received, the WebSocket close procedure is
2759 performed. In this case, when the function returns, the error
2760 @ref error::closed will be indicated.
2762 @return The number of message payload bytes appended to the buffer.
2764 @param buffer A dynamic buffer to hold the message data after any
2765 masking or decompression has been applied.
2767 @param limit An upper limit on the number of bytes this function
2768 will append into the buffer. If this value is zero, then a reasonable
2769 size will be chosen automatically.
2771 @throws system_error Thrown to indicate an error. The corresponding
2772 error code may be retrieved from the exception object for inspection.
2774 template<class DynamicBuffer>
2777 DynamicBuffer& buffer,
2780 /** Read part of a message
2782 This function is used to synchronously read some
2783 message data from the stream.
2784 The call blocks until one of the following is true:
2786 @li Some or all of the message is received.
2788 @li A close frame is received. In this case the error indicated by
2789 the function will be @ref error::closed.
2791 @li An error occurs on the stream.
2793 This operation is implemented in terms of one or more calls to the next
2794 layer's `read_some` and `write_some` functions.
2796 Received message data, if any, is appended to the input area of the
2797 buffer. The functions @ref got_binary and @ref got_text may be used
2798 to query the stream and determine the type of the last received message.
2799 The function @ref is_message_done may be called to determine if the
2800 message received by the last read operation is complete.
2802 While this operation is active, the implementation will read incoming
2803 control frames and handle them automatically as follows:
2805 @li The @ref control_callback will be invoked for each control frame.
2807 @li For each received ping frame, a pong frame will be
2810 @li If a close frame is received, the WebSocket close procedure is
2811 performed. In this case, when the function returns, the error
2812 @ref error::closed will be indicated.
2814 @return The number of message payload bytes appended to the buffer.
2816 @param buffer A dynamic buffer to hold the message data after any
2817 masking or decompression has been applied.
2819 @param limit An upper limit on the number of bytes this function
2820 will append into the buffer. If this value is zero, then a reasonable
2821 size will be chosen automatically.
2823 @param ec Set to indicate what error occurred, if any.
2825 template<class DynamicBuffer>
2828 DynamicBuffer& buffer,
2832 /** Read part of a message asynchronously
2834 This function is used to asynchronously read part of a
2835 message from the stream.
2836 The function call always returns immediately.
2837 The asynchronous operation will continue until one of the
2840 @li Some or all of the message is received.
2842 @li A close frame is received. In this case the error indicated by
2843 the function will be @ref error::closed.
2845 @li An error occurs on the stream.
2847 This operation is implemented in terms of one or more calls to the
2848 next layer's `async_read_some` and `async_write_some` functions,
2849 and is known as a <em>composed operation</em>. The program must
2850 ensure that the stream performs no other reads until this operation
2853 Received message data, if any, is appended to the input area of the
2854 buffer. The functions @ref got_binary and @ref got_text may be used
2855 to query the stream and determine the type of the last received message.
2856 The function @ref is_message_done may be called to determine if the
2857 message received by the last read operation is complete.
2859 While this operation is active, the implementation will read incoming
2860 control frames and handle them automatically as follows:
2862 @li The @ref control_callback will be invoked for each control frame.
2864 @li For each received ping frame, a pong frame will be
2867 @li If a close frame is received, the WebSocket close procedure is
2868 performed. In this case, when the function returns, the error
2869 @ref error::closed will be indicated.
2871 Because of the need to handle control frames, asynchronous read
2872 operations can cause writes to take place. These writes are managed
2873 transparently; callers can still have one active asynchronous
2874 read and asynchronous write operation pending simultaneously
2875 (a user initiated call to @ref async_close counts as a write).
2877 @param buffer A dynamic buffer to hold the message data after
2878 any masking or decompression has been applied. This object must
2879 remain valid until the handler is called.
2881 @param limit An upper limit on the number of bytes this function
2882 will append into the buffer. If this value is zero, then a reasonable
2883 size will be chosen automatically.
2885 @param handler The handler to be called when the read operation
2886 completes. Copies will be made of the handler as required. The
2887 equivalent function signature of the handler must be:
2890 error_code const& ec, // Result of operation
2891 std::size_t bytes_written // Number of bytes appended to buffer
2894 Regardless of whether the asynchronous operation completes
2895 immediately or not, the handler will not be invoked from within
2896 this function. Invocation of the handler will be performed in a
2897 manner equivalent to using `boost::asio::io_context::post`.
2899 template<class DynamicBuffer, class ReadHandler>
2900 BOOST_ASIO_INITFN_RESULT_TYPE(
2901 ReadHandler, void(error_code, std::size_t))
2903 DynamicBuffer& buffer,
2905 ReadHandler&& handler);
2907 //--------------------------------------------------------------------------
2909 /** Read part of a message
2911 This function is used to synchronously read some
2912 message data from the stream.
2913 The call blocks until one of the following is true:
2915 @li Some or all of the message is received.
2917 @li A close frame is received. In this case the error indicated by
2918 the function will be @ref error::closed.
2920 @li An error occurs on the stream.
2922 This operation is implemented in terms of one or more calls to the next
2923 layer's `read_some` and `write_some` functions.
2925 Received message data, if any, is written to the buffer sequence.
2926 The functions @ref got_binary and @ref got_text may be used
2927 to query the stream and determine the type of the last received message.
2928 The function @ref is_message_done may be called to determine if the
2929 message received by the last read operation is complete.
2931 While this operation is active, the implementation will read incoming
2932 control frames and handle them automatically as follows:
2934 @li The @ref control_callback will be invoked for each control frame.
2936 @li For each received ping frame, a pong frame will be
2939 @li If a close frame is received, the WebSocket close procedure is
2940 performed. In this case, when the function returns, the error
2941 @ref error::closed will be indicated.
2943 @return The number of message payload bytes written to the
2946 @param buffers A buffer sequence to hold the message data after any
2947 masking or decompression has been applied.
2949 @throws system_error Thrown to indicate an error. The corresponding
2950 error code may be retrieved from the exception object for inspection.
2952 template<class MutableBufferSequence>
2955 MutableBufferSequence const& buffers);
2957 /** Read part of a message
2959 This function is used to synchronously read some
2960 message data from the stream.
2961 The call blocks until one of the following is true:
2963 @li Some or all of the message is received.
2965 @li A close frame is received. In this case the error indicated by
2966 the function will be @ref error::closed.
2968 @li An error occurs on the stream.
2970 This operation is implemented in terms of one or more calls to the next
2971 layer's `read_some` and `write_some` functions.
2973 Received message data, if any, is written to the buffer sequence.
2974 The functions @ref got_binary and @ref got_text may be used
2975 to query the stream and determine the type of the last received message.
2976 The function @ref is_message_done may be called to determine if the
2977 message received by the last read operation is complete.
2979 While this operation is active, the implementation will read incoming
2980 control frames and handle them automatically as follows:
2982 @li The @ref control_callback will be invoked for each control frame.
2984 @li For each received ping frame, a pong frame will be
2987 @li If a close frame is received, the WebSocket close procedure is
2988 performed. In this case, when the function returns, the error
2989 @ref error::closed will be indicated.
2991 @return The number of message payload bytes written to the
2994 @param buffers A buffer sequence to hold the message data after any
2995 masking or decompression has been applied.
2997 @param ec Set to indicate what error occurred, if any.
2999 template<class MutableBufferSequence>
3002 MutableBufferSequence const& buffers,
3005 /** Read part of a message asynchronously
3007 This function is used to asynchronously read part of a
3008 message from the stream.
3009 The function call always returns immediately.
3010 The asynchronous operation will continue until one of the
3013 @li Some or all of the message is received.
3015 @li A close frame is received. In this case the error indicated by
3016 the function will be @ref error::closed.
3018 @li An error occurs on the stream.
3020 This operation is implemented in terms of one or more calls to the
3021 next layer's `async_read_some` and `async_write_some` functions,
3022 and is known as a <em>composed operation</em>. The program must
3023 ensure that the stream performs no other reads until this operation
3026 Received message data, if any, is written to the buffer sequence.
3027 The functions @ref got_binary and @ref got_text may be used
3028 to query the stream and determine the type of the last received message.
3029 The function @ref is_message_done may be called to determine if the
3030 message received by the last read operation is complete.
3032 While this operation is active, the implementation will read incoming
3033 control frames and handle them automatically as follows:
3035 @li The @ref control_callback will be invoked for each control frame.
3037 @li For each received ping frame, a pong frame will be
3040 @li If a close frame is received, the WebSocket close procedure is
3041 performed. In this case, when the function returns, the error
3042 @ref error::closed will be indicated.
3044 Because of the need to handle control frames, asynchronous read
3045 operations can cause writes to take place. These writes are managed
3046 transparently; callers can still have one active asynchronous
3047 read and asynchronous write operation pending simultaneously
3048 (a user initiated call to @ref async_close counts as a write).
3050 @param buffers The buffer sequence into which message data will
3051 be placed after any masking or decompresison has been applied.
3052 The implementation will make copies of this object as needed,
3053 but ownership of the underlying memory is not transferred.
3054 The caller is responsible for ensuring that the memory
3055 locations pointed to by the buffer sequence remains valid
3056 until the completion handler is called.
3058 @param handler The handler to be called when the read operation
3059 completes. Copies will be made of the handler as required. The
3060 equivalent function signature of the handler must be:
3063 error_code const& ec, // Result of operation
3064 std::size_t bytes_written // Number of bytes written to the buffer sequence
3067 Regardless of whether the asynchronous operation completes
3068 immediately or not, the handler will not be invoked from within
3069 this function. Invocation of the handler will be performed in a
3070 manner equivalent to using `boost::asio::io_context::post`.
3072 template<class MutableBufferSequence, class ReadHandler>
3073 BOOST_ASIO_INITFN_RESULT_TYPE(
3074 ReadHandler, void(error_code, std::size_t))
3076 MutableBufferSequence const& buffers,
3077 ReadHandler&& handler);
3079 //--------------------------------------------------------------------------
3083 //--------------------------------------------------------------------------
3085 /** Write a message to the stream.
3087 This function is used to synchronously write a message to
3088 the stream. The call blocks until one of the following conditions
3091 @li The entire message is sent.
3093 @li An error occurs.
3095 This operation is implemented in terms of one or more calls to the
3096 next layer's `write_some` function.
3098 The current setting of the @ref binary option controls
3099 whether the message opcode is set to text or binary. If the
3100 @ref auto_fragment option is set, the message will be split
3101 into one or more frames as necessary. The actual payload contents
3102 sent may be transformed as per the WebSocket protocol settings.
3104 @param buffers The buffers containing the entire message
3105 payload. The implementation will make copies of this object
3106 as needed, but ownership of the underlying memory is not
3107 transferred. The caller is responsible for ensuring that
3108 the memory locations pointed to by buffers remains valid
3109 until the completion handler is called.
3111 @return The number of bytes written from the buffers.
3112 If an error occurred, this will be less than the sum
3113 of the buffer sizes.
3115 @throws system_error Thrown on failure.
3117 @note This function always sends an entire message. To
3118 send a message in fragments, use @ref write_some.
3120 template<class ConstBufferSequence>
3122 write(ConstBufferSequence const& buffers);
3124 /** Write a message to the stream.
3126 This function is used to synchronously write a message to
3127 the stream. The call blocks until one of the following conditions
3130 @li The entire message is sent.
3132 @li An error occurs.
3134 This operation is implemented in terms of one or more calls to the
3135 next layer's `write_some` function.
3137 The current setting of the @ref binary option controls
3138 whether the message opcode is set to text or binary. If the
3139 @ref auto_fragment option is set, the message will be split
3140 into one or more frames as necessary. The actual payload contents
3141 sent may be transformed as per the WebSocket protocol settings.
3143 @param buffers The buffers containing the entire message
3144 payload. The implementation will make copies of this object
3145 as needed, but ownership of the underlying memory is not
3146 transferred. The caller is responsible for ensuring that
3147 the memory locations pointed to by buffers remains valid
3148 until the completion handler is called.
3150 @return The number of bytes written from the buffers.
3151 If an error occurred, this will be less than the sum
3152 of the buffer sizes.
3154 @param ec Set to indicate what error occurred, if any.
3156 @throws system_error Thrown on failure.
3158 @note This function always sends an entire message. To
3159 send a message in fragments, use @ref write_some.
3161 template<class ConstBufferSequence>
3163 write(ConstBufferSequence const& buffers, error_code& ec);
3165 /** Start an asynchronous operation to write a message to the stream.
3167 This function is used to asynchronously write a message to
3168 the stream. The function call always returns immediately.
3169 The asynchronous operation will continue until one of the
3170 following conditions is true:
3172 @li The entire message is sent.
3174 @li An error occurs.
3176 This operation is implemented in terms of one or more calls
3177 to the next layer's `async_write_some` functions, and is known
3178 as a <em>composed operation</em>. The program must ensure that
3179 the stream performs no other write operations (such as
3180 stream::async_write, stream::async_write_some, or
3181 stream::async_close).
3183 The current setting of the @ref binary option controls
3184 whether the message opcode is set to text or binary. If the
3185 @ref auto_fragment option is set, the message will be split
3186 into one or more frames as necessary. The actual payload contents
3187 sent may be transformed as per the WebSocket protocol settings.
3189 @param buffers The buffers containing the entire message
3190 payload. The implementation will make copies of this object
3191 as needed, but ownership of the underlying memory is not
3192 transferred. The caller is responsible for ensuring that
3193 the memory locations pointed to by buffers remains valid
3194 until the completion handler is called.
3196 @param handler The handler to be called when the write operation
3197 completes. Copies will be made of the handler as required. The
3198 function signature of the handler must be:
3201 error_code const& ec, // Result of operation
3202 std::size_t bytes_transferred // Number of bytes written from the
3203 // buffers. If an error occurred,
3204 // this will be less than the sum
3205 // of the buffer sizes.
3208 Regardless of whether the asynchronous operation completes
3209 immediately or not, the handler will not be invoked from within
3210 this function. Invocation of the handler will be performed in a
3211 manner equivalent to using `boost::asio::io_context::post`.
3214 class ConstBufferSequence,
3216 BOOST_ASIO_INITFN_RESULT_TYPE(
3217 WriteHandler, void(error_code, std::size_t))
3219 ConstBufferSequence const& buffers,
3220 WriteHandler&& handler);
3222 /** Write partial message data on the stream.
3224 This function is used to write some or all of a message's
3225 payload to the stream. The call will block until one of the
3226 following conditions is true:
3228 @li A frame is sent.
3230 @li Message data is transferred to the write buffer.
3232 @li An error occurs.
3234 This operation is implemented in terms of one or more calls
3235 to the stream's `write_some` function.
3237 If this is the beginning of a new message, the message opcode
3238 will be set to text or binary as per the current setting of
3239 the @ref binary option. The actual payload sent may be
3240 transformed as per the WebSocket protocol settings.
3242 @param fin `true` if this is the last part of the message.
3244 @param buffers The input buffer sequence holding the data to write.
3246 @return The number of bytes written from the buffers.
3247 If an error occurred, this will be less than the sum
3248 of the buffer sizes.
3250 @throws system_error Thrown on failure.
3252 template<class ConstBufferSequence>
3254 write_some(bool fin, ConstBufferSequence const& buffers);
3256 /** Write partial message data on the stream.
3258 This function is used to write some or all of a message's
3259 payload to the stream. The call will block until one of the
3260 following conditions is true:
3262 @li A frame is sent.
3264 @li Message data is transferred to the write buffer.
3266 @li An error occurs.
3268 This operation is implemented in terms of one or more calls
3269 to the stream's `write_some` function.
3271 If this is the beginning of a new message, the message opcode
3272 will be set to text or binary as per the current setting of
3273 the @ref binary option. The actual payload sent may be
3274 transformed as per the WebSocket protocol settings.
3276 @param fin `true` if this is the last part of the message.
3278 @param buffers The input buffer sequence holding the data to write.
3280 @param ec Set to indicate what error occurred, if any.
3282 @return The number of bytes written from the buffers.
3283 If an error occurred, this will be less than the sum
3284 of the buffer sizes.
3286 @return The number of bytes consumed in the input buffers.
3288 template<class ConstBufferSequence>
3290 write_some(bool fin,
3291 ConstBufferSequence const& buffers, error_code& ec);
3293 /** Start an asynchronous operation to send a message frame on the stream.
3295 This function is used to asynchronously write a message frame
3296 on the stream. This function call always returns immediately.
3297 The asynchronous operation will continue until one of the following
3300 @li The entire frame is sent.
3302 @li An error occurs.
3304 This operation is implemented in terms of one or more calls
3305 to the next layer's `async_write_some` functions, and is known
3306 as a <em>composed operation</em>. The actual payload sent
3307 may be transformed as per the WebSocket protocol settings. The
3308 program must ensure that the stream performs no other write
3309 operations (such as stream::async_write, stream::async_write_some,
3310 or stream::async_close).
3312 If this is the beginning of a new message, the message opcode
3313 will be set to text or binary as per the current setting of
3314 the @ref binary option. The actual payload sent may be
3315 transformed as per the WebSocket protocol settings.
3317 @param fin `true` if this is the last part of the message.
3319 @param buffers A object meeting the requirements of
3320 ConstBufferSequence which holds the payload data before any
3321 masking or compression. Although the buffers object may be copied
3322 as necessary, ownership of the underlying buffers is retained by
3323 the caller, which must guarantee that they remain valid until
3324 the handler is called.
3326 @param handler The handler to be called when the write completes.
3327 Copies will be made of the handler as required. The equivalent
3328 function signature of the handler must be:
3330 error_code const& ec, // Result of operation
3331 std::size_t bytes_transferred // Number of bytes written from the
3332 // buffers. If an error occurred,
3333 // this will be less than the sum
3334 // of the buffer sizes.
3337 template<class ConstBufferSequence, class WriteHandler>
3338 BOOST_ASIO_INITFN_RESULT_TYPE(
3339 WriteHandler, void(error_code, std::size_t))
3340 async_write_some(bool fin,
3341 ConstBufferSequence const& buffers, WriteHandler&& handler);
3344 template<class, class> class accept_op;
3345 template<class> class close_op;
3346 template<class> class fail_op;
3347 template<class> class handshake_op;
3348 template<class> class ping_op;
3349 template<class> class read_fh_op;
3350 template<class, class> class read_some_op;
3351 template<class, class> class read_op;
3352 template<class> class response_op;
3353 template<class, class> class write_some_op;
3354 template<class, class> class write_op;
3356 static void default_decorate_req(request_type&) {}
3357 static void default_decorate_res(response_type&) {}
3359 void open(role_type role);
3365 check_open(error_code& ec)
3367 if(status_ != status::open)
3369 ec = boost::asio::error::operation_aborted;
3372 ec.assign(0, ec.category());
3377 check_ok(error_code& ec)
3381 if(status_ != status::closed)
3382 status_ = status::failed;
3388 template<class DynamicBuffer>
3390 parse_fh(detail::frame_header& fh,
3391 DynamicBuffer& b, close_code& code);
3393 template<class DynamicBuffer>
3395 write_close(DynamicBuffer& b, close_reason const& rc);
3397 template<class DynamicBuffer>
3399 write_ping(DynamicBuffer& b,
3400 detail::opcode op, ping_data const& data);
3402 template<class Decorator>
3404 build_request(detail::sec_ws_key_type& key,
3407 Decorator const& decorator);
3409 template<class Body,
3410 class Allocator, class Decorator>
3412 build_response(http::request<Body,
3413 http::basic_fields<Allocator>> const& req,
3414 Decorator const& decorator);
3417 on_response(response_type const& resp,
3418 detail::sec_ws_key_type const& key, error_code& ec);
3420 template<class Decorator>
3422 do_accept(Decorator const& decorator,
3425 template<class Body, class Allocator,
3428 do_accept(http::request<Body,
3429 http::basic_fields<Allocator>> const& req,
3430 Decorator const& decorator, error_code& ec);
3432 template<class RequestDecorator>
3434 do_handshake(response_type* res_p,
3435 string_view host, string_view target,
3436 RequestDecorator const& decorator,
3450 #include <boost/beast/websocket/impl/accept.ipp>
3451 #include <boost/beast/websocket/impl/close.ipp>
3452 #include <boost/beast/websocket/impl/handshake.ipp>
3453 #include <boost/beast/websocket/impl/ping.ipp>
3454 #include <boost/beast/websocket/impl/read.ipp>
3455 #include <boost/beast/websocket/impl/stream.ipp>
3456 #include <boost/beast/websocket/impl/write.ipp>