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[section Teardown] 11 12The WebSocket protocol requirements described in rfc6455 section 7.1.1 13outline an operation described as 14[@https://tools.ietf.org/html/rfc6455#section-7.1.1 ['Close the WebSocket Connection]]. 15This operation cleanly discards bytes remaining at receiving endpoints 16and also closes the underlying TCP/IP connection. Orderly shutdowns are 17always preferred; for TLS or SSL streams, a protocol-level shutdown is 18desired. This presents a small issue for the 19[link beast.ref.boost__beast__websocket__stream `stream`] 20implementation: the stream's `NextLayer` template type requires only 21__SyncStream__ or __AsyncStream__, but those concepts do not support 22the operations to shut down the connection. 23 24To enable the implementation to perform the shutdown components of the 25close operation, the library exposes two customization points expressed 26as free functions associated with the next layer type: 27 28* [link beast.ref.boost__beast__websocket__teardown `teardown`]: Overloads 29 of this function drain and shut down a stream synchronously. 30 31* [link beast.ref.boost__beast__websocket__teardown `async_teardown`]: 32 Overloads of this function drain and shut down a stream asynchronously. 33 34The implementation provides suitable overloads of the teardown 35customization points when websocket streams are instantiated using the 36Asio types __socket__ or __ssl_stream__ for the next layer. In this 37case no user action is required. However, when the websocket stream is 38instantiated for a user-defined type, compile errors will result if the 39customization points are not provided for the user defined type. 40Furthermore, user-defined types that wrap one of the Asio objects 41mentioned earlier may wish to invoke a teardown customization point 42for the wrapped object. This is how those tasks are accomplished. 43 44[heading User-defined Teardown] 45 46To provide overloads of teardown for a user-defined type, simply declare 47the two free functions with the correct signature, accepting a reference 48to the user-defined type as the stream parameter: 49 50[code_websocket_7_1] 51 52When the implementation invokes the asynchronous teardown function, it 53always uses an invokable completion handler. It is not necessary 54to specify the return type customization when creating user-defined 55overloads of `async_teardown`. 56 57[heading Invoking Teardown] 58 59To invoke the customization point, first bring the default implementation 60into scope with a `using` statement. Then call the customization point 61without namespace qualification, allowing argument-dependent lookup to 62take effect: 63 64[code_websocket_7_2] 65 66[endsect] 67