87 lines
2.7 KiB
Plaintext
87 lines
2.7 KiB
Plaintext
[/
|
|
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]
|