2 // windows/basic_overlapped_handle.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2020 Christopher M. Kohlhoff (chris at kohlhoff dot com)
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_ASIO_WINDOWS_BASIC_OVERLAPPED_HANDLE_HPP
12 #define BOOST_ASIO_WINDOWS_BASIC_OVERLAPPED_HANDLE_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #if defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE) \
21 || defined(BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE) \
22 || defined(GENERATING_DOCUMENTATION)
25 #include <boost/asio/async_result.hpp>
26 #include <boost/asio/detail/io_object_impl.hpp>
27 #include <boost/asio/detail/throw_error.hpp>
28 #include <boost/asio/detail/win_iocp_handle_service.hpp>
29 #include <boost/asio/error.hpp>
30 #include <boost/asio/execution_context.hpp>
31 #include <boost/asio/executor.hpp>
33 #if defined(BOOST_ASIO_HAS_MOVE)
35 #endif // defined(BOOST_ASIO_HAS_MOVE)
37 #include <boost/asio/detail/push_options.hpp>
43 /// Provides Windows handle functionality for objects that support
46 * The windows::overlapped_handle class provides the ability to wrap a Windows
47 * handle. The underlying object referred to by the handle must support
51 * @e Distinct @e objects: Safe.@n
52 * @e Shared @e objects: Unsafe.
54 template <typename Executor = executor>
55 class basic_overlapped_handle
58 /// The type of the executor associated with the object.
59 typedef Executor executor_type;
61 /// Rebinds the handle type to another executor.
62 template <typename Executor1>
63 struct rebind_executor
65 /// The handle type when rebound to the specified executor.
66 typedef basic_overlapped_handle<Executor1> other;
69 /// The native representation of a handle.
70 #if defined(GENERATING_DOCUMENTATION)
71 typedef implementation_defined native_handle_type;
73 typedef boost::asio::detail::win_iocp_handle_service::native_handle_type
77 /// An overlapped_handle is always the lowest layer.
78 typedef basic_overlapped_handle lowest_layer_type;
80 /// Construct an overlapped handle without opening it.
82 * This constructor creates an overlapped handle without opening it.
84 * @param ex The I/O executor that the overlapped handle will use, by default,
85 * to dispatch handlers for any asynchronous operations performed on the
88 explicit basic_overlapped_handle(const executor_type& ex)
93 /// Construct an overlapped handle without opening it.
95 * This constructor creates an overlapped handle without opening it.
97 * @param context An execution context which provides the I/O executor that
98 * the overlapped handle will use, by default, to dispatch handlers for any
99 * asynchronous operations performed on the overlapped handle.
101 template <typename ExecutionContext>
102 explicit basic_overlapped_handle(ExecutionContext& context,
104 is_convertible<ExecutionContext&, execution_context&>::value,
105 basic_overlapped_handle
111 /// Construct an overlapped handle on an existing native handle.
113 * This constructor creates an overlapped handle object to hold an existing
116 * @param ex The I/O executor that the overlapped handle will use, by default,
117 * to dispatch handlers for any asynchronous operations performed on the
120 * @param native_handle The new underlying handle implementation.
122 * @throws boost::system::system_error Thrown on failure.
124 basic_overlapped_handle(const executor_type& ex,
125 const native_handle_type& native_handle)
128 boost::system::error_code ec;
129 impl_.get_service().assign(impl_.get_implementation(), native_handle, ec);
130 boost::asio::detail::throw_error(ec, "assign");
133 /// Construct an overlapped handle on an existing native handle.
135 * This constructor creates an overlapped handle object to hold an existing
138 * @param context An execution context which provides the I/O executor that
139 * the overlapped handle will use, by default, to dispatch handlers for any
140 * asynchronous operations performed on the overlapped handle.
142 * @param native_handle The new underlying handle implementation.
144 * @throws boost::system::system_error Thrown on failure.
146 template <typename ExecutionContext>
147 basic_overlapped_handle(ExecutionContext& context,
148 const native_handle_type& native_handle,
150 is_convertible<ExecutionContext&, execution_context&>::value
154 boost::system::error_code ec;
155 impl_.get_service().assign(impl_.get_implementation(), native_handle, ec);
156 boost::asio::detail::throw_error(ec, "assign");
159 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
160 /// Move-construct an overlapped handle from another.
162 * This constructor moves a handle from one object to another.
164 * @param other The other overlapped handle object from which the move will
167 * @note Following the move, the moved-from object is in the same state as if
168 * constructed using the @c overlapped_handle(const executor_type&)
171 basic_overlapped_handle(basic_overlapped_handle&& other)
172 : impl_(std::move(other.impl_))
176 /// Move-assign an overlapped handle from another.
178 * This assignment operator moves a handle from one object to another.
180 * @param other The other overlapped handle object from which the move will
183 * @note Following the move, the moved-from object is in the same state as if
184 * constructed using the @c overlapped_handle(const executor_type&)
187 basic_overlapped_handle& operator=(basic_overlapped_handle&& other)
189 impl_ = std::move(other.impl_);
192 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
194 /// Get the executor associated with the object.
195 executor_type get_executor() BOOST_ASIO_NOEXCEPT
197 return impl_.get_executor();
200 /// Get a reference to the lowest layer.
202 * This function returns a reference to the lowest layer in a stack of
203 * layers. Since an overlapped_handle cannot contain any further layers, it
204 * simply returns a reference to itself.
206 * @return A reference to the lowest layer in the stack of layers. Ownership
207 * is not transferred to the caller.
209 lowest_layer_type& lowest_layer()
214 /// Get a const reference to the lowest layer.
216 * This function returns a const reference to the lowest layer in a stack of
217 * layers. Since an overlapped_handle cannot contain any further layers, it
218 * simply returns a reference to itself.
220 * @return A const reference to the lowest layer in the stack of layers.
221 * Ownership is not transferred to the caller.
223 const lowest_layer_type& lowest_layer() const
228 /// Assign an existing native handle to the handle.
230 * This function opens the handle to hold an existing native handle.
232 * @param handle A native handle.
234 * @throws boost::system::system_error Thrown on failure.
236 void assign(const native_handle_type& handle)
238 boost::system::error_code ec;
239 impl_.get_service().assign(impl_.get_implementation(), handle, ec);
240 boost::asio::detail::throw_error(ec, "assign");
243 /// Assign an existing native handle to the handle.
245 * This function opens the handle to hold an existing native handle.
247 * @param handle A native handle.
249 * @param ec Set to indicate what error occurred, if any.
251 BOOST_ASIO_SYNC_OP_VOID assign(const native_handle_type& handle,
252 boost::system::error_code& ec)
254 impl_.get_service().assign(impl_.get_implementation(), handle, ec);
255 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
258 /// Determine whether the handle is open.
261 return impl_.get_service().is_open(impl_.get_implementation());
264 /// Close the handle.
266 * This function is used to close the handle. Any asynchronous read or write
267 * operations will be cancelled immediately, and will complete with the
268 * boost::asio::error::operation_aborted error.
270 * @throws boost::system::system_error Thrown on failure.
274 boost::system::error_code ec;
275 impl_.get_service().close(impl_.get_implementation(), ec);
276 boost::asio::detail::throw_error(ec, "close");
279 /// Close the handle.
281 * This function is used to close the handle. Any asynchronous read or write
282 * operations will be cancelled immediately, and will complete with the
283 * boost::asio::error::operation_aborted error.
285 * @param ec Set to indicate what error occurred, if any.
287 BOOST_ASIO_SYNC_OP_VOID close(boost::system::error_code& ec)
289 impl_.get_service().close(impl_.get_implementation(), ec);
290 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
293 /// Get the native handle representation.
295 * This function may be used to obtain the underlying representation of the
296 * handle. This is intended to allow access to native handle functionality
297 * that is not otherwise provided.
299 native_handle_type native_handle()
301 return impl_.get_service().native_handle(impl_.get_implementation());
304 /// Cancel all asynchronous operations associated with the handle.
306 * This function causes all outstanding asynchronous read or write operations
307 * to finish immediately, and the handlers for cancelled operations will be
308 * passed the boost::asio::error::operation_aborted error.
310 * @throws boost::system::system_error Thrown on failure.
314 boost::system::error_code ec;
315 impl_.get_service().cancel(impl_.get_implementation(), ec);
316 boost::asio::detail::throw_error(ec, "cancel");
319 /// Cancel all asynchronous operations associated with the handle.
321 * This function causes all outstanding asynchronous read or write operations
322 * to finish immediately, and the handlers for cancelled operations will be
323 * passed the boost::asio::error::operation_aborted error.
325 * @param ec Set to indicate what error occurred, if any.
327 BOOST_ASIO_SYNC_OP_VOID cancel(boost::system::error_code& ec)
329 impl_.get_service().cancel(impl_.get_implementation(), ec);
330 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
334 /// Protected destructor to prevent deletion through this type.
336 * This function destroys the handle, cancelling any outstanding asynchronous
337 * wait operations associated with the handle as if by calling @c cancel.
339 ~basic_overlapped_handle()
343 boost::asio::detail::io_object_impl<
344 boost::asio::detail::win_iocp_handle_service, Executor> impl_;
347 // Disallow copying and assignment.
348 basic_overlapped_handle(const basic_overlapped_handle&) BOOST_ASIO_DELETED;
349 basic_overlapped_handle& operator=(
350 const basic_overlapped_handle&) BOOST_ASIO_DELETED;
353 } // namespace windows
357 #include <boost/asio/detail/pop_options.hpp>
359 #endif // defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE)
360 // || defined(BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE)
361 // || defined(GENERATING_DOCUMENTATION)
363 #endif // BOOST_ASIO_WINDOWS_BASIC_OVERLAPPED_HANDLE_HPP