1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[/-----------------------------------------------------------------------------] 11 12[section:decorator Decorator] 13 14For programs which need to modify either the outgoing WebSocket HTTP Upgrade 15request, the outgoing WebSocket HTTP Upgrade response, or both, the stream 16supports an optional property called a ['decorator]. This is a function 17pointer or callable object which is invoked before the implementation 18sends an HTTP message. The decorator receives a modifiable reference to 19the message, allowing for modifications. The interface to this system 20uses: 21 22[table WebSocket Decorator Interface 23[[Name][Description]] 24[[ 25 [link beast.ref.boost__beast__websocket__request_type `request_type`] 26][ 27 This is the type of the object passed to the decorator to 28 represent HTTP Upgrade requests. 29]] 30[[ 31 [link beast.ref.boost__beast__websocket__response_type `response_type`] 32][ 33 This is the type of the object passed to the decorator to 34 represent HTTP Upgrade response. 35]] 36[[ 37 [link beast.ref.boost__beast__websocket__stream_base__decorator `stream_base::decorator`] 38][ 39 Objects of this type are used to hold a decorator to be 40 set on the stream using `set_option`. 41]] 42[[ 43 [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`] 44][ 45 This function is used to set a `stream_base::decorator` on the stream. 46]] 47] 48 49This declares a normal function which decorates outgoing HTTP requests: 50 51[code_websocket_3_1] 52 53When using a decorator, it must be set on the stream before any handshaking 54takes place. This sets the decorator on the stream, to be used for all 55subsequent calls to accept or handshake: 56 57[code_websocket_3_2] 58 59Alternatively, a function object may be used. Small function objects will 60not incur a memory allocation. The follow code declares and sets a function 61object as a decorator: 62 63[code_websocket_3_3] 64 65A lambda may be used in place of a named function object: 66 67[code_websocket_3_4] 68 69It also possible for a single decorator to handle both requests and 70responses, if it is overloaded for both types either as a generic 71lambda (C++14 and later) or as a class as shown here: 72 73[code_websocket_3_5] 74 75The implementation takes ownership by decay-copy of the invocable object 76used as the decorator. Move-only types are possible: 77 78[code_websocket_3_6] 79 80[important 81 Undefined behavior results if the decorator modifies the fields 82 specific to perform the WebSocket Upgrade, such as the Upgrade 83 or Connection fields. 84] 85 86[endsect] 87