/Src/Dependencies/Boost/boost/asio/basic_stream_socket.hpp

http://hadesmem.googlecode.com/ · C++ Header · 797 lines · 196 code · 40 blank · 561 comment · 2 complexity · 691e1fd5cb85220fad02fb8d587a799e MD5 · raw file

  1. //
  2. // basic_stream_socket.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_BASIC_STREAM_SOCKET_HPP
  11. #define BOOST_ASIO_BASIC_STREAM_SOCKET_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. #include <cstddef>
  17. #include <boost/asio/basic_socket.hpp>
  18. #include <boost/asio/detail/handler_type_requirements.hpp>
  19. #include <boost/asio/detail/throw_error.hpp>
  20. #include <boost/asio/error.hpp>
  21. #include <boost/asio/stream_socket_service.hpp>
  22. #include <boost/asio/detail/push_options.hpp>
  23. namespace boost {
  24. namespace asio {
  25. /// Provides stream-oriented socket functionality.
  26. /**
  27. * The basic_stream_socket class template provides asynchronous and blocking
  28. * stream-oriented socket functionality.
  29. *
  30. * @par Thread Safety
  31. * @e Distinct @e objects: Safe.@n
  32. * @e Shared @e objects: Unsafe.
  33. *
  34. * @par Concepts:
  35. * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.
  36. */
  37. template <typename Protocol,
  38. typename StreamSocketService = stream_socket_service<Protocol> >
  39. class basic_stream_socket
  40. : public basic_socket<Protocol, StreamSocketService>
  41. {
  42. public:
  43. /// (Deprecated: Use native_handle_type.) The native representation of a
  44. /// socket.
  45. typedef typename StreamSocketService::native_handle_type native_type;
  46. /// The native representation of a socket.
  47. typedef typename StreamSocketService::native_handle_type native_handle_type;
  48. /// The protocol type.
  49. typedef Protocol protocol_type;
  50. /// The endpoint type.
  51. typedef typename Protocol::endpoint endpoint_type;
  52. /// Construct a basic_stream_socket without opening it.
  53. /**
  54. * This constructor creates a stream socket without opening it. The socket
  55. * needs to be opened and then connected or accepted before data can be sent
  56. * or received on it.
  57. *
  58. * @param io_service The io_service object that the stream socket will use to
  59. * dispatch handlers for any asynchronous operations performed on the socket.
  60. */
  61. explicit basic_stream_socket(boost::asio::io_service& io_service)
  62. : basic_socket<Protocol, StreamSocketService>(io_service)
  63. {
  64. }
  65. /// Construct and open a basic_stream_socket.
  66. /**
  67. * This constructor creates and opens a stream socket. The socket needs to be
  68. * connected or accepted before data can be sent or received on it.
  69. *
  70. * @param io_service The io_service object that the stream socket will use to
  71. * dispatch handlers for any asynchronous operations performed on the socket.
  72. *
  73. * @param protocol An object specifying protocol parameters to be used.
  74. *
  75. * @throws boost::system::system_error Thrown on failure.
  76. */
  77. basic_stream_socket(boost::asio::io_service& io_service,
  78. const protocol_type& protocol)
  79. : basic_socket<Protocol, StreamSocketService>(io_service, protocol)
  80. {
  81. }
  82. /// Construct a basic_stream_socket, opening it and binding it to the given
  83. /// local endpoint.
  84. /**
  85. * This constructor creates a stream socket and automatically opens it bound
  86. * to the specified endpoint on the local machine. The protocol used is the
  87. * protocol associated with the given endpoint.
  88. *
  89. * @param io_service The io_service object that the stream socket will use to
  90. * dispatch handlers for any asynchronous operations performed on the socket.
  91. *
  92. * @param endpoint An endpoint on the local machine to which the stream
  93. * socket will be bound.
  94. *
  95. * @throws boost::system::system_error Thrown on failure.
  96. */
  97. basic_stream_socket(boost::asio::io_service& io_service,
  98. const endpoint_type& endpoint)
  99. : basic_socket<Protocol, StreamSocketService>(io_service, endpoint)
  100. {
  101. }
  102. /// Construct a basic_stream_socket on an existing native socket.
  103. /**
  104. * This constructor creates a stream socket object to hold an existing native
  105. * socket.
  106. *
  107. * @param io_service The io_service object that the stream socket will use to
  108. * dispatch handlers for any asynchronous operations performed on the socket.
  109. *
  110. * @param protocol An object specifying protocol parameters to be used.
  111. *
  112. * @param native_socket The new underlying socket implementation.
  113. *
  114. * @throws boost::system::system_error Thrown on failure.
  115. */
  116. basic_stream_socket(boost::asio::io_service& io_service,
  117. const protocol_type& protocol, const native_handle_type& native_socket)
  118. : basic_socket<Protocol, StreamSocketService>(
  119. io_service, protocol, native_socket)
  120. {
  121. }
  122. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  123. /// Move-construct a basic_stream_socket from another.
  124. /**
  125. * This constructor moves a stream socket from one object to another.
  126. *
  127. * @param other The other basic_stream_socket object from which the move
  128. * will occur.
  129. *
  130. * @note Following the move, the moved-from object is in the same state as if
  131. * constructed using the @c basic_stream_socket(io_service&) constructor.
  132. */
  133. basic_stream_socket(basic_stream_socket&& other)
  134. : basic_socket<Protocol, StreamSocketService>(
  135. BOOST_ASIO_MOVE_CAST(basic_stream_socket)(other))
  136. {
  137. }
  138. /// Move-assign a basic_stream_socket from another.
  139. /**
  140. * This assignment operator moves a stream socket from one object to another.
  141. *
  142. * @param other The other basic_stream_socket object from which the move
  143. * will occur.
  144. *
  145. * @note Following the move, the moved-from object is in the same state as if
  146. * constructed using the @c basic_stream_socket(io_service&) constructor.
  147. */
  148. basic_stream_socket& operator=(basic_stream_socket&& other)
  149. {
  150. basic_socket<Protocol, StreamSocketService>::operator=(
  151. BOOST_ASIO_MOVE_CAST(basic_stream_socket)(other));
  152. return *this;
  153. }
  154. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  155. /// Send some data on the socket.
  156. /**
  157. * This function is used to send data on the stream socket. The function
  158. * call will block until one or more bytes of the data has been sent
  159. * successfully, or an until error occurs.
  160. *
  161. * @param buffers One or more data buffers to be sent on the socket.
  162. *
  163. * @returns The number of bytes sent.
  164. *
  165. * @throws boost::system::system_error Thrown on failure.
  166. *
  167. * @note The send operation may not transmit all of the data to the peer.
  168. * Consider using the @ref write function if you need to ensure that all data
  169. * is written before the blocking operation completes.
  170. *
  171. * @par Example
  172. * To send a single data buffer use the @ref buffer function as follows:
  173. * @code
  174. * socket.send(boost::asio::buffer(data, size));
  175. * @endcode
  176. * See the @ref buffer documentation for information on sending multiple
  177. * buffers in one go, and how to use it with arrays, boost::array or
  178. * std::vector.
  179. */
  180. template <typename ConstBufferSequence>
  181. std::size_t send(const ConstBufferSequence& buffers)
  182. {
  183. boost::system::error_code ec;
  184. std::size_t s = this->get_service().send(
  185. this->get_implementation(), buffers, 0, ec);
  186. boost::asio::detail::throw_error(ec, "send");
  187. return s;
  188. }
  189. /// Send some data on the socket.
  190. /**
  191. * This function is used to send data on the stream socket. The function
  192. * call will block until one or more bytes of the data has been sent
  193. * successfully, or an until error occurs.
  194. *
  195. * @param buffers One or more data buffers to be sent on the socket.
  196. *
  197. * @param flags Flags specifying how the send call is to be made.
  198. *
  199. * @returns The number of bytes sent.
  200. *
  201. * @throws boost::system::system_error Thrown on failure.
  202. *
  203. * @note The send operation may not transmit all of the data to the peer.
  204. * Consider using the @ref write function if you need to ensure that all data
  205. * is written before the blocking operation completes.
  206. *
  207. * @par Example
  208. * To send a single data buffer use the @ref buffer function as follows:
  209. * @code
  210. * socket.send(boost::asio::buffer(data, size), 0);
  211. * @endcode
  212. * See the @ref buffer documentation for information on sending multiple
  213. * buffers in one go, and how to use it with arrays, boost::array or
  214. * std::vector.
  215. */
  216. template <typename ConstBufferSequence>
  217. std::size_t send(const ConstBufferSequence& buffers,
  218. socket_base::message_flags flags)
  219. {
  220. boost::system::error_code ec;
  221. std::size_t s = this->get_service().send(
  222. this->get_implementation(), buffers, flags, ec);
  223. boost::asio::detail::throw_error(ec, "send");
  224. return s;
  225. }
  226. /// Send some data on the socket.
  227. /**
  228. * This function is used to send data on the stream socket. The function
  229. * call will block until one or more bytes of the data has been sent
  230. * successfully, or an until error occurs.
  231. *
  232. * @param buffers One or more data buffers to be sent on the socket.
  233. *
  234. * @param flags Flags specifying how the send call is to be made.
  235. *
  236. * @param ec Set to indicate what error occurred, if any.
  237. *
  238. * @returns The number of bytes sent. Returns 0 if an error occurred.
  239. *
  240. * @note The send operation may not transmit all of the data to the peer.
  241. * Consider using the @ref write function if you need to ensure that all data
  242. * is written before the blocking operation completes.
  243. */
  244. template <typename ConstBufferSequence>
  245. std::size_t send(const ConstBufferSequence& buffers,
  246. socket_base::message_flags flags, boost::system::error_code& ec)
  247. {
  248. return this->get_service().send(
  249. this->get_implementation(), buffers, flags, ec);
  250. }
  251. /// Start an asynchronous send.
  252. /**
  253. * This function is used to asynchronously send data on the stream socket.
  254. * The function call always returns immediately.
  255. *
  256. * @param buffers One or more data buffers to be sent on the socket. Although
  257. * the buffers object may be copied as necessary, ownership of the underlying
  258. * memory blocks is retained by the caller, which must guarantee that they
  259. * remain valid until the handler is called.
  260. *
  261. * @param handler The handler to be called when the send operation completes.
  262. * Copies will be made of the handler as required. The function signature of
  263. * the handler must be:
  264. * @code void handler(
  265. * const boost::system::error_code& error, // Result of operation.
  266. * std::size_t bytes_transferred // Number of bytes sent.
  267. * ); @endcode
  268. * Regardless of whether the asynchronous operation completes immediately or
  269. * not, the handler will not be invoked from within this function. Invocation
  270. * of the handler will be performed in a manner equivalent to using
  271. * boost::asio::io_service::post().
  272. *
  273. * @note The send operation may not transmit all of the data to the peer.
  274. * Consider using the @ref async_write function if you need to ensure that all
  275. * data is written before the asynchronous operation completes.
  276. *
  277. * @par Example
  278. * To send a single data buffer use the @ref buffer function as follows:
  279. * @code
  280. * socket.async_send(boost::asio::buffer(data, size), handler);
  281. * @endcode
  282. * See the @ref buffer documentation for information on sending multiple
  283. * buffers in one go, and how to use it with arrays, boost::array or
  284. * std::vector.
  285. */
  286. template <typename ConstBufferSequence, typename WriteHandler>
  287. void async_send(const ConstBufferSequence& buffers,
  288. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  289. {
  290. // If you get an error on the following line it means that your handler does
  291. // not meet the documented type requirements for a WriteHandler.
  292. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  293. this->get_service().async_send(this->get_implementation(), buffers, 0,
  294. BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  295. }
  296. /// Start an asynchronous send.
  297. /**
  298. * This function is used to asynchronously send data on the stream socket.
  299. * The function call always returns immediately.
  300. *
  301. * @param buffers One or more data buffers to be sent on the socket. Although
  302. * the buffers object may be copied as necessary, ownership of the underlying
  303. * memory blocks is retained by the caller, which must guarantee that they
  304. * remain valid until the handler is called.
  305. *
  306. * @param flags Flags specifying how the send call is to be made.
  307. *
  308. * @param handler The handler to be called when the send operation completes.
  309. * Copies will be made of the handler as required. The function signature of
  310. * the handler must be:
  311. * @code void handler(
  312. * const boost::system::error_code& error, // Result of operation.
  313. * std::size_t bytes_transferred // Number of bytes sent.
  314. * ); @endcode
  315. * Regardless of whether the asynchronous operation completes immediately or
  316. * not, the handler will not be invoked from within this function. Invocation
  317. * of the handler will be performed in a manner equivalent to using
  318. * boost::asio::io_service::post().
  319. *
  320. * @note The send operation may not transmit all of the data to the peer.
  321. * Consider using the @ref async_write function if you need to ensure that all
  322. * data is written before the asynchronous operation completes.
  323. *
  324. * @par Example
  325. * To send a single data buffer use the @ref buffer function as follows:
  326. * @code
  327. * socket.async_send(boost::asio::buffer(data, size), 0, handler);
  328. * @endcode
  329. * See the @ref buffer documentation for information on sending multiple
  330. * buffers in one go, and how to use it with arrays, boost::array or
  331. * std::vector.
  332. */
  333. template <typename ConstBufferSequence, typename WriteHandler>
  334. void async_send(const ConstBufferSequence& buffers,
  335. socket_base::message_flags flags,
  336. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  337. {
  338. // If you get an error on the following line it means that your handler does
  339. // not meet the documented type requirements for a WriteHandler.
  340. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  341. this->get_service().async_send(this->get_implementation(), buffers, flags,
  342. BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  343. }
  344. /// Receive some data on the socket.
  345. /**
  346. * This function is used to receive data on the stream socket. The function
  347. * call will block until one or more bytes of data has been received
  348. * successfully, or until an error occurs.
  349. *
  350. * @param buffers One or more buffers into which the data will be received.
  351. *
  352. * @returns The number of bytes received.
  353. *
  354. * @throws boost::system::system_error Thrown on failure. An error code of
  355. * boost::asio::error::eof indicates that the connection was closed by the
  356. * peer.
  357. *
  358. * @note The receive operation may not receive all of the requested number of
  359. * bytes. Consider using the @ref read function if you need to ensure that the
  360. * requested amount of data is read before the blocking operation completes.
  361. *
  362. * @par Example
  363. * To receive into a single data buffer use the @ref buffer function as
  364. * follows:
  365. * @code
  366. * socket.receive(boost::asio::buffer(data, size));
  367. * @endcode
  368. * See the @ref buffer documentation for information on receiving into
  369. * multiple buffers in one go, and how to use it with arrays, boost::array or
  370. * std::vector.
  371. */
  372. template <typename MutableBufferSequence>
  373. std::size_t receive(const MutableBufferSequence& buffers)
  374. {
  375. boost::system::error_code ec;
  376. std::size_t s = this->get_service().receive(
  377. this->get_implementation(), buffers, 0, ec);
  378. boost::asio::detail::throw_error(ec, "receive");
  379. return s;
  380. }
  381. /// Receive some data on the socket.
  382. /**
  383. * This function is used to receive data on the stream socket. The function
  384. * call will block until one or more bytes of data has been received
  385. * successfully, or until an error occurs.
  386. *
  387. * @param buffers One or more buffers into which the data will be received.
  388. *
  389. * @param flags Flags specifying how the receive call is to be made.
  390. *
  391. * @returns The number of bytes received.
  392. *
  393. * @throws boost::system::system_error Thrown on failure. An error code of
  394. * boost::asio::error::eof indicates that the connection was closed by the
  395. * peer.
  396. *
  397. * @note The receive operation may not receive all of the requested number of
  398. * bytes. Consider using the @ref read function if you need to ensure that the
  399. * requested amount of data is read before the blocking operation completes.
  400. *
  401. * @par Example
  402. * To receive into a single data buffer use the @ref buffer function as
  403. * follows:
  404. * @code
  405. * socket.receive(boost::asio::buffer(data, size), 0);
  406. * @endcode
  407. * See the @ref buffer documentation for information on receiving into
  408. * multiple buffers in one go, and how to use it with arrays, boost::array or
  409. * std::vector.
  410. */
  411. template <typename MutableBufferSequence>
  412. std::size_t receive(const MutableBufferSequence& buffers,
  413. socket_base::message_flags flags)
  414. {
  415. boost::system::error_code ec;
  416. std::size_t s = this->get_service().receive(
  417. this->get_implementation(), buffers, flags, ec);
  418. boost::asio::detail::throw_error(ec, "receive");
  419. return s;
  420. }
  421. /// Receive some data on a connected socket.
  422. /**
  423. * This function is used to receive data on the stream socket. The function
  424. * call will block until one or more bytes of data has been received
  425. * successfully, or until an error occurs.
  426. *
  427. * @param buffers One or more buffers into which the data will be received.
  428. *
  429. * @param flags Flags specifying how the receive call is to be made.
  430. *
  431. * @param ec Set to indicate what error occurred, if any.
  432. *
  433. * @returns The number of bytes received. Returns 0 if an error occurred.
  434. *
  435. * @note The receive operation may not receive all of the requested number of
  436. * bytes. Consider using the @ref read function if you need to ensure that the
  437. * requested amount of data is read before the blocking operation completes.
  438. */
  439. template <typename MutableBufferSequence>
  440. std::size_t receive(const MutableBufferSequence& buffers,
  441. socket_base::message_flags flags, boost::system::error_code& ec)
  442. {
  443. return this->get_service().receive(
  444. this->get_implementation(), buffers, flags, ec);
  445. }
  446. /// Start an asynchronous receive.
  447. /**
  448. * This function is used to asynchronously receive data from the stream
  449. * socket. The function call always returns immediately.
  450. *
  451. * @param buffers One or more buffers into which the data will be received.
  452. * Although the buffers object may be copied as necessary, ownership of the
  453. * underlying memory blocks is retained by the caller, which must guarantee
  454. * that they remain valid until the handler is called.
  455. *
  456. * @param handler The handler to be called when the receive operation
  457. * completes. Copies will be made of the handler as required. The function
  458. * signature of the handler must be:
  459. * @code void handler(
  460. * const boost::system::error_code& error, // Result of operation.
  461. * std::size_t bytes_transferred // Number of bytes received.
  462. * ); @endcode
  463. * Regardless of whether the asynchronous operation completes immediately or
  464. * not, the handler will not be invoked from within this function. Invocation
  465. * of the handler will be performed in a manner equivalent to using
  466. * boost::asio::io_service::post().
  467. *
  468. * @note The receive operation may not receive all of the requested number of
  469. * bytes. Consider using the @ref async_read function if you need to ensure
  470. * that the requested amount of data is received before the asynchronous
  471. * operation completes.
  472. *
  473. * @par Example
  474. * To receive into a single data buffer use the @ref buffer function as
  475. * follows:
  476. * @code
  477. * socket.async_receive(boost::asio::buffer(data, size), handler);
  478. * @endcode
  479. * See the @ref buffer documentation for information on receiving into
  480. * multiple buffers in one go, and how to use it with arrays, boost::array or
  481. * std::vector.
  482. */
  483. template <typename MutableBufferSequence, typename ReadHandler>
  484. void async_receive(const MutableBufferSequence& buffers,
  485. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  486. {
  487. // If you get an error on the following line it means that your handler does
  488. // not meet the documented type requirements for a ReadHandler.
  489. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  490. this->get_service().async_receive(this->get_implementation(),
  491. buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  492. }
  493. /// Start an asynchronous receive.
  494. /**
  495. * This function is used to asynchronously receive data from the stream
  496. * socket. The function call always returns immediately.
  497. *
  498. * @param buffers One or more buffers into which the data will be received.
  499. * Although the buffers object may be copied as necessary, ownership of the
  500. * underlying memory blocks is retained by the caller, which must guarantee
  501. * that they remain valid until the handler is called.
  502. *
  503. * @param flags Flags specifying how the receive call is to be made.
  504. *
  505. * @param handler The handler to be called when the receive operation
  506. * completes. Copies will be made of the handler as required. The function
  507. * signature of the handler must be:
  508. * @code void handler(
  509. * const boost::system::error_code& error, // Result of operation.
  510. * std::size_t bytes_transferred // Number of bytes received.
  511. * ); @endcode
  512. * Regardless of whether the asynchronous operation completes immediately or
  513. * not, the handler will not be invoked from within this function. Invocation
  514. * of the handler will be performed in a manner equivalent to using
  515. * boost::asio::io_service::post().
  516. *
  517. * @note The receive operation may not receive all of the requested number of
  518. * bytes. Consider using the @ref async_read function if you need to ensure
  519. * that the requested amount of data is received before the asynchronous
  520. * operation completes.
  521. *
  522. * @par Example
  523. * To receive into a single data buffer use the @ref buffer function as
  524. * follows:
  525. * @code
  526. * socket.async_receive(boost::asio::buffer(data, size), 0, handler);
  527. * @endcode
  528. * See the @ref buffer documentation for information on receiving into
  529. * multiple buffers in one go, and how to use it with arrays, boost::array or
  530. * std::vector.
  531. */
  532. template <typename MutableBufferSequence, typename ReadHandler>
  533. void async_receive(const MutableBufferSequence& buffers,
  534. socket_base::message_flags flags,
  535. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  536. {
  537. // If you get an error on the following line it means that your handler does
  538. // not meet the documented type requirements for a ReadHandler.
  539. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  540. this->get_service().async_receive(this->get_implementation(),
  541. buffers, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  542. }
  543. /// Write some data to the socket.
  544. /**
  545. * This function is used to write data to the stream socket. The function call
  546. * will block until one or more bytes of the data has been written
  547. * successfully, or until an error occurs.
  548. *
  549. * @param buffers One or more data buffers to be written to the socket.
  550. *
  551. * @returns The number of bytes written.
  552. *
  553. * @throws boost::system::system_error Thrown on failure. An error code of
  554. * boost::asio::error::eof indicates that the connection was closed by the
  555. * peer.
  556. *
  557. * @note The write_some operation may not transmit all of the data to the
  558. * peer. Consider using the @ref write function if you need to ensure that
  559. * all data is written before the blocking operation completes.
  560. *
  561. * @par Example
  562. * To write a single data buffer use the @ref buffer function as follows:
  563. * @code
  564. * socket.write_some(boost::asio::buffer(data, size));
  565. * @endcode
  566. * See the @ref buffer documentation for information on writing multiple
  567. * buffers in one go, and how to use it with arrays, boost::array or
  568. * std::vector.
  569. */
  570. template <typename ConstBufferSequence>
  571. std::size_t write_some(const ConstBufferSequence& buffers)
  572. {
  573. boost::system::error_code ec;
  574. std::size_t s = this->get_service().send(
  575. this->get_implementation(), buffers, 0, ec);
  576. boost::asio::detail::throw_error(ec, "write_some");
  577. return s;
  578. }
  579. /// Write some data to the socket.
  580. /**
  581. * This function is used to write data to the stream socket. The function call
  582. * will block until one or more bytes of the data has been written
  583. * successfully, or until an error occurs.
  584. *
  585. * @param buffers One or more data buffers to be written to the socket.
  586. *
  587. * @param ec Set to indicate what error occurred, if any.
  588. *
  589. * @returns The number of bytes written. Returns 0 if an error occurred.
  590. *
  591. * @note The write_some operation may not transmit all of the data to the
  592. * peer. Consider using the @ref write function if you need to ensure that
  593. * all data is written before the blocking operation completes.
  594. */
  595. template <typename ConstBufferSequence>
  596. std::size_t write_some(const ConstBufferSequence& buffers,
  597. boost::system::error_code& ec)
  598. {
  599. return this->get_service().send(this->get_implementation(), buffers, 0, ec);
  600. }
  601. /// Start an asynchronous write.
  602. /**
  603. * This function is used to asynchronously write data to the stream socket.
  604. * The function call always returns immediately.
  605. *
  606. * @param buffers One or more data buffers to be written to the socket.
  607. * Although the buffers object may be copied as necessary, ownership of the
  608. * underlying memory blocks is retained by the caller, which must guarantee
  609. * that they remain valid until the handler is called.
  610. *
  611. * @param handler The handler to be called when the write operation completes.
  612. * Copies will be made of the handler as required. The function signature of
  613. * the handler must be:
  614. * @code void handler(
  615. * const boost::system::error_code& error, // Result of operation.
  616. * std::size_t bytes_transferred // Number of bytes written.
  617. * ); @endcode
  618. * Regardless of whether the asynchronous operation completes immediately or
  619. * not, the handler will not be invoked from within this function. Invocation
  620. * of the handler will be performed in a manner equivalent to using
  621. * boost::asio::io_service::post().
  622. *
  623. * @note The write operation may not transmit all of the data to the peer.
  624. * Consider using the @ref async_write function if you need to ensure that all
  625. * data is written before the asynchronous operation completes.
  626. *
  627. * @par Example
  628. * To write a single data buffer use the @ref buffer function as follows:
  629. * @code
  630. * socket.async_write_some(boost::asio::buffer(data, size), handler);
  631. * @endcode
  632. * See the @ref buffer documentation for information on writing multiple
  633. * buffers in one go, and how to use it with arrays, boost::array or
  634. * std::vector.
  635. */
  636. template <typename ConstBufferSequence, typename WriteHandler>
  637. void async_write_some(const ConstBufferSequence& buffers,
  638. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  639. {
  640. // If you get an error on the following line it means that your handler does
  641. // not meet the documented type requirements for a WriteHandler.
  642. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  643. this->get_service().async_send(this->get_implementation(),
  644. buffers, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  645. }
  646. /// Read some data from the socket.
  647. /**
  648. * This function is used to read data from the stream socket. The function
  649. * call will block until one or more bytes of data has been read successfully,
  650. * or until an error occurs.
  651. *
  652. * @param buffers One or more buffers into which the data will be read.
  653. *
  654. * @returns The number of bytes read.
  655. *
  656. * @throws boost::system::system_error Thrown on failure. An error code of
  657. * boost::asio::error::eof indicates that the connection was closed by the
  658. * peer.
  659. *
  660. * @note The read_some operation may not read all of the requested number of
  661. * bytes. Consider using the @ref read function if you need to ensure that
  662. * the requested amount of data is read before the blocking operation
  663. * completes.
  664. *
  665. * @par Example
  666. * To read into a single data buffer use the @ref buffer function as follows:
  667. * @code
  668. * socket.read_some(boost::asio::buffer(data, size));
  669. * @endcode
  670. * See the @ref buffer documentation for information on reading into multiple
  671. * buffers in one go, and how to use it with arrays, boost::array or
  672. * std::vector.
  673. */
  674. template <typename MutableBufferSequence>
  675. std::size_t read_some(const MutableBufferSequence& buffers)
  676. {
  677. boost::system::error_code ec;
  678. std::size_t s = this->get_service().receive(
  679. this->get_implementation(), buffers, 0, ec);
  680. boost::asio::detail::throw_error(ec, "read_some");
  681. return s;
  682. }
  683. /// Read some data from the socket.
  684. /**
  685. * This function is used to read data from the stream socket. The function
  686. * call will block until one or more bytes of data has been read successfully,
  687. * or until an error occurs.
  688. *
  689. * @param buffers One or more buffers into which the data will be read.
  690. *
  691. * @param ec Set to indicate what error occurred, if any.
  692. *
  693. * @returns The number of bytes read. Returns 0 if an error occurred.
  694. *
  695. * @note The read_some operation may not read all of the requested number of
  696. * bytes. Consider using the @ref read function if you need to ensure that
  697. * the requested amount of data is read before the blocking operation
  698. * completes.
  699. */
  700. template <typename MutableBufferSequence>
  701. std::size_t read_some(const MutableBufferSequence& buffers,
  702. boost::system::error_code& ec)
  703. {
  704. return this->get_service().receive(
  705. this->get_implementation(), buffers, 0, ec);
  706. }
  707. /// Start an asynchronous read.
  708. /**
  709. * This function is used to asynchronously read data from the stream socket.
  710. * The function call always returns immediately.
  711. *
  712. * @param buffers One or more buffers into which the data will be read.
  713. * Although the buffers object may be copied as necessary, ownership of the
  714. * underlying memory blocks is retained by the caller, which must guarantee
  715. * that they remain valid until the handler is called.
  716. *
  717. * @param handler The handler to be called when the read operation completes.
  718. * Copies will be made of the handler as required. The function signature of
  719. * the handler must be:
  720. * @code void handler(
  721. * const boost::system::error_code& error, // Result of operation.
  722. * std::size_t bytes_transferred // Number of bytes read.
  723. * ); @endcode
  724. * Regardless of whether the asynchronous operation completes immediately or
  725. * not, the handler will not be invoked from within this function. Invocation
  726. * of the handler will be performed in a manner equivalent to using
  727. * boost::asio::io_service::post().
  728. *
  729. * @note The read operation may not read all of the requested number of bytes.
  730. * Consider using the @ref async_read function if you need to ensure that the
  731. * requested amount of data is read before the asynchronous operation
  732. * completes.
  733. *
  734. * @par Example
  735. * To read into a single data buffer use the @ref buffer function as follows:
  736. * @code
  737. * socket.async_read_some(boost::asio::buffer(data, size), handler);
  738. * @endcode
  739. * See the @ref buffer documentation for information on reading into multiple
  740. * buffers in one go, and how to use it with arrays, boost::array or
  741. * std::vector.
  742. */
  743. template <typename MutableBufferSequence, typename ReadHandler>
  744. void async_read_some(const MutableBufferSequence& buffers,
  745. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  746. {
  747. // If you get an error on the following line it means that your handler does
  748. // not meet the documented type requirements for a ReadHandler.
  749. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  750. this->get_service().async_receive(this->get_implementation(),
  751. buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  752. }
  753. };
  754. } // namespace asio
  755. } // namespace boost
  756. #include <boost/asio/detail/pop_options.hpp>
  757. #endif // BOOST_ASIO_BASIC_STREAM_SOCKET_HPP