/Src/Dependencies/Boost/boost/asio/posix/basic_stream_descriptor.hpp

http://hadesmem.googlecode.com/ · C++ Header · 360 lines · 103 code · 25 blank · 232 comment · 3 complexity · 5a7450de2defca8c5d7063c95777ae0e MD5 · raw file

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