123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566 |
- [/
- 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 Teardown]
- The WebSocket protocol requirements described in rfc6455 section 7.1.1
- outline an operation described as
- [@https://tools.ietf.org/html/rfc6455#section-7.1.1 ['Close the WebSocket Connection]].
- This operation cleanly discards bytes remaining at receiving endpoints
- and also closes the underlying TCP/IP connection. Orderly shutdowns are
- always preferred; for TLS or SSL streams, a protocol-level shutdown is
- desired. This presents a small issue for the
- [link beast.ref.boost__beast__websocket__stream `stream`]
- implementation: the stream's `NextLayer` template type requires only
- __SyncStream__ or __AsyncStream__, but those concepts do not support
- the operations to shut down the connection.
- To enable the implementation to perform the shutdown components of the
- close operation, the library exposes two customization points expressed
- as free functions associated with the next layer type:
- * [link beast.ref.boost__beast__websocket__teardown `teardown`]: Overloads
- of this function drain and shut down a stream synchronously.
- * [link beast.ref.boost__beast__websocket__teardown `async_teardown`]:
- Overloads of this function drain and shut down a stream asynchronously.
- The implementation provides suitable overloads of the teardown
- customization points when websocket streams are instantiated using the
- Asio types __socket__ or __ssl_stream__ for the next layer. In this
- case no user action is required. However, when the websocket stream is
- instantiated for a user-defined type, compile errors will result if the
- customization points are not provided for the user defined type.
- Furthermore, user-defined types that wrap one of the Asio objects
- mentioned earlier may wish to invoke a teardown customization point
- for the wrapped object. This is how those tasks are accomplished.
- [heading User-defined Teardown]
- To provide overloads of teardown for a user-defined type, simply declare
- the two free functions with the correct signature, accepting a reference
- to the user-defined type as the stream parameter:
- [code_websocket_7_1]
- When the implementation invokes the asynchronous teardown function, it
- always uses an invokable completion handler. It is not necessary
- to specify the return type customization when creating user-defined
- overloads of `async_teardown`.
- [heading Invoking Teardown]
- To invoke the customization point, first bring the default implementation
- into scope with a `using` statement. Then call the customization point
- without namespace qualification, allowing argument-dependent lookup to
- take effect:
- [code_websocket_7_2]
- [endsect]
|