/Src/Dependencies/Boost/boost/asio/windows/basic_handle.hpp

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