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
19 namespace boost {
20 namespace beast {
21 namespace 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 @param role The role of the local endpoint
33
34 @param socket The socket to tear down.
35
36 @param ec Set to the error if any occurred.
37 */
38 template<class Socket>
39 void
teardown(role_type role,Socket & socket,error_code & ec)40 teardown(
41 role_type role,
42 Socket& socket,
43 error_code& ec)
44 {
45 boost::ignore_unused(role, socket, ec);
46 /*
47 If you are trying to use OpenSSL and this goes off, you need to
48 add an include for <boost/beast/websocket/ssl.hpp>.
49
50 If you are creating an instance of beast::websocket::stream with your
51 own user defined type, you must provide an overload of teardown with
52 the corresponding signature (including the role_type).
53 */
54 static_assert(sizeof(Socket)==-1,
55 "Unknown Socket type in teardown.");
56 }
57
58 /** Start tearing down a connection.
59
60 This begins tearing down a connection asynchronously.
61 The implementation will call the overload of this function
62 based on the `Socket` parameter used to consruct the socket.
63 When `Stream` is a user defined type, and not a
64 `net::ip::tcp::socket` or any `net::ssl::stream`,
65 callers are responsible for providing a suitable overload
66 of this function.
67
68 @param role The role of the local endpoint
69
70 @param socket The socket to tear down.
71
72 @param handler The completion handler to invoke when the operation
73 completes. The implementation takes ownership of the handler by
74 performing a decay-copy. The equivalent function signature of
75 the handler must be:
76 @code
77 void handler(
78 error_code const& error // result of operation
79 );
80 @endcode
81 Regardless of whether the asynchronous operation completes
82 immediately or not, the handler will not be invoked from within
83 this function. Invocation of the handler will be performed in a
84 manner equivalent to using `net::post`.
85
86 */
87 template<
88 class Socket,
89 class TeardownHandler>
90 void
async_teardown(role_type role,Socket & socket,TeardownHandler && handler)91 async_teardown(
92 role_type role,
93 Socket& socket,
94 TeardownHandler&& handler)
95 {
96 boost::ignore_unused(role, socket, handler);
97 /*
98 If you are trying to use OpenSSL and this goes off, you need to
99 add an include for <boost/beast/websocket/ssl.hpp>.
100
101 If you are creating an instance of beast::websocket::stream with your
102 own user defined type, you must provide an overload of teardown with
103 the corresponding signature (including the role_type).
104 */
105 static_assert(sizeof(Socket)==-1,
106 "Unknown Socket type in async_teardown.");
107 }
108
109 } // websocket
110
111 //------------------------------------------------------------------------------
112
113 namespace websocket {
114
115 /** Tear down a `net::ip::tcp::socket`.
116
117 This tears down a connection. The implementation will call
118 the overload of this function based on the `Stream` parameter
119 used to consruct the socket. When `Stream` is a user defined
120 type, and not a `net::ip::tcp::socket` or any
121 `net::ssl::stream`, callers are responsible for
122 providing a suitable overload of this function.
123
124 @param role The role of the local endpoint
125
126 @param socket The socket to tear down.
127
128 @param ec Set to the error if any occurred.
129 */
130 template<class Protocol, class Executor>
131 void
132 teardown(
133 role_type role,
134 net::basic_stream_socket<
135 Protocol, Executor>& socket,
136 error_code& ec);
137
138 /** Start tearing down a `net::ip::tcp::socket`.
139
140 This begins tearing down a connection asynchronously.
141 The implementation will call the overload of this function
142 based on the `Stream` parameter used to consruct the socket.
143 When `Stream` is a user defined type, and not a
144 `net::ip::tcp::socket` or any `net::ssl::stream`,
145 callers are responsible for providing a suitable overload
146 of this function.
147
148 @param role The role of the local endpoint
149
150 @param socket The socket to tear down.
151
152 @param handler The completion handler to invoke when the operation
153 completes. The implementation takes ownership of the handler by
154 performing a decay-copy. The equivalent function signature of
155 the handler must be:
156 @code
157 void handler(
158 error_code const& error // result of operation
159 );
160 @endcode
161 Regardless of whether the asynchronous operation completes
162 immediately or not, the handler will not be invoked from within
163 this function. Invocation of the handler will be performed in a
164 manner equivalent to using `net::post`.
165
166 */
167 template<
168 class Protocol, class Executor,
169 class TeardownHandler>
170 void
171 async_teardown(
172 role_type role,
173 net::basic_stream_socket<
174 Protocol, Executor>& socket,
175 TeardownHandler&& handler);
176
177 } // websocket
178 } // beast
179 } // boost
180
181 #include <boost/beast/websocket/impl/teardown.hpp>
182
183 #endif
184