Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / windows / basic_stream_handle.hpp @ 2486

History | View | Annotate | Download (13.7 kB)

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