PageRenderTime 31ms CodeModel.GetById 10ms app.highlight 15ms RepoModel.GetById 2ms app.codeStats 0ms

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

http://hadesmem.googlecode.com/
C++ Header | 374 lines | 107 code | 25 blank | 242 comment | 3 complexity | 28fb9f4bc06a5aa574f8e9b9f02d3551 MD5 | raw file
  1//
  2// windows/basic_random_access_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_RANDOM_ACCESS_HANDLE_HPP
 12#define BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_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(GENERATING_DOCUMENTATION)
 22
 23#include <cstddef>
 24#include <boost/asio/detail/handler_type_requirements.hpp>
 25#include <boost/asio/detail/throw_error.hpp>
 26#include <boost/asio/error.hpp>
 27#include <boost/asio/windows/basic_handle.hpp>
 28#include <boost/asio/windows/random_access_handle_service.hpp>
 29
 30#include <boost/asio/detail/push_options.hpp>
 31
 32namespace boost {
 33namespace asio {
 34namespace windows {
 35
 36/// Provides random-access handle functionality.
 37/**
 38 * The windows::basic_random_access_handle class template provides asynchronous
 39 * and blocking random-access handle functionality.
 40 *
 41 * @par Thread Safety
 42 * @e Distinct @e objects: Safe.@n
 43 * @e Shared @e objects: Unsafe.
 44 */
 45template <typename RandomAccessHandleService = random_access_handle_service>
 46class basic_random_access_handle
 47  : public basic_handle<RandomAccessHandleService>
 48{
 49public:
 50  /// (Deprecated: Use native_handle_type.) The native representation of a
 51  /// handle.
 52  typedef typename RandomAccessHandleService::native_handle_type native_type;
 53
 54  /// The native representation of a handle.
 55  typedef typename RandomAccessHandleService::native_handle_type
 56    native_handle_type;
 57
 58  /// Construct a basic_random_access_handle without opening it.
 59  /**
 60   * This constructor creates a random-access handle without opening it. The
 61   * handle needs to be opened before data can be written to or or read from it.
 62   *
 63   * @param io_service The io_service object that the random-access handle will
 64   * use to dispatch handlers for any asynchronous operations performed on the
 65   * handle.
 66   */
 67  explicit basic_random_access_handle(boost::asio::io_service& io_service)
 68    : basic_handle<RandomAccessHandleService>(io_service)
 69  {
 70  }
 71
 72  /// Construct a basic_random_access_handle on an existing native handle.
 73  /**
 74   * This constructor creates a random-access handle object to hold an existing
 75   * native handle.
 76   *
 77   * @param io_service The io_service object that the random-access handle will
 78   * use to dispatch handlers for any asynchronous operations performed on the
 79   * handle.
 80   *
 81   * @param handle The new underlying handle implementation.
 82   *
 83   * @throws boost::system::system_error Thrown on failure.
 84   */
 85  basic_random_access_handle(boost::asio::io_service& io_service,
 86      const native_handle_type& handle)
 87    : basic_handle<RandomAccessHandleService>(io_service, handle)
 88  {
 89  }
 90
 91#if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 92  /// Move-construct a basic_random_access_handle from another.
 93  /**
 94   * This constructor moves a random-access handle from one object to another.
 95   *
 96   * @param other The other basic_random_access_handle object from which the
 97   * move will occur.
 98   *
 99   * @note Following the move, the moved-from object is in the same state as if
100   * constructed using the @c basic_random_access_handle(io_service&)
101   * constructor.
102   */
103  basic_random_access_handle(basic_random_access_handle&& other)
104    : basic_handle<RandomAccessHandleService>(
105        BOOST_ASIO_MOVE_CAST(basic_random_access_handle)(other))
106  {
107  }
108
109  /// Move-assign a basic_random_access_handle from another.
110  /**
111   * This assignment operator moves a random-access handle from one object to
112   * another.
113   *
114   * @param other The other basic_random_access_handle object from which the
115   * move will occur.
116   *
117   * @note Following the move, the moved-from object is in the same state as if
118   * constructed using the @c basic_random_access_handle(io_service&)
119   * constructor.
120   */
121  basic_random_access_handle& operator=(basic_random_access_handle&& other)
122  {
123    basic_handle<RandomAccessHandleService>::operator=(
124        BOOST_ASIO_MOVE_CAST(basic_random_access_handle)(other));
125    return *this;
126  }
127#endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
128
129  /// Write some data to the handle at the specified offset.
130  /**
131   * This function is used to write data to the random-access handle. The
132   * function call will block until one or more bytes of the data has been
133   * written successfully, or until an error occurs.
134   *
135   * @param offset The offset at which the data will be written.
136   *
137   * @param buffers One or more data buffers to be written to the handle.
138   *
139   * @returns The number of bytes written.
140   *
141   * @throws boost::system::system_error Thrown on failure. An error code of
142   * boost::asio::error::eof indicates that the connection was closed by the
143   * peer.
144   *
145   * @note The write_some_at operation may not write all of the data. Consider
146   * using the @ref write_at function if you need to ensure that all data is
147   * written before the blocking operation completes.
148   *
149   * @par Example
150   * To write a single data buffer use the @ref buffer function as follows:
151   * @code
152   * handle.write_some_at(42, boost::asio::buffer(data, size));
153   * @endcode
154   * See the @ref buffer documentation for information on writing multiple
155   * buffers in one go, and how to use it with arrays, boost::array or
156   * std::vector.
157   */
158  template <typename ConstBufferSequence>
159  std::size_t write_some_at(boost::uint64_t offset,
160      const ConstBufferSequence& buffers)
161  {
162    boost::system::error_code ec;
163    std::size_t s = this->get_service().write_some_at(
164        this->get_implementation(), offset, buffers, ec);
165    boost::asio::detail::throw_error(ec, "write_some_at");
166    return s;
167  }
168
169  /// Write some data to the handle at the specified offset.
170  /**
171   * This function is used to write data to the random-access handle. The
172   * function call will block until one or more bytes of the data has been
173   * written successfully, or until an error occurs.
174   *
175   * @param offset The offset at which the data will be written.
176   *
177   * @param buffers One or more data buffers to be written to the handle.
178   *
179   * @param ec Set to indicate what error occurred, if any.
180   *
181   * @returns The number of bytes written. Returns 0 if an error occurred.
182   *
183   * @note The write_some operation may not transmit all of the data to the
184   * peer. Consider using the @ref write_at function if you need to ensure that
185   * all data is written before the blocking operation completes.
186   */
187  template <typename ConstBufferSequence>
188  std::size_t write_some_at(boost::uint64_t offset,
189      const ConstBufferSequence& buffers, boost::system::error_code& ec)
190  {
191    return this->get_service().write_some_at(
192        this->get_implementation(), offset, buffers, ec);
193  }
194
195  /// Start an asynchronous write at the specified offset.
196  /**
197   * This function is used to asynchronously write data to the random-access
198   * handle. The function call always returns immediately.
199   *
200   * @param offset The offset at which the data will be written.
201   *
202   * @param buffers One or more data buffers to be written to the handle.
203   * Although the buffers object may be copied as necessary, ownership of the
204   * underlying memory blocks is retained by the caller, which must guarantee
205   * that they remain valid until the handler is called.
206   *
207   * @param handler The handler to be called when the write operation completes.
208   * Copies will be made of the handler as required. The function signature of
209   * the handler must be:
210   * @code void handler(
211   *   const boost::system::error_code& error, // Result of operation.
212   *   std::size_t bytes_transferred           // Number of bytes written.
213   * ); @endcode
214   * Regardless of whether the asynchronous operation completes immediately or
215   * not, the handler will not be invoked from within this function. Invocation
216   * of the handler will be performed in a manner equivalent to using
217   * boost::asio::io_service::post().
218   *
219   * @note The write operation may not transmit all of the data to the peer.
220   * Consider using the @ref async_write_at function if you need to ensure that
221   * all data is written before the asynchronous operation completes.
222   *
223   * @par Example
224   * To write a single data buffer use the @ref buffer function as follows:
225   * @code
226   * handle.async_write_some_at(42, boost::asio::buffer(data, size), handler);
227   * @endcode
228   * See the @ref buffer documentation for information on writing multiple
229   * buffers in one go, and how to use it with arrays, boost::array or
230   * std::vector.
231   */
232  template <typename ConstBufferSequence, typename WriteHandler>
233  void async_write_some_at(boost::uint64_t offset,
234      const ConstBufferSequence& buffers,
235      BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
236  {
237    // If you get an error on the following line it means that your handler does
238    // not meet the documented type requirements for a WriteHandler.
239    BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
240
241    this->get_service().async_write_some_at(this->get_implementation(),
242        offset, buffers, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
243  }
244
245  /// Read some data from the handle at the specified offset.
246  /**
247   * This function is used to read data from the random-access handle. The
248   * function call will block until one or more bytes of data has been read
249   * successfully, or until an error occurs.
250   *
251   * @param offset The offset at which the data will be read.
252   *
253   * @param buffers One or more buffers into which the data will be read.
254   *
255   * @returns The number of bytes read.
256   *
257   * @throws boost::system::system_error Thrown on failure. An error code of
258   * boost::asio::error::eof indicates that the connection was closed by the
259   * peer.
260   *
261   * @note The read_some operation may not read all of the requested number of
262   * bytes. Consider using the @ref read_at function if you need to ensure that
263   * the requested amount of data is read before the blocking operation
264   * completes.
265   *
266   * @par Example
267   * To read into a single data buffer use the @ref buffer function as follows:
268   * @code
269   * handle.read_some_at(42, boost::asio::buffer(data, size));
270   * @endcode
271   * See the @ref buffer documentation for information on reading into multiple
272   * buffers in one go, and how to use it with arrays, boost::array or
273   * std::vector.
274   */
275  template <typename MutableBufferSequence>
276  std::size_t read_some_at(boost::uint64_t offset,
277      const MutableBufferSequence& buffers)
278  {
279    boost::system::error_code ec;
280    std::size_t s = this->get_service().read_some_at(
281        this->get_implementation(), offset, buffers, ec);
282    boost::asio::detail::throw_error(ec, "read_some_at");
283    return s;
284  }
285
286  /// Read some data from the handle at the specified offset.
287  /**
288   * This function is used to read data from the random-access handle. The
289   * function call will block until one or more bytes of data has been read
290   * successfully, or until an error occurs.
291   *
292   * @param offset The offset at which the data will be read.
293   *
294   * @param buffers One or more buffers into which the data will be read.
295   *
296   * @param ec Set to indicate what error occurred, if any.
297   *
298   * @returns The number of bytes read. Returns 0 if an error occurred.
299   *
300   * @note The read_some operation may not read all of the requested number of
301   * bytes. Consider using the @ref read_at function if you need to ensure that
302   * the requested amount of data is read before the blocking operation
303   * completes.
304   */
305  template <typename MutableBufferSequence>
306  std::size_t read_some_at(boost::uint64_t offset,
307      const MutableBufferSequence& buffers, boost::system::error_code& ec)
308  {
309    return this->get_service().read_some_at(
310        this->get_implementation(), offset, buffers, ec);
311  }
312
313  /// Start an asynchronous read at the specified offset.
314  /**
315   * This function is used to asynchronously read data from the random-access
316   * handle. The function call always returns immediately.
317   *
318   * @param offset The offset at which the data will be read.
319   *
320   * @param buffers One or more buffers into which the data will be read.
321   * Although the buffers object may be copied as necessary, ownership of the
322   * underlying memory blocks is retained by the caller, which must guarantee
323   * that they remain valid until the handler is called.
324   *
325   * @param handler The handler to be called when the read operation completes.
326   * Copies will be made of the handler as required. The function signature of
327   * the handler must be:
328   * @code void handler(
329   *   const boost::system::error_code& error, // Result of operation.
330   *   std::size_t bytes_transferred           // Number of bytes read.
331   * ); @endcode
332   * Regardless of whether the asynchronous operation completes immediately or
333   * not, the handler will not be invoked from within this function. Invocation
334   * of the handler will be performed in a manner equivalent to using
335   * boost::asio::io_service::post().
336   *
337   * @note The read operation may not read all of the requested number of bytes.
338   * Consider using the @ref async_read_at function if you need to ensure that
339   * the requested amount of data is read before the asynchronous operation
340   * completes.
341   *
342   * @par Example
343   * To read into a single data buffer use the @ref buffer function as follows:
344   * @code
345   * handle.async_read_some_at(42, boost::asio::buffer(data, size), handler);
346   * @endcode
347   * See the @ref buffer documentation for information on reading into multiple
348   * buffers in one go, and how to use it with arrays, boost::array or
349   * std::vector.
350   */
351  template <typename MutableBufferSequence, typename ReadHandler>
352  void async_read_some_at(boost::uint64_t offset,
353      const MutableBufferSequence& buffers,
354      BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
355  {
356    // If you get an error on the following line it means that your handler does
357    // not meet the documented type requirements for a ReadHandler.
358    BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
359
360    this->get_service().async_read_some_at(this->get_implementation(),
361        offset, buffers, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
362  }
363};
364
365} // namespace windows
366} // namespace asio
367} // namespace boost
368
369#include <boost/asio/detail/pop_options.hpp>
370
371#endif // defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE)
372       //   || defined(GENERATING_DOCUMENTATION)
373
374#endif // BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP