gameserv-2.0/asio/asio/windows/basic_random_access_handle.hpp

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