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#ifndef BOOST_BEAST_WEBSOCKET_TEARDOWN_HPP
11#define BOOST_BEAST_WEBSOCKET_TEARDOWN_HPP
12
13#include <boost/beast/core/detail/config.hpp>
14#include <boost/beast/core/error.hpp>
15#include <boost/beast/core/role.hpp>
16#include <boost/asio/basic_stream_socket.hpp>
17#include <type_traits>
18
19namespace boost {
20namespace beast {
21namespace websocket {
22
23/** Tear down a connection.
24
25 This tears down a connection. The implementation will call
26 the overload of this function based on the `Socket` parameter
27 used to consruct the socket. When `Socket` is a user defined
28 type, and not a `net::ip::tcp::socket` or any
29 `net::ssl::stream`, callers are responsible for
30 providing a suitable overload of this function.
31
32 @note
33
34 This function serves as a customization point and is not intended
35 to be called directly.
36
37 @param role The role of the local endpoint
38
39 @param socket The socket to tear down.
40
41 @param ec Set to the error if any occurred.
42*/
43template<class Socket>
44void
45teardown(
46 role_type role,
47 Socket& socket,
48 error_code& ec)
49{
50 boost::ignore_unused(role, socket, ec);
51/*
52 If you are trying to use OpenSSL and this goes off, you need to
53 add an include for <boost/beast/websocket/ssl.hpp>.
54
55 If you are creating an instance of beast::websocket::stream with your
56 own user defined type, you must provide an overload of teardown with
57 the corresponding signature (including the role_type).
58*/
59 static_assert(sizeof(Socket)==-1,
60 "Unknown Socket type in teardown.");
61}
62
63/** Start tearing down a connection.
64
65 This begins tearing down a connection asynchronously.
66 The implementation will call the overload of this function
67 based on the `Socket` parameter used to consruct the socket.
68 When `Stream` is a user defined type, and not a
69 `net::ip::tcp::socket` or any `net::ssl::stream`,
70 callers are responsible for providing a suitable overload
71 of this function.
72
73 @note
74
75 This function serves as a customization point and is not intended
76 to be called directly.
77
78 @param role The role of the local endpoint
79
80 @param socket The socket to tear down.
81
82 @param handler The completion handler to invoke when the operation
83 completes. The implementation takes ownership of the handler by
84 performing a decay-copy. The equivalent function signature of
85 the handler must be:
86 @code
87 void handler(
88 error_code const& error // result of operation
89 );
90 @endcode
91 If the handler has an associated immediate executor,
92 an immediate completion will be dispatched to it.
93 Otherwise, the handler will not be invoked from within
94 this function. Invocation of the handler will be performed in a
95 manner equivalent to using `net::post`.
96
97*/
98template<
99 class Socket,
100 class TeardownHandler>
101void
102async_teardown(
103 role_type role,
104 Socket& socket,
105 TeardownHandler&& handler)
106{
107 boost::ignore_unused(role, socket, handler);
108/*
109 If you are trying to use OpenSSL and this goes off, you need to
110 add an include for <boost/beast/websocket/ssl.hpp>.
111
112 If you are creating an instance of beast::websocket::stream with your
113 own user defined type, you must provide an overload of teardown with
114 the corresponding signature (including the role_type).
115*/
116 static_assert(sizeof(Socket)==-1,
117 "Unknown Socket type in async_teardown.");
118}
119
120} // websocket
121
122//------------------------------------------------------------------------------
123
124namespace websocket {
125
126/** Tear down a `net::ip::tcp::socket`.
127
128 This tears down a connection. The implementation will call
129 the overload of this function based on the `Stream` parameter
130 used to consruct the socket. When `Stream` is a user defined
131 type, and not a `net::ip::tcp::socket` or any
132 `net::ssl::stream`, callers are responsible for
133 providing a suitable overload of this function.
134
135 @note
136
137 This function serves as a customization point and is not intended
138 to be called directly.
139
140 @param role The role of the local endpoint
141
142 @param socket The socket to tear down.
143
144 @param ec Set to the error if any occurred.
145*/
146template<class Protocol, class Executor>
147void
148teardown(
149 role_type role,
150 net::basic_stream_socket<
151 Protocol, Executor>& socket,
152 error_code& ec);
153
154/** Start tearing down a `net::ip::tcp::socket`.
155
156 This begins tearing down a connection asynchronously.
157 The implementation will call the overload of this function
158 based on the `Stream` parameter used to consruct the socket.
159 When `Stream` is a user defined type, and not a
160 `net::ip::tcp::socket` or any `net::ssl::stream`,
161 callers are responsible for providing a suitable overload
162 of this function.
163
164 @note
165
166 This function serves as a customization point and is not intended
167 to be called directly.
168
169 @param role The role of the local endpoint
170
171 @param socket The socket to tear down.
172
173 @param handler The completion handler to invoke when the operation
174 completes. The implementation takes ownership of the handler by
175 performing a decay-copy. The equivalent function signature of
176 the handler must be:
177 @code
178 void handler(
179 error_code const& error // result of operation
180 );
181 @endcode
182 If the handler has an associated immediate executor,
183 an immediate completion will be dispatched to it.
184 Otherwise, the handler will not be invoked from within
185 this function. Invocation of the handler will be performed in a
186 manner equivalent to using `net::post`.
187
188 @par Per-Operation Cancellation
189
190 This asynchronous operation supports cancellation for the following
191 net::cancellation_type values:
192
193 @li @c net::cancellation_type::terminal
194 @li @c net::cancellation_type::partial
195 @li @c net::cancellation_type::total
196
197 if they are also supported by the socket's @c async_wait operation.
198
199*/
200template<
201 class Protocol, class Executor,
202 class TeardownHandler>
203void
204async_teardown(
205 role_type role,
206 net::basic_stream_socket<
207 Protocol, Executor>& socket,
208 TeardownHandler&& handler);
209
210} // websocket
211} // beast
212} // boost
213
214#include <boost/beast/websocket/impl/teardown.hpp>
215
216#endif
217

source code of boost/libs/beast/include/boost/beast/websocket/teardown.hpp