1 // 2 // windows/basic_handle.hpp 3 // ~~~~~~~~~~~~~~~~~~~~~~~~ 4 // 5 // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) 6 // 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) 9 // 10 11 #ifndef BOOST_ASIO_WINDOWS_BASIC_HANDLE_HPP 12 #define BOOST_ASIO_WINDOWS_BASIC_HANDLE_HPP 13 14 #if defined(_MSC_VER) && (_MSC_VER >= 1200) 15 # pragma once 16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) 17 18 #include <boost/asio/detail/config.hpp> 19 20 #if defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE) \ 21 || defined(BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE) \ 22 || defined(BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE) \ 23 || defined(GENERATING_DOCUMENTATION) 24 25 #include <boost/asio/basic_io_object.hpp> 26 #include <boost/asio/detail/throw_error.hpp> 27 #include <boost/asio/error.hpp> 28 29 #include <boost/asio/detail/push_options.hpp> 30 31 namespace boost { 32 namespace asio { 33 namespace windows { 34 35 /// Provides Windows handle functionality. 36 /** 37 * The windows::basic_handle class template provides the ability to wrap a 38 * Windows handle. 39 * 40 * @par Thread Safety 41 * @e Distinct @e objects: Safe.@n 42 * @e Shared @e objects: Unsafe. 43 */ 44 template <typename HandleService> 45 class basic_handle 46 : public basic_io_object<HandleService> 47 { 48 public: 49 /// (Deprecated: Use native_handle_type.) The native representation of a 50 /// handle. 51 typedef typename HandleService::native_handle_type native_type; 52 53 /// The native representation of a handle. 54 typedef typename HandleService::native_handle_type native_handle_type; 55 56 /// A basic_handle is always the lowest layer. 57 typedef basic_handle<HandleService> lowest_layer_type; 58 59 /// Construct a basic_handle without opening it. 60 /** 61 * This constructor creates a handle without opening it. 62 * 63 * @param io_service The io_service object that the handle will use to 64 * dispatch handlers for any asynchronous operations performed on the handle. 65 */ basic_handle(boost::asio::io_service & io_service)66 explicit basic_handle(boost::asio::io_service& io_service) 67 : basic_io_object<HandleService>(io_service) 68 { 69 } 70 71 /// Construct a basic_handle on an existing native handle. 72 /** 73 * This constructor creates a handle object to hold an existing native handle. 74 * 75 * @param io_service The io_service object that the handle will use to 76 * dispatch handlers for any asynchronous operations performed on the handle. 77 * 78 * @param handle A native handle. 79 * 80 * @throws boost::system::system_error Thrown on failure. 81 */ basic_handle(boost::asio::io_service & io_service,const native_handle_type & handle)82 basic_handle(boost::asio::io_service& io_service, 83 const native_handle_type& handle) 84 : basic_io_object<HandleService>(io_service) 85 { 86 boost::system::error_code ec; 87 this->get_service().assign(this->get_implementation(), handle, ec); 88 boost::asio::detail::throw_error(ec, "assign"); 89 } 90 91 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) 92 /// Move-construct a basic_handle from another. 93 /** 94 * This constructor moves a handle from one object to another. 95 * 96 * @param other The other basic_handle object from which the move will occur. 97 * 98 * @note Following the move, the moved-from object is in the same state as if 99 * constructed using the @c basic_handle(io_service&) constructor. 100 */ basic_handle(basic_handle && other)101 basic_handle(basic_handle&& other) 102 : basic_io_object<HandleService>( 103 BOOST_ASIO_MOVE_CAST(basic_handle)(other)) 104 { 105 } 106 107 /// Move-assign a basic_handle from another. 108 /** 109 * This assignment operator moves a handle from one object to another. 110 * 111 * @param other The other basic_handle object from which the move will occur. 112 * 113 * @note Following the move, the moved-from object is in the same state as if 114 * constructed using the @c basic_handle(io_service&) constructor. 115 */ operator =(basic_handle && other)116 basic_handle& operator=(basic_handle&& other) 117 { 118 basic_io_object<HandleService>::operator=( 119 BOOST_ASIO_MOVE_CAST(basic_handle)(other)); 120 return *this; 121 } 122 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) 123 124 /// Get a reference to the lowest layer. 125 /** 126 * This function returns a reference to the lowest layer in a stack of 127 * layers. Since a basic_handle cannot contain any further layers, it simply 128 * returns a reference to itself. 129 * 130 * @return A reference to the lowest layer in the stack of layers. Ownership 131 * is not transferred to the caller. 132 */ lowest_layer()133 lowest_layer_type& lowest_layer() 134 { 135 return *this; 136 } 137 138 /// Get a const reference to the lowest layer. 139 /** 140 * This function returns a const reference to the lowest layer in a stack of 141 * layers. Since a basic_handle cannot contain any further layers, it simply 142 * returns a reference to itself. 143 * 144 * @return A const reference to the lowest layer in the stack of layers. 145 * Ownership is not transferred to the caller. 146 */ lowest_layer() const147 const lowest_layer_type& lowest_layer() const 148 { 149 return *this; 150 } 151 152 /// Assign an existing native handle to the handle. 153 /* 154 * This function opens the handle to hold an existing native handle. 155 * 156 * @param handle A native handle. 157 * 158 * @throws boost::system::system_error Thrown on failure. 159 */ assign(const native_handle_type & handle)160 void assign(const native_handle_type& handle) 161 { 162 boost::system::error_code ec; 163 this->get_service().assign(this->get_implementation(), handle, ec); 164 boost::asio::detail::throw_error(ec, "assign"); 165 } 166 167 /// Assign an existing native handle to the handle. 168 /* 169 * This function opens the handle to hold an existing native handle. 170 * 171 * @param handle A native handle. 172 * 173 * @param ec Set to indicate what error occurred, if any. 174 */ assign(const native_handle_type & handle,boost::system::error_code & ec)175 boost::system::error_code assign(const native_handle_type& handle, 176 boost::system::error_code& ec) 177 { 178 return this->get_service().assign(this->get_implementation(), handle, ec); 179 } 180 181 /// Determine whether the handle is open. is_open() const182 bool is_open() const 183 { 184 return this->get_service().is_open(this->get_implementation()); 185 } 186 187 /// Close the handle. 188 /** 189 * This function is used to close the handle. Any asynchronous read or write 190 * operations will be cancelled immediately, and will complete with the 191 * boost::asio::error::operation_aborted error. 192 * 193 * @throws boost::system::system_error Thrown on failure. 194 */ close()195 void close() 196 { 197 boost::system::error_code ec; 198 this->get_service().close(this->get_implementation(), ec); 199 boost::asio::detail::throw_error(ec, "close"); 200 } 201 202 /// Close the handle. 203 /** 204 * This function is used to close the handle. Any asynchronous read or write 205 * operations will be cancelled immediately, and will complete with the 206 * boost::asio::error::operation_aborted error. 207 * 208 * @param ec Set to indicate what error occurred, if any. 209 */ close(boost::system::error_code & ec)210 boost::system::error_code close(boost::system::error_code& ec) 211 { 212 return this->get_service().close(this->get_implementation(), ec); 213 } 214 215 /// (Deprecated: Use native_handle().) Get the native handle representation. 216 /** 217 * This function may be used to obtain the underlying representation of the 218 * handle. This is intended to allow access to native handle functionality 219 * that is not otherwise provided. 220 */ native()221 native_type native() 222 { 223 return this->get_service().native_handle(this->get_implementation()); 224 } 225 226 /// Get the native handle representation. 227 /** 228 * This function may be used to obtain the underlying representation of the 229 * handle. This is intended to allow access to native handle functionality 230 * that is not otherwise provided. 231 */ native_handle()232 native_handle_type native_handle() 233 { 234 return this->get_service().native_handle(this->get_implementation()); 235 } 236 237 /// Cancel all asynchronous operations associated with the handle. 238 /** 239 * This function causes all outstanding asynchronous read or write operations 240 * to finish immediately, and the handlers for cancelled operations will be 241 * passed the boost::asio::error::operation_aborted error. 242 * 243 * @throws boost::system::system_error Thrown on failure. 244 */ cancel()245 void cancel() 246 { 247 boost::system::error_code ec; 248 this->get_service().cancel(this->get_implementation(), ec); 249 boost::asio::detail::throw_error(ec, "cancel"); 250 } 251 252 /// Cancel all asynchronous operations associated with the handle. 253 /** 254 * This function causes all outstanding asynchronous read or write operations 255 * to finish immediately, and the handlers for cancelled operations will be 256 * passed the boost::asio::error::operation_aborted error. 257 * 258 * @param ec Set to indicate what error occurred, if any. 259 */ cancel(boost::system::error_code & ec)260 boost::system::error_code cancel(boost::system::error_code& ec) 261 { 262 return this->get_service().cancel(this->get_implementation(), ec); 263 } 264 265 protected: 266 /// Protected destructor to prevent deletion through this type. ~basic_handle()267 ~basic_handle() 268 { 269 } 270 }; 271 272 } // namespace windows 273 } // namespace asio 274 } // namespace boost 275 276 #include <boost/asio/detail/pop_options.hpp> 277 278 #endif // defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE) 279 // || defined(BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE) 280 // || defined(BOOST_ASIO_HAS_WINDOWS_OBJECT_HANDLE) 281 // || defined(GENERATING_DOCUMENTATION) 282 283 #endif // BOOST_ASIO_WINDOWS_BASIC_HANDLE_HPP 284