1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586 |
- [/
- 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
- ]
- [/-----------------------------------------------------------------------------]
- [section:decorator Decorator]
- For programs which need to modify either the outgoing WebSocket HTTP Upgrade
- request, the outgoing WebSocket HTTP Upgrade response, or both, the stream
- supports an optional property called a ['decorator]. This is a function
- pointer or callable object which is invoked before the implementation
- sends an HTTP message. The decorator receives a modifiable reference to
- the message, allowing for modifications. The interface to this system
- uses:
- [table WebSocket Decorator Interface
- [[Name][Description]]
- [[
- [link beast.ref.boost__beast__websocket__request_type `request_type`]
- ][
- This is the type of the object passed to the decorator to
- represent HTTP Upgrade requests.
- ]]
- [[
- [link beast.ref.boost__beast__websocket__response_type `response_type`]
- ][
- This is the type of the object passed to the decorator to
- represent HTTP Upgrade response.
- ]]
- [[
- [link beast.ref.boost__beast__websocket__stream_base__decorator `stream_base::decorator`]
- ][
- Objects of this type are used to hold a decorator to be
- set on the stream using `set_option`.
- ]]
- [[
- [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`]
- ][
- This function is used to set a `stream_base::decorator` on the stream.
- ]]
- ]
- This declares a normal function which decorates outgoing HTTP requests:
- [code_websocket_3_1]
- When using a decorator, it must be set on the stream before any handshaking
- takes place. This sets the decorator on the stream, to be used for all
- subsequent calls to accept or handshake:
- [code_websocket_3_2]
- Alternatively, a function object may be used. Small function objects will
- not incur a memory allocation. The follow code declares and sets a function
- object as a decorator:
- [code_websocket_3_3]
- A lambda may be used in place of a named function object:
- [code_websocket_3_4]
- It also possible for a single decorator to handle both requests and
- responses, if it is overloaded for both types either as a generic
- lambda (C++14 and later) or as a class as shown here:
- [code_websocket_3_5]
- The implementation takes ownership by decay-copy of the invocable object
- used as the decorator. Move-only types are possible:
- [code_websocket_3_6]
- [important
- Undefined behavior results if the decorator modifies the fields
- specific to perform the WebSocket Upgrade, such as the Upgrade
- or Connection fields.
- ]
- [endsect]
|