boost/asio/windows/basic_stream_handle.hpp

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