1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776 |
- //
- // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
- //
- // Distributed under the Boost Software License, Version 1.0. (See accompanying
- // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- //
- // Official repository: https://github.com/boostorg/beast
- //
- #ifndef BOOST_BEAST_WEBSOCKET_STREAM_HPP
- #define BOOST_BEAST_WEBSOCKET_STREAM_HPP
- #include <boost/beast/core/detail/config.hpp>
- #include <boost/beast/websocket/error.hpp>
- #include <boost/beast/websocket/option.hpp>
- #include <boost/beast/websocket/rfc6455.hpp>
- #include <boost/beast/websocket/stream_base.hpp>
- #include <boost/beast/websocket/stream_fwd.hpp>
- #include <boost/beast/websocket/detail/hybi13.hpp>
- #include <boost/beast/websocket/detail/impl_base.hpp>
- #include <boost/beast/websocket/detail/pmd_extension.hpp>
- #include <boost/beast/websocket/detail/prng.hpp>
- #include <boost/beast/core/role.hpp>
- #include <boost/beast/core/stream_traits.hpp>
- #include <boost/beast/core/string.hpp>
- #include <boost/beast/http/detail/type_traits.hpp>
- #include <boost/asio/async_result.hpp>
- #include <boost/asio/error.hpp>
- #include <boost/shared_ptr.hpp>
- #include <algorithm>
- #include <cstdint>
- #include <functional>
- #include <limits>
- #include <memory>
- #include <type_traits>
- #include <random>
- namespace boost {
- namespace beast {
- namespace websocket {
- /** The type of received control frame.
- Values of this type are passed to the control frame
- callback set using @ref stream::control_callback.
- */
- enum class frame_type
- {
- /// A close frame was received
- close,
- /// A ping frame was received
- ping,
- /// A pong frame was received
- pong
- };
- namespace detail {
- class frame_test;
- } // detail
- //--------------------------------------------------------------------
- /** Provides message-oriented functionality using WebSocket.
- The @ref stream class template provides asynchronous and blocking
- message-oriented functionality necessary for clients and servers
- to utilize the WebSocket protocol.
- For asynchronous operations, the application must ensure
- that they are are all performed within the same implicit
- or explicit strand.
- @par Thread Safety
- @e Distinct @e objects: Safe.@n
- @e Shared @e objects: Unsafe.
- The application must also ensure that all asynchronous
- operations are performed within the same implicit or explicit strand.
- @par Example
- To declare the @ref stream object with a @ref tcp_stream in a
- multi-threaded asynchronous program using a strand, you may write:
- @code
- websocket::stream<tcp_stream> ws{net::io_context::strand(ioc)};
- @endcode
- Alternatively, for a single-threaded or synchronous application
- you may write:
- @code
- websocket::stream<tcp_stream> ws(ioc);
- @endcode
- @tparam NextLayer The type representing the next layer, to which
- data will be read and written during operations. For synchronous
- operations, the type must support the <em>SyncStream</em> concept.
- For asynchronous operations, the type must support the
- <em>AsyncStream</em> concept.
- @tparam deflateSupported A `bool` indicating whether or not the
- stream will be capable of negotiating the permessage-deflate websocket
- extension. Note that even if this is set to `true`, the permessage
- deflate options (set by the caller at runtime) must still have the
- feature enabled for a successful negotiation to occur.
- @note A stream object must not be moved or destroyed while there
- are pending asynchronous operations associated with it.
- @par Concepts
- @li <em>AsyncStream</em>
- @li <em>DynamicBuffer</em>
- @li <em>SyncStream</em>
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">Websocket Close (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">WebSocket Ping (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">WebSocket Pong (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- template<
- class NextLayer,
- bool deflateSupported>
- class stream
- #if ! BOOST_BEAST_DOXYGEN
- : private stream_base
- #endif
- {
- struct impl_type;
- boost::shared_ptr<impl_type> impl_;
- using time_point = typename
- std::chrono::steady_clock::time_point;
- using control_cb_type =
- std::function<void(frame_type, string_view)>;
- friend class close_test;
- friend class frame_test;
- friend class ping_test;
- friend class read2_test;
- friend class read3_test;
- friend class stream_test;
- friend class write_test;
- /* The read buffer has to be at least as large
- as the largest possible control frame including
- the frame header.
- */
- static std::size_t constexpr max_control_frame_size = 2 + 8 + 4 + 125;
- static std::size_t constexpr tcp_frame_size = 1536;
- static time_point never() noexcept
- {
- return (time_point::max)();
- }
- public:
- /// Indicates if the permessage-deflate extension is supported
- using is_deflate_supported =
- std::integral_constant<bool, deflateSupported>;
- /// The type of the next layer.
- using next_layer_type =
- typename std::remove_reference<NextLayer>::type;
- /// The type of the executor associated with the object.
- using executor_type =
- beast::executor_type<next_layer_type>;
- /** Destructor
- Destroys the stream and all associated resources.
- @note A stream object must not be destroyed while there
- are pending asynchronous operations associated with it.
- */
- ~stream();
- /** Constructor
- If `NextLayer` is move constructible, this function
- will move-construct a new stream from the existing stream.
- After the move, the only valid operation on the moved-from
- object is destruction.
- */
- stream(stream&&) = default;
- /// Move assignment (deleted)
- stream& operator=(stream&&) = delete;
- /** Constructor
- This constructor creates a websocket stream and initializes
- the next layer object.
- @throws Any exceptions thrown by the NextLayer constructor.
- @param args The arguments to be passed to initialize the
- next layer object. The arguments are forwarded to the next
- layer's constructor.
- */
- template<class... Args>
- explicit
- stream(Args&&... args);
- //--------------------------------------------------------------------------
- /** Get the executor associated with the object.
- This function may be used to obtain the executor object that the
- stream uses to dispatch handlers for asynchronous operations.
- @return A copy of the executor that stream will use to dispatch handlers.
- */
- executor_type
- get_executor() noexcept;
- /** Get a reference to the next layer
- This function returns a reference to the next layer
- in a stack of stream layers.
- @return A reference to the next layer in the stack of
- stream layers.
- */
- next_layer_type&
- next_layer() noexcept;
- /** Get a reference to the next layer
- This function returns a reference to the next layer in a
- stack of stream layers.
- @return A reference to the next layer in the stack of
- stream layers.
- */
- next_layer_type const&
- next_layer() const noexcept;
- //--------------------------------------------------------------------------
- //
- // Observers
- //
- //--------------------------------------------------------------------------
- /** Returns `true` if the stream is open.
- The stream is open after a successful handshake, and when
- no error has occurred.
- */
- bool
- is_open() const noexcept;
- /** Returns `true` if the latest message data indicates binary.
- This function informs the caller of whether the last
- received message frame represents a message with the
- binary opcode.
- If there is no last message frame, the return value is
- undefined.
- */
- bool
- got_binary() const noexcept;
- /** Returns `true` if the latest message data indicates text.
- This function informs the caller of whether the last
- received message frame represents a message with the
- text opcode.
- If there is no last message frame, the return value is
- undefined.
- */
- bool
- got_text() const
- {
- return ! got_binary();
- }
- /// Returns `true` if the last completed read finished the current message.
- bool
- is_message_done() const noexcept;
- /** Returns the close reason received from the remote peer.
- This is only valid after a read completes with error::closed.
- */
- close_reason const&
- reason() const noexcept;
- /** Returns a suggested maximum buffer size for the next call to read.
- This function returns a reasonable upper limit on the number
- of bytes for the size of the buffer passed in the next call
- to read. The number is determined by the state of the current
- frame and whether or not the permessage-deflate extension is
- enabled.
- @param initial_size A non-zero size representing the caller's
- desired buffer size for when there is no information which may
- be used to calculate a more specific value. For example, when
- reading the first frame header of a message.
- */
- std::size_t
- read_size_hint(
- std::size_t initial_size = +tcp_frame_size) const;
- /** Returns a suggested maximum buffer size for the next call to read.
- This function returns a reasonable upper limit on the number
- of bytes for the size of the buffer passed in the next call
- to read. The number is determined by the state of the current
- frame and whether or not the permessage-deflate extension is
- enabled.
- @param buffer The buffer which will be used for reading. The
- implementation will query the buffer to obtain the optimum
- size of a subsequent call to `buffer.prepare` based on the
- state of the current frame, if any.
- */
- template<class DynamicBuffer
- #if ! BOOST_BEAST_DOXYGEN
- , class = typename std::enable_if<
- ! std::is_integral<DynamicBuffer>::value>::type
- #endif
- >
- std::size_t
- read_size_hint(
- DynamicBuffer& buffer) const;
- //--------------------------------------------------------------------------
- //
- // Settings
- //
- //--------------------------------------------------------------------------
- #if BOOST_BEAST_DOXYGEN
- template<class Option>
- void
- get_option(Option& opt);
- template<class Option>
- void
- set_option(Option opt);
- #else
- void set_option(decorator opt);
- void get_option(timeout& opt);
- void set_option(timeout const& opt);
- #endif
- /** Set the permessage-deflate extension options
- @throws invalid_argument if `deflateSupported == false`, and either
- `client_enable` or `server_enable` is `true`.
- */
- void
- set_option(permessage_deflate const& o);
- /// Get the permessage-deflate extension options
- void
- get_option(permessage_deflate& o);
- /** Set the automatic fragmentation option.
- Determines if outgoing message payloads are broken up into
- multiple pieces.
- When the automatic fragmentation size is turned on, outgoing
- message payloads are broken up into multiple frames no larger
- than the write buffer size.
- The default setting is to fragment messages.
- @param value A `bool` indicating if auto fragmentation should be on.
- @par Example
- Setting the automatic fragmentation option:
- @code
- ws.auto_fragment(true);
- @endcode
- */
- void
- auto_fragment(bool value);
- /// Returns `true` if the automatic fragmentation option is set.
- bool
- auto_fragment() const;
- /** Set the binary message write option.
- This controls whether or not outgoing message opcodes
- are set to binary or text. The setting is only applied
- at the start when a caller begins a new message. Changing
- the opcode after a message is started will only take effect
- after the current message being sent is complete.
- The default setting is to send text messages.
- @param value `true` if outgoing messages should indicate
- binary, or `false` if they should indicate text.
- @par Example
- Setting the message type to binary.
- @code
- ws.binary(true);
- @endcode
- */
- void
- binary(bool value);
- /// Returns `true` if the binary message write option is set.
- bool
- binary() const;
- /** Set a callback to be invoked on each incoming control frame.
- Sets the callback to be invoked whenever a ping, pong,
- or close control frame is received during a call to one
- of the following functions:
- @li @ref beast::websocket::stream::read
- @li @ref beast::websocket::stream::read_some
- @li @ref beast::websocket::stream::async_read
- @li @ref beast::websocket::stream::async_read_some
- Unlike completion handlers, the callback will be invoked
- for each control frame during a call to any synchronous
- or asynchronous read function. The operation is passive,
- with no associated error code, and triggered by reads.
- For close frames, the close reason code may be obtained by
- calling the function @ref reason.
- @param cb The function object to call, which must be
- invocable with this equivalent signature:
- @code
- void
- callback(
- frame_type kind, // The type of frame
- string_view payload // The payload in the frame
- );
- @endcode
- The implementation type-erases the callback which may require
- a dynamic allocation. To prevent the possibility of a dynamic
- allocation, use `std::ref` to wrap the callback.
- If the read operation which receives the control frame is
- an asynchronous operation, the callback will be invoked using
- the same method as that used to invoke the final handler.
- @note Incoming ping and close frames are automatically
- handled. Pings are responded to with pongs, and a close frame
- is responded to with a close frame leading to the closure of
- the stream. It is not necessary to manually send pings, pongs,
- or close frames from inside the control callback.
- Attempting to manually send a close frame from inside the
- control callback after receiving a close frame will result
- in undefined behavior.
- */
- void
- control_callback(std::function<void(frame_type, string_view)> cb);
- /** Reset the control frame callback.
- This function removes any previously set control frame callback.
- */
- void
- control_callback();
- /** Set the maximum incoming message size option.
- Sets the largest permissible incoming message size. Message
- frame fields indicating a size that would bring the total
- message size over this limit will cause a protocol failure.
- The default setting is 16 megabytes. A value of zero indicates
- a limit of the maximum value of a `std::uint64_t`.
- @par Example
- Setting the maximum read message size.
- @code
- ws.read_message_max(65536);
- @endcode
- @param amount The limit on the size of incoming messages.
- */
- void
- read_message_max(std::size_t amount);
- /// Returns the maximum incoming message size setting.
- std::size_t
- read_message_max() const;
- /** Set whether the PRNG is cryptographically secure
- This controls whether or not the source of pseudo-random
- numbers used to produce the masks required by the WebSocket
- protocol are of cryptographic quality. When the setting is
- `true`, a strong algorithm is used which cannot be guessed
- by observing outputs. When the setting is `false`, a much
- faster algorithm is used.
- Masking is only performed by streams operating in the client
- mode. For streams operating in the server mode, this setting
- has no effect.
- By default, newly constructed streams use a secure PRNG.
- If the WebSocket stream is used with an encrypted SSL or TLS
- next layer, if it is known to the application that intermediate
- proxies are not vulnerable to cache poisoning, or if the
- application is designed such that an attacker cannot send
- arbitrary inputs to the stream interface, then the faster
- algorithm may be used.
- For more information please consult the WebSocket protocol RFC.
- @param value `true` if the PRNG algorithm should be
- cryptographically secure.
- */
- void
- secure_prng(bool value);
- /** Set the write buffer size option.
- Sets the size of the write buffer used by the implementation to
- send frames. The write buffer is needed when masking payload data
- in the client role, compressing frames, or auto-fragmenting message
- data.
- Lowering the size of the buffer can decrease the memory requirements
- for each connection, while increasing the size of the buffer can reduce
- the number of calls made to the next layer to write data.
- The default setting is 4096. The minimum value is 8.
- The write buffer size can only be changed when the stream is not
- open. Undefined behavior results if the option is modified after a
- successful WebSocket handshake.
- @par Example
- Setting the write buffer size.
- @code
- ws.write_buffer_bytes(8192);
- @endcode
- @param amount The size of the write buffer in bytes.
- */
- void
- write_buffer_bytes(std::size_t amount);
- /// Returns the size of the write buffer.
- std::size_t
- write_buffer_bytes() const;
- /** Set the text message write option.
- This controls whether or not outgoing message opcodes
- are set to binary or text. The setting is only applied
- at the start when a caller begins a new message. Changing
- the opcode after a message is started will only take effect
- after the current message being sent is complete.
- The default setting is to send text messages.
- @param value `true` if outgoing messages should indicate
- text, or `false` if they should indicate binary.
- @par Example
- Setting the message type to text.
- @code
- ws.text(true);
- @endcode
- */
- void
- text(bool value);
- /// Returns `true` if the text message write option is set.
- bool
- text() const;
- /*
- timer settings
- * Timer is disabled
- * Close on timeout
- - no complete frame received, OR
- - no complete frame sent
- * Ping on timeout
- - ping on no complete frame received
- * if can't ping?
- */
- //--------------------------------------------------------------------------
- //
- // Handshaking (Client)
- //
- //--------------------------------------------------------------------------
- /** Perform the WebSocket handshake in the client role.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- @throws system_error Thrown on failure.
- @par Example
- @code
- ws.handshake("localhost", "/");
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- void
- handshake(
- string_view host,
- string_view target);
- /** Perform the WebSocket handshake in the client role.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param res The HTTP Upgrade response returned by the remote
- endpoint. The caller may use the response to access any
- additional information sent by the server.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- @throws system_error Thrown on failure.
- @par Example
- @code
- response_type res;
- ws.handshake(res, "localhost", "/");
- std::cout << res;
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- void
- handshake(
- response_type& res,
- string_view host,
- string_view target);
- /** Perform the WebSocket handshake in the client role.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- @param ec Set to indicate what error occurred, if any.
- @par Example
- @code
- error_code ec;
- ws.handshake("localhost", "/", ec);
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- void
- handshake(
- string_view host,
- string_view target,
- error_code& ec);
- /** Perform the WebSocket handshake in the client role.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param res The HTTP Upgrade response returned by the remote
- endpoint. The caller may use the response to access any
- additional information sent by the server.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- @param ec Set to indicate what error occurred, if any.
- @par Example
- @code
- error_code ec;
- response_type res;
- ws.handshake(res, "localhost", "/", ec);
- if(! ec)
- std::cout << res;
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- void
- handshake(
- response_type& res,
- string_view host,
- string_view target,
- error_code& ec);
- /** Perform the WebSocket handshake asynchronously in the client role.
- This initiating function is used to asynchronously begin performing the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. No other operation may be performed
- on the stream until this operation completes.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- The implementation will not access the string data after the
- initiating function returns.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- The implementation will not access the string data after the
- initiating function returns.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @par Example
- @code
- ws.async_handshake("localhost", "/",
- [](error_code ec)
- {
- if(ec)
- std::cerr << "Error: " << ec.message() << "\n";
- });
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 HandshakeHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
- async_handshake(
- string_view host,
- string_view target,
- HandshakeHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- /** Perform the WebSocket handshake asynchronously in the client role.
- This initiating function is used to asynchronously begin performing the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The request is sent and the response is received.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. No other operation may be performed
- on the stream until this operation completes.
- The handshake is successful if the received HTTP response
- indicates the upgrade was accepted by the server, represented by a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols.
- @param res The HTTP Upgrade response returned by the remote
- endpoint. The caller may use the response to access any
- additional information sent by the server. This object will
- be assigned before the completion handler is invoked.
- @param host The name of the remote host. This is required by
- the HTTP protocol to set the "Host" header field.
- The implementation will not access the string data after the
- initiating function returns.
- @param target The request-target, in origin-form. The server may use the
- target to distinguish different services on the same listening port.
- The implementation will not access the string data after the
- initiating function returns.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @par Example
- @code
- response_type res;
- ws.async_handshake(res, "localhost", "/",
- [&res](error_code ec)
- {
- if(ec)
- std::cerr << "Error: " << ec.message() << "\n";
- else
- std::cout << res;
- });
- @endcode
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.1">Websocket Opening Handshake Client Requirements (RFC6455)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host field (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-3.1.1">request-target (RFC7230)</a>
- @li <a href="https://tools.ietf.org/html/rfc7230#section-5.3.1">origin-form (RFC7230)</a>
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 HandshakeHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
- async_handshake(
- response_type& res,
- string_view host,
- string_view target,
- HandshakeHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- //
- // Handshaking (Server)
- //
- //--------------------------------------------------------------------------
- /** Perform the WebSocket handshake in the server role.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @throws system_error Thrown on failure.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- void
- accept();
- /** Read and respond to a WebSocket HTTP Upgrade request.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @param ec Set to indicate what error occurred, if any.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- void
- accept(error_code& ec);
- /** Read and respond to a WebSocket HTTP Upgrade request.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @param buffers Caller provided data that has already been
- received on the stream. The implementation will copy the
- caller provided data before the function returns.
- @throws system_error Thrown on failure.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<class ConstBufferSequence>
- #if BOOST_BEAST_DOXYGEN
- void
- #else
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
- #endif
- accept(ConstBufferSequence const& buffers);
- /** Read and respond to a WebSocket HTTP Upgrade request.
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @param buffers Caller provided data that has already been
- received on the stream. The implementation will copy the
- caller provided data before the function returns.
- @param ec Set to indicate what error occurred, if any.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<class ConstBufferSequence>
- #if BOOST_BEAST_DOXYGEN
- void
- #else
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
- #endif
- accept(
- ConstBufferSequence const& buffers,
- error_code& ec);
- /** Respond to a WebSocket HTTP Upgrade request
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not
- access this object from other threads.
- @throws system_error Thrown on failure.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<class Body, class Allocator>
- void
- accept(http::request<Body,
- http::basic_fields<Allocator>> const& req);
- /** Respond to a WebSocket HTTP Upgrade request
- This function is used to perform the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- The call blocks until one of the following conditions is true:
- @li The response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not
- access this object from other threads.
- @param ec Set to indicate what error occurred, if any.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<class Body, class Allocator>
- void
- accept(http::request<Body,
- http::basic_fields<Allocator>> const& req,
- error_code& ec);
- /** Perform the WebSocket handshake asynchronously in the server role.
- This initiating function is used to asynchronously begin performing the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. No other operation may be performed
- on the stream until this operation completes.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::async_read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept(
- AcceptHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- /** Perform the WebSocket handshake asynchronously in the server role.
- This initiating function is used to asynchronously begin performing the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. No other operation may be performed
- on the stream until this operation completes.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- If the request size exceeds the capacity of the stream's
- internal buffer, the error @ref error::buffer_overflow will be
- indicated. To handle larger requests, an application should
- read the HTTP request directly using @ref http::async_read and then
- pass the request to the appropriate overload of @ref accept or
- @ref async_accept
- @param buffers Caller provided data that has already been
- received on the stream. This may be used for implementations
- allowing multiple protocols on the same stream. The
- buffered data will first be applied to the handshake, and
- then to received WebSocket frames. The implementation will
- copy the caller provided data before the function returns.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<
- class ConstBufferSequence,
- BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept(
- ConstBufferSequence const& buffers,
- AcceptHandler&& handler =
- net::default_completion_token_t<
- executor_type>{}
- #ifndef BOOST_BEAST_DOXYGEN
- , typename std::enable_if<
- ! http::detail::is_header<
- ConstBufferSequence>::value>::type* = 0
- #endif
- );
- /** Perform the WebSocket handshake asynchronously in the server role.
- This initiating function is used to asynchronously begin performing the
- <a href="https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake">WebSocket handshake</a>,
- required before messages can be sent and received. During the handshake,
- the client sends the Websocket Upgrade HTTP request, and the server
- replies with an HTTP response indicating the result of the handshake.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The request is received and the response is sent.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. No other operation may be performed
- on the stream until this operation completes.
- If a valid upgrade request is received, an HTTP response with a
- <a href="https://tools.ietf.org/html/rfc7230#section-3.1.2">status-code</a>
- of @ref beast::http::status::switching_protocols is sent to
- the peer, otherwise a non-successful error is associated with
- the operation.
- @param req An object containing the HTTP Upgrade request.
- Ownership is not transferred, the implementation will not access
- this object from other threads.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-4.2">Websocket Opening Handshake Server Requirements (RFC6455)</a>
- */
- template<
- class Body, class Allocator,
- BOOST_BEAST_ASYNC_TPARAM1 AcceptHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept(
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- AcceptHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- //
- // Close Frames
- //
- //--------------------------------------------------------------------------
- /** Send a websocket close control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
- which begins the websocket closing handshake. The session ends when
- both ends of the connection have sent and received a close frame.
- The call blocks until one of the following conditions is true:
- @li The close frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- After beginning the closing handshake, the program should not write
- further message data, pings, or pongs. Instead, the program should
- continue reading message data until an error occurs. A read returning
- @ref error::closed indicates a successful connection closure.
- @param cr The reason for the close.
- If the close reason specifies a close code other than
- @ref beast::websocket::close_code::none, the close frame is
- sent with the close code and optional reason string. Otherwise,
- the close frame is sent with no payload.
- @throws system_error Thrown on failure.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
- */
- void
- close(close_reason const& cr);
- /** Send a websocket close control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
- which begins the websocket closing handshake. The session ends when
- both ends of the connection have sent and received a close frame.
- The call blocks until one of the following conditions is true:
- @li The close frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- After beginning the closing handshake, the program should not write
- further message data, pings, or pongs. Instead, the program should
- continue reading message data until an error occurs. A read returning
- @ref error::closed indicates a successful connection closure.
- @param cr The reason for the close.
- If the close reason specifies a close code other than
- @ref beast::websocket::close_code::none, the close frame is
- sent with the close code and optional reason string. Otherwise,
- the close frame is sent with no payload.
- @param ec Set to indicate what error occurred, if any.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
- */
- void
- close(close_reason const& cr, error_code& ec);
- /** Send a websocket close control frame asynchronously.
- This function is used to asynchronously send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>,
- which begins the websocket closing handshake. The session ends when
- both ends of the connection have sent and received a close frame.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The close frame finishes sending.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_write_some`
- function. No other operations except for message reading operations
- should be initiated on the stream after a close operation is started.
- After beginning the closing handshake, the program should not write
- further message data, pings, or pongs. Instead, the program should
- continue reading message data until an error occurs. A read returning
- @ref error::closed indicates a successful connection closure.
- @param cr The reason for the close.
- If the close reason specifies a close code other than
- @ref beast::websocket::close_code::none, the close frame is
- sent with the close code and optional reason string. Otherwise,
- the close frame is sent with no payload.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- @see
- @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 CloseHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(CloseHandler)
- async_close(
- close_reason const& cr,
- CloseHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- //
- // Ping/Pong Frames
- //
- //--------------------------------------------------------------------------
- /** Send a websocket ping control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
- which usually elicits an automatic pong control frame response from
- the peer.
- The call blocks until one of the following conditions is true:
- @li The ping frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- @param payload The payload of the ping message, which may be empty.
- @throws system_error Thrown on failure.
- */
- void
- ping(ping_data const& payload);
- /** Send a websocket ping control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
- which usually elicits an automatic pong control frame response from
- the peer.
- The call blocks until one of the following conditions is true:
- @li The ping frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- @param payload The payload of the ping message, which may be empty.
- @param ec Set to indicate what error occurred, if any.
- */
- void
- ping(ping_data const& payload, error_code& ec);
- /** Send a websocket ping control frame asynchronously.
- This function is used to asynchronously send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.2">ping frame</a>,
- which usually elicits an automatic pong control frame response from
- the peer.
- @li The ping frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_write_some`
- function. The program must ensure that no other calls to @ref ping,
- @ref pong, @ref async_ping, or @ref async_pong are performed until
- this operation completes.
- If a close frame is sent or received before the ping frame is
- sent, the error received by this completion handler will be
- `net::error::operation_aborted`.
- @param payload The payload of the ping message, which may be empty.
- The implementation will not access the contents of this object after
- the initiating function returns.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 WriteHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(WriteHandler)
- async_ping(
- ping_data const& payload,
- WriteHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- /** Send a websocket pong control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
- which is usually sent automatically in response to a ping frame
- from the remote peer.
- The call blocks until one of the following conditions is true:
- @li The pong frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- WebSocket allows pong frames to be sent at any time, without first
- receiving a ping. An unsolicited pong sent in this fashion may
- indicate to the remote peer that the connection is still active.
- @param payload The payload of the pong message, which may be empty.
- @throws system_error Thrown on failure.
- */
- void
- pong(ping_data const& payload);
- /** Send a websocket pong control frame.
- This function is used to send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
- which is usually sent automatically in response to a ping frame
- from the remote peer.
- The call blocks until one of the following conditions is true:
- @li The pong frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- WebSocket allows pong frames to be sent at any time, without first
- receiving a ping. An unsolicited pong sent in this fashion may
- indicate to the remote peer that the connection is still active.
- @param payload The payload of the pong message, which may be empty.
- @param ec Set to indicate what error occurred, if any.
- */
- void
- pong(ping_data const& payload, error_code& ec);
- /** Send a websocket pong control frame asynchronously.
- This function is used to asynchronously send a
- <a href="https://tools.ietf.org/html/rfc6455#section-5.5.3">pong frame</a>,
- which is usually sent automatically in response to a ping frame
- from the remote peer.
- @li The pong frame is written.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_write_some`
- function. The program must ensure that no other calls to @ref ping,
- @ref pong, @ref async_ping, or @ref async_pong are performed until
- this operation completes.
- If a close frame is sent or received before the pong frame is
- sent, the error received by this completion handler will be
- `net::error::operation_aborted`.
- WebSocket allows pong frames to be sent at any time, without first
- receiving a ping. An unsolicited pong sent in this fashion may
- indicate to the remote peer that the connection is still active.
- @param payload The payload of the pong message, which may be empty.
- The implementation will not access the contents of this object after
- the initiating function returns.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec // Result of operation
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- BOOST_BEAST_ASYNC_TPARAM1 WriteHandler =
- net::default_completion_token_t<executor_type>
- >
- BOOST_BEAST_ASYNC_RESULT1(WriteHandler)
- async_pong(
- ping_data const& payload,
- WriteHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- //
- // Reading
- //
- //--------------------------------------------------------------------------
- /** Read a complete message.
- This function is used to read a complete message.
- The call blocks until one of the following is true:
- @li A complete message is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to append message data to.
- @throws system_error Thrown on failure.
- */
- template<class DynamicBuffer>
- std::size_t
- read(DynamicBuffer& buffer);
- /** Read a complete message.
- This function is used to read a complete message.
- The call blocks until one of the following is true:
- @li A complete message is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to append message data to.
- @param ec Set to indicate what error occurred, if any.
- */
- template<class DynamicBuffer>
- std::size_t
- read(DynamicBuffer& buffer, error_code& ec);
- /** Read a complete message asynchronously.
- This function is used to asynchronously read a complete message.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li A complete message is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. The program must ensure that no other
- calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
- are performed until this operation completes.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- Until the operation completes, the implementation will read incoming
- control frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- Pong frames and close frames sent by the implementation while the
- read operation is outstanding do not prevent the application from
- also writing message data, sending pings, sending pongs, or sending
- close frames.
- @param buffer A dynamic buffer to append message data to.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec, // Result of operation
- std::size_t bytes_written // Number of bytes appended to buffer
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- class DynamicBuffer,
- BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
- net::default_completion_token_t<
- executor_type>>
- BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
- async_read(
- DynamicBuffer& buffer,
- ReadHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- /** Read some message data.
- This function is used to read some message data.
- The call blocks until one of the following is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to append message data to.
- @param limit An upper limit on the number of bytes this function
- will append into the buffer. If this value is zero, then a reasonable
- size will be chosen automatically.
- @throws system_error Thrown on failure.
- */
- template<class DynamicBuffer>
- std::size_t
- read_some(
- DynamicBuffer& buffer,
- std::size_t limit);
- /** Read some message data.
- This function is used to read some message data.
- The call blocks until one of the following is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffer A dynamic buffer to append message data to.
- @param limit An upper limit on the number of bytes this function
- will append into the buffer. If this value is zero, then a reasonable
- size will be chosen automatically.
- @param ec Set to indicate what error occurred, if any.
- */
- template<class DynamicBuffer>
- std::size_t
- read_some(
- DynamicBuffer& buffer,
- std::size_t limit,
- error_code& ec);
- /** Read some message data asynchronously.
- This function is used to asynchronously read some message data.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. The program must ensure that no other
- calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
- are performed until this operation completes.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- Until the operation completes, the implementation will read incoming
- control frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- Pong frames and close frames sent by the implementation while the
- read operation is outstanding do not prevent the application from
- also writing message data, sending pings, sending pongs, or sending
- close frames.
- @param buffer A dynamic buffer to append message data to.
- @param limit An upper limit on the number of bytes this function
- will append into the buffer. If this value is zero, then a reasonable
- size will be chosen automatically.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec, // Result of operation
- std::size_t bytes_written // Number of bytes appended to buffer
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- class DynamicBuffer,
- BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
- net::default_completion_token_t<
- executor_type>>
- BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
- async_read_some(
- DynamicBuffer& buffer,
- std::size_t limit,
- ReadHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- /** Read some message data.
- This function is used to read some message data.
- The call blocks until one of the following is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffers A buffer sequence to write message data into.
- The previous contents of the buffers will be overwritten, starting
- from the beginning.
- @throws system_error Thrown on failure.
- */
- template<class MutableBufferSequence>
- std::size_t
- read_some(
- MutableBufferSequence const& buffers);
- /** Read some message data.
- This function is used to read some message data.
- The call blocks until one of the following is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `read_some` and `write_some`
- functions.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- The function @ref is_message_done may be called to determine if the
- message received by the last read operation is complete.
- Until the call returns, the implementation will read incoming control
- frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket closing handshake is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- @return The number of message payload bytes appended to the buffer.
- @param buffers A buffer sequence to write message data into.
- The previous contents of the buffers will be overwritten, starting
- from the beginning.
- @param ec Set to indicate what error occurred, if any.
- */
- template<class MutableBufferSequence>
- std::size_t
- read_some(
- MutableBufferSequence const& buffers,
- error_code& ec);
- /** Read some message data asynchronously.
- This function is used to asynchronously read some message data.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li Some message data is received.
- @li A close frame is received. In this case the error indicated by
- the function will be @ref error::closed.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's `async_read_some`
- and `async_write_some` functions. The program must ensure that no other
- calls to @ref read, @ref read_some, @ref async_read, or @ref async_read_some
- are performed until this operation completes.
- Received message data is appended to the buffer.
- The functions @ref got_binary and @ref got_text may be used
- to query the stream and determine the type of the last received message.
- Until the operation completes, the implementation will read incoming
- control frames and handle them automatically as follows:
- @li The @ref control_callback will be invoked for each control frame.
- @li For each received ping frame, a pong frame will be
- automatically sent.
- @li If a close frame is received, the WebSocket close procedure is
- performed. In this case, when the function returns, the error
- @ref error::closed will be indicated.
- Pong frames and close frames sent by the implementation while the
- read operation is outstanding do not prevent the application from
- also writing message data, sending pings, sending pongs, or sending
- close frames.
- @param buffers A buffer sequence to write message data into.
- The previous contents of the buffers will be overwritten, starting
- from the beginning.
- The implementation will make copies of this object as needed, but
- but ownership of the underlying memory is not transferred. The
- caller is responsible for ensuring that the memory locations
- pointed to by the buffer sequence remain valid until the
- completion handler is called.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec, // Result of operation
- std::size_t bytes_written // Number of bytes written to the buffers
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- class MutableBufferSequence,
- BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
- net::default_completion_token_t<
- executor_type>>
- BOOST_BEAST_ASYNC_RESULT2(ReadHandler)
- async_read_some(
- MutableBufferSequence const& buffers,
- ReadHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //--------------------------------------------------------------------------
- //
- // Writing
- //
- //--------------------------------------------------------------------------
- /** Write a complete message.
- This function is used to write a complete message.
- The call blocks until one of the following is true:
- @li The message is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- The current setting of the @ref binary option controls
- whether the message opcode is set to text or binary. If the
- @ref auto_fragment option is set, the message will be split
- into one or more frames as necessary. The actual payload contents
- sent may be transformed as per the WebSocket protocol settings.
- @param buffers The buffers containing the message to send.
- @return The number of bytes sent from the buffers.
- @throws system_error Thrown on failure.
- */
- template<class ConstBufferSequence>
- std::size_t
- write(ConstBufferSequence const& buffers);
- /** Write a complete message.
- This function is used to write a complete message.
- The call blocks until one of the following is true:
- @li The complete message is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- The current setting of the @ref binary option controls
- whether the message opcode is set to text or binary. If the
- @ref auto_fragment option is set, the message will be split
- into one or more frames as necessary. The actual payload contents
- sent may be transformed as per the WebSocket protocol settings.
- @param buffers The buffers containing the message to send.
- @param ec Set to indicate what error occurred, if any.
- @return The number of bytes sent from the buffers.
- */
- template<class ConstBufferSequence>
- std::size_t
- write(ConstBufferSequence const& buffers, error_code& ec);
- /** Write a complete message asynchronously.
- This function is used to asynchronously write a complete message.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The complete message is written.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's
- `async_write_some` function. The program must ensure that no other
- calls to @ref write, @ref write_some, @ref async_write, or
- @ref async_write_some are performed until this operation completes.
- The current setting of the @ref binary option controls
- whether the message opcode is set to text or binary. If the
- @ref auto_fragment option is set, the message will be split
- into one or more frames as necessary. The actual payload contents
- sent may be transformed as per the WebSocket protocol settings.
- @param buffers A buffer sequence containing the entire message
- payload. The implementation will make copies of this object
- as needed, but ownership of the underlying memory is not
- transferred. The caller is responsible for ensuring that
- the memory locations pointed to by buffers remains valid
- until the completion handler is called.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec, // Result of operation
- std::size_t bytes_transferred // Number of bytes sent from the
- // buffers. If an error occurred,
- // this will be less than the buffer_size.
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- class ConstBufferSequence,
- BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
- net::default_completion_token_t<
- executor_type>>
- BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
- async_write(
- ConstBufferSequence const& buffers,
- WriteHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- /** Write some message data.
- This function is used to send part of a message.
- The call blocks until one of the following is true:
- @li The message data is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- If this is the beginning of a new message, the message opcode
- will be set to text or binary based on the current setting of
- the @ref binary (or @ref text) option. The actual payload sent
- may be transformed as per the WebSocket protocol settings.
- @param fin `true` if this is the last part of the message.
- @param buffers The buffers containing the message part to send.
- @return The number of bytes sent from the buffers.
- @throws system_error Thrown on failure.
- */
- template<class ConstBufferSequence>
- std::size_t
- write_some(bool fin, ConstBufferSequence const& buffers);
- /** Write some message data.
- This function is used to send part of a message.
- The call blocks until one of the following is true:
- @li The message data is written.
- @li An error occurs.
- The algorithm, known as a <em>composed operation</em>, is implemented
- in terms of calls to the next layer's `write_some` function.
- If this is the beginning of a new message, the message opcode
- will be set to text or binary based on the current setting of
- the @ref binary (or @ref text) option. The actual payload sent
- may be transformed as per the WebSocket protocol settings.
- @param fin `true` if this is the last part of the message.
- @param buffers The buffers containing the message part to send.
- @param ec Set to indicate what error occurred, if any.
- @return The number of bytes sent from the buffers.
- @return The number of bytes consumed in the input buffers.
- */
- template<class ConstBufferSequence>
- std::size_t
- write_some(bool fin,
- ConstBufferSequence const& buffers, error_code& ec);
- /** Write some message data asynchronously.
- This function is used to asynchronously write part of a message.
- This call always returns immediately. The asynchronous operation
- will continue until one of the following conditions is true:
- @li The message data is written.
- @li An error occurs.
- The algorithm, known as a <em>composed asynchronous operation</em>,
- is implemented in terms of calls to the next layer's
- `async_write_some` function. The program must ensure that no other
- calls to @ref write, @ref write_some, @ref async_write, or
- @ref async_write_some are performed until this operation completes.
- If this is the beginning of a new message, the message opcode
- will be set to text or binary based on the current setting of
- the @ref binary (or @ref text) option. The actual payload sent
- may be transformed as per the WebSocket protocol settings.
- @param fin `true` if this is the last part of the message.
- @param buffers The buffers containing the message part to send.
- The implementation will make copies of this object
- as needed, but ownership of the underlying memory is not
- transferred. The caller is responsible for ensuring that
- the memory locations pointed to by buffers remains valid
- until the completion handler is called.
- @param handler The completion handler to invoke when the operation
- completes. The implementation takes ownership of the handler by
- performing a decay-copy. The equivalent function signature of
- the handler must be:
- @code
- void handler(
- error_code const& ec, // Result of operation
- std::size_t bytes_transferred // Number of bytes sent from the
- // buffers. If an error occurred,
- // this will be less than the buffer_size.
- );
- @endcode
- Regardless of whether the asynchronous operation completes
- immediately or not, the handler will not be invoked from within
- this function. Invocation of the handler will be performed in a
- manner equivalent to using `net::post`.
- */
- template<
- class ConstBufferSequence,
- BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
- net::default_completion_token_t<
- executor_type>>
- BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
- async_write_some(
- bool fin,
- ConstBufferSequence const& buffers,
- WriteHandler&& handler =
- net::default_completion_token_t<
- executor_type>{});
- //
- // Deprecated
- //
- #if ! BOOST_BEAST_DOXYGEN
- template<class RequestDecorator>
- void
- handshake_ex(
- string_view host,
- string_view target,
- RequestDecorator const& decorator);
- template<class RequestDecorator>
- void
- handshake_ex(
- response_type& res,
- string_view host,
- string_view target,
- RequestDecorator const& decorator);
- template<class RequestDecorator>
- void
- handshake_ex(
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- error_code& ec);
- template<class RequestDecorator>
- void
- handshake_ex(
- response_type& res,
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- error_code& ec);
- template<class RequestDecorator, class HandshakeHandler>
- BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
- async_handshake_ex(
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- HandshakeHandler&& handler);
- template<class RequestDecorator, class HandshakeHandler>
- BOOST_BEAST_ASYNC_RESULT1(HandshakeHandler)
- async_handshake_ex(
- response_type& res,
- string_view host,
- string_view target,
- RequestDecorator const& decorator,
- HandshakeHandler&& handler);
- template<class ResponseDecorator>
- void
- accept_ex(ResponseDecorator const& decorator);
- template<class ResponseDecorator>
- void
- accept_ex(
- ResponseDecorator const& decorator,
- error_code& ec);
- template<class ConstBufferSequence,
- class ResponseDecorator>
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
- accept_ex(
- ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator);
- template<class ConstBufferSequence, class ResponseDecorator>
- typename std::enable_if<! http::detail::is_header<
- ConstBufferSequence>::value>::type
- accept_ex(
- ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator,
- error_code& ec);
- template<class Body, class Allocator,
- class ResponseDecorator>
- void
- accept_ex(http::request<Body,
- http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator);
- template<class Body, class Allocator,
- class ResponseDecorator>
- void
- accept_ex(http::request<Body,
- http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator,
- error_code& ec);
- template<
- class ResponseDecorator,
- class AcceptHandler>
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept_ex(
- ResponseDecorator const& decorator,
- AcceptHandler&& handler);
- template<
- class ConstBufferSequence,
- class ResponseDecorator,
- class AcceptHandler>
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept_ex(
- ConstBufferSequence const& buffers,
- ResponseDecorator const& decorator,
- AcceptHandler&& handler,
- typename std::enable_if<
- ! http::detail::is_header<
- ConstBufferSequence>::value>::type* = 0);
- template<
- class Body, class Allocator,
- class ResponseDecorator,
- class AcceptHandler>
- BOOST_BEAST_ASYNC_RESULT1(AcceptHandler)
- async_accept_ex(
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- ResponseDecorator const& decorator,
- AcceptHandler&& handler);
- #endif
- private:
- template<class, class> class accept_op;
- template<class> class close_op;
- template<class> class handshake_op;
- template<class> class ping_op;
- template<class> class idle_ping_op;
- template<class, class> class read_some_op;
- template<class, class> class read_op;
- template<class> class response_op;
- template<class, class> class write_some_op;
- template<class, class> class write_op;
- struct run_accept_op;
- struct run_close_op;
- struct run_handshake_op;
- struct run_ping_op;
- struct run_idle_ping_op;
- struct run_read_some_op;
- struct run_read_op;
- struct run_response_op;
- struct run_write_some_op;
- struct run_write_op;
- static void default_decorate_req(request_type&) {}
- static void default_decorate_res(response_type&) {}
- //
- // accept / handshake
- //
- template<class Buffers, class Decorator>
- void
- do_accept(
- Buffers const& buffers,
- Decorator const& decorator,
- error_code& ec);
- template<
- class Body, class Allocator,
- class Decorator>
- void
- do_accept(
- http::request<Body,
- http::basic_fields<Allocator>> const& req,
- Decorator const& decorator,
- error_code& ec);
- template<class RequestDecorator>
- void
- do_handshake(response_type* res_p,
- string_view host, string_view target,
- RequestDecorator const& decorator,
- error_code& ec);
- //
- // fail
- //
- void
- do_fail(
- std::uint16_t code,
- error_code ev,
- error_code& ec);
- };
- /** Manually provide a one-time seed to initialize the PRNG
- This function invokes the specified seed sequence to produce a seed
- suitable for use with the pseudo-random number generator used to
- create masks and perform WebSocket protocol handshakes.
- If a seed is not manually provided, the implementation will
- perform a one-time seed generation using `std::random_device`. This
- function may be used when the application runs in an environment
- where the random device is unreliable or does not provide sufficient
- entropy.
- @par Preconditions
- This function may not be called after any websocket @ref stream objects
- have been constructed.
- @param ss A reference to a `std::seed_seq` which will be used to seed
- the pseudo-random number generator. The seed sequence should have at
- least 256 bits of entropy.
- @see stream::secure_prng
- */
- inline
- void
- seed_prng(std::seed_seq& ss)
- {
- detail::prng_seed(&ss);
- }
- } // websocket
- } // beast
- } // boost
- #include <boost/beast/websocket/impl/stream_impl.hpp> // must be first
- #include <boost/beast/websocket/impl/accept.hpp>
- #include <boost/beast/websocket/impl/close.hpp>
- #include <boost/beast/websocket/impl/handshake.hpp>
- #include <boost/beast/websocket/impl/ping.hpp>
- #include <boost/beast/websocket/impl/read.hpp>
- #include <boost/beast/websocket/impl/stream.hpp>
- #include <boost/beast/websocket/impl/write.hpp>
- #endif
|