/src/contrib/boost/asio/write.hpp

http://pythonocc.googlecode.com/ · C++ Header · 542 lines · 58 code · 27 blank · 457 comment · 1 complexity · 6549f05c16375f09596c12eea69d8877 MD5 · raw file

  1. //
  2. // write.hpp
  3. // ~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2010 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_WRITE_HPP
  11. #define BOOST_ASIO_WRITE_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/push_options.hpp>
  16. #include <boost/asio/detail/push_options.hpp>
  17. #include <cstddef>
  18. #include <boost/config.hpp>
  19. #include <boost/asio/detail/pop_options.hpp>
  20. #include <boost/asio/basic_streambuf.hpp>
  21. #include <boost/asio/error.hpp>
  22. namespace boost {
  23. namespace asio {
  24. /**
  25. * @defgroup write boost::asio::write
  26. *
  27. * @brief Write a certain amount of data to a stream before returning.
  28. */
  29. /*@{*/
  30. /// Write all of the supplied data to a stream before returning.
  31. /**
  32. * This function is used to write a certain number of bytes of data to a stream.
  33. * The call will block until one of the following conditions is true:
  34. *
  35. * @li All of the data in the supplied buffers has been written. That is, the
  36. * bytes transferred is equal to the sum of the buffer sizes.
  37. *
  38. * @li An error occurred.
  39. *
  40. * This operation is implemented in terms of zero or more calls to the stream's
  41. * write_some function.
  42. *
  43. * @param s The stream to which the data is to be written. The type must support
  44. * the SyncWriteStream concept.
  45. *
  46. * @param buffers One or more buffers containing the data to be written. The sum
  47. * of the buffer sizes indicates the maximum number of bytes to write to the
  48. * stream.
  49. *
  50. * @returns The number of bytes transferred.
  51. *
  52. * @throws boost::system::system_error Thrown on failure.
  53. *
  54. * @par Example
  55. * To write a single data buffer use the @ref buffer function as follows:
  56. * @code boost::asio::write(s, boost::asio::buffer(data, size)); @endcode
  57. * See the @ref buffer documentation for information on writing multiple
  58. * buffers in one go, and how to use it with arrays, boost::array or
  59. * std::vector.
  60. *
  61. * @note This overload is equivalent to calling:
  62. * @code boost::asio::write(
  63. * s, buffers,
  64. * boost::asio::transfer_all()); @endcode
  65. */
  66. template <typename SyncWriteStream, typename ConstBufferSequence>
  67. std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers);
  68. /// Write a certain amount of data to a stream before returning.
  69. /**
  70. * This function is used to write a certain number of bytes of data to a stream.
  71. * The call will block until one of the following conditions is true:
  72. *
  73. * @li All of the data in the supplied buffers has been written. That is, the
  74. * bytes transferred is equal to the sum of the buffer sizes.
  75. *
  76. * @li The completion_condition function object returns 0.
  77. *
  78. * This operation is implemented in terms of zero or more calls to the stream's
  79. * write_some function.
  80. *
  81. * @param s The stream to which the data is to be written. The type must support
  82. * the SyncWriteStream concept.
  83. *
  84. * @param buffers One or more buffers containing the data to be written. The sum
  85. * of the buffer sizes indicates the maximum number of bytes to write to the
  86. * stream.
  87. *
  88. * @param completion_condition The function object to be called to determine
  89. * whether the write operation is complete. The signature of the function object
  90. * must be:
  91. * @code std::size_t completion_condition(
  92. * // Result of latest write_some operation.
  93. * const boost::system::error_code& error,
  94. *
  95. * // Number of bytes transferred so far.
  96. * std::size_t bytes_transferred
  97. * ); @endcode
  98. * A return value of 0 indicates that the write operation is complete. A
  99. * non-zero return value indicates the maximum number of bytes to be written on
  100. * the next call to the stream's write_some function.
  101. *
  102. * @returns The number of bytes transferred.
  103. *
  104. * @throws boost::system::system_error Thrown on failure.
  105. *
  106. * @par Example
  107. * To write a single data buffer use the @ref buffer function as follows:
  108. * @code boost::asio::write(s, boost::asio::buffer(data, size),
  109. * boost::asio::transfer_at_least(32)); @endcode
  110. * See the @ref buffer documentation for information on writing multiple
  111. * buffers in one go, and how to use it with arrays, boost::array or
  112. * std::vector.
  113. */
  114. template <typename SyncWriteStream, typename ConstBufferSequence,
  115. typename CompletionCondition>
  116. std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
  117. CompletionCondition completion_condition);
  118. /// Write a certain amount of data to a stream before returning.
  119. /**
  120. * This function is used to write a certain number of bytes of data to a stream.
  121. * The call will block until one of the following conditions is true:
  122. *
  123. * @li All of the data in the supplied buffers has been written. That is, the
  124. * bytes transferred is equal to the sum of the buffer sizes.
  125. *
  126. * @li The completion_condition function object returns 0.
  127. *
  128. * This operation is implemented in terms of zero or more calls to the stream's
  129. * write_some function.
  130. *
  131. * @param s The stream to which the data is to be written. The type must support
  132. * the SyncWriteStream concept.
  133. *
  134. * @param buffers One or more buffers containing the data to be written. The sum
  135. * of the buffer sizes indicates the maximum number of bytes to write to the
  136. * stream.
  137. *
  138. * @param completion_condition The function object to be called to determine
  139. * whether the write operation is complete. The signature of the function object
  140. * must be:
  141. * @code std::size_t completion_condition(
  142. * // Result of latest write_some operation.
  143. * const boost::system::error_code& error,
  144. *
  145. * // Number of bytes transferred so far.
  146. * std::size_t bytes_transferred
  147. * ); @endcode
  148. * A return value of 0 indicates that the write operation is complete. A
  149. * non-zero return value indicates the maximum number of bytes to be written on
  150. * the next call to the stream's write_some function.
  151. *
  152. * @param ec Set to indicate what error occurred, if any.
  153. *
  154. * @returns The number of bytes written. If an error occurs, returns the total
  155. * number of bytes successfully transferred prior to the error.
  156. */
  157. template <typename SyncWriteStream, typename ConstBufferSequence,
  158. typename CompletionCondition>
  159. std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
  160. CompletionCondition completion_condition, boost::system::error_code& ec);
  161. #if !defined(BOOST_NO_IOSTREAM)
  162. /// Write all of the supplied data to a stream before returning.
  163. /**
  164. * This function is used to write a certain number of bytes of data to a stream.
  165. * The call will block until one of the following conditions is true:
  166. *
  167. * @li All of the data in the supplied basic_streambuf has been written.
  168. *
  169. * @li An error occurred.
  170. *
  171. * This operation is implemented in terms of zero or more calls to the stream's
  172. * write_some function.
  173. *
  174. * @param s The stream to which the data is to be written. The type must support
  175. * the SyncWriteStream concept.
  176. *
  177. * @param b The basic_streambuf object from which data will be written.
  178. *
  179. * @returns The number of bytes transferred.
  180. *
  181. * @throws boost::system::system_error Thrown on failure.
  182. *
  183. * @note This overload is equivalent to calling:
  184. * @code boost::asio::write(
  185. * s, b,
  186. * boost::asio::transfer_all()); @endcode
  187. */
  188. template <typename SyncWriteStream, typename Allocator>
  189. std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b);
  190. /// Write a certain amount of data to a stream before returning.
  191. /**
  192. * This function is used to write a certain number of bytes of data to a stream.
  193. * The call will block until one of the following conditions is true:
  194. *
  195. * @li All of the data in the supplied basic_streambuf has been written.
  196. *
  197. * @li The completion_condition function object returns 0.
  198. *
  199. * This operation is implemented in terms of zero or more calls to the stream's
  200. * write_some function.
  201. *
  202. * @param s The stream to which the data is to be written. The type must support
  203. * the SyncWriteStream concept.
  204. *
  205. * @param b The basic_streambuf object from which data will be written.
  206. *
  207. * @param completion_condition The function object to be called to determine
  208. * whether the write operation is complete. The signature of the function object
  209. * must be:
  210. * @code std::size_t completion_condition(
  211. * // Result of latest write_some operation.
  212. * const boost::system::error_code& error,
  213. *
  214. * // Number of bytes transferred so far.
  215. * std::size_t bytes_transferred
  216. * ); @endcode
  217. * A return value of 0 indicates that the write operation is complete. A
  218. * non-zero return value indicates the maximum number of bytes to be written on
  219. * the next call to the stream's write_some function.
  220. *
  221. * @returns The number of bytes transferred.
  222. *
  223. * @throws boost::system::system_error Thrown on failure.
  224. */
  225. template <typename SyncWriteStream, typename Allocator,
  226. typename CompletionCondition>
  227. std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
  228. CompletionCondition completion_condition);
  229. /// Write a certain amount of data to a stream before returning.
  230. /**
  231. * This function is used to write a certain number of bytes of data to a stream.
  232. * The call will block until one of the following conditions is true:
  233. *
  234. * @li All of the data in the supplied basic_streambuf has been written.
  235. *
  236. * @li The completion_condition function object returns 0.
  237. *
  238. * This operation is implemented in terms of zero or more calls to the stream's
  239. * write_some function.
  240. *
  241. * @param s The stream to which the data is to be written. The type must support
  242. * the SyncWriteStream concept.
  243. *
  244. * @param b The basic_streambuf object from which data will be written.
  245. *
  246. * @param completion_condition The function object to be called to determine
  247. * whether the write operation is complete. The signature of the function object
  248. * must be:
  249. * @code std::size_t completion_condition(
  250. * // Result of latest write_some operation.
  251. * const boost::system::error_code& error,
  252. *
  253. * // Number of bytes transferred so far.
  254. * std::size_t bytes_transferred
  255. * ); @endcode
  256. * A return value of 0 indicates that the write operation is complete. A
  257. * non-zero return value indicates the maximum number of bytes to be written on
  258. * the next call to the stream's write_some function.
  259. *
  260. * @param ec Set to indicate what error occurred, if any.
  261. *
  262. * @returns The number of bytes written. If an error occurs, returns the total
  263. * number of bytes successfully transferred prior to the error.
  264. */
  265. template <typename SyncWriteStream, typename Allocator,
  266. typename CompletionCondition>
  267. std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
  268. CompletionCondition completion_condition, boost::system::error_code& ec);
  269. #endif // !defined(BOOST_NO_IOSTREAM)
  270. /*@}*/
  271. /**
  272. * @defgroup async_write boost::asio::async_write
  273. *
  274. * @brief Start an asynchronous operation to write a certain amount of data to a
  275. * stream.
  276. */
  277. /*@{*/
  278. /// Start an asynchronous operation to write all of the supplied data to a
  279. /// stream.
  280. /**
  281. * This function is used to asynchronously write a certain number of bytes of
  282. * data to a stream. The function call always returns immediately. The
  283. * asynchronous operation will continue until one of the following conditions
  284. * is true:
  285. *
  286. * @li All of the data in the supplied buffers has been written. That is, the
  287. * bytes transferred is equal to the sum of the buffer sizes.
  288. *
  289. * @li An error occurred.
  290. *
  291. * This operation is implemented in terms of zero or more calls to the stream's
  292. * async_write_some function, and is known as a <em>composed operation</em>. The
  293. * program must ensure that the stream performs no other write operations (such
  294. * as async_write, the stream's async_write_some function, or any other composed
  295. * operations that perform writes) until this operation completes.
  296. *
  297. * @param s The stream to which the data is to be written. The type must support
  298. * the AsyncWriteStream concept.
  299. *
  300. * @param buffers One or more buffers containing the data to be written.
  301. * Although the buffers object may be copied as necessary, ownership of the
  302. * underlying memory blocks is retained by the caller, which must guarantee
  303. * that they remain valid until the handler is called.
  304. *
  305. * @param handler The handler to be called when the write operation completes.
  306. * Copies will be made of the handler as required. The function signature of
  307. * the handler must be:
  308. * @code void handler(
  309. * const boost::system::error_code& error, // Result of operation.
  310. *
  311. * std::size_t bytes_transferred // Number of bytes written from the
  312. * // buffers. If an error occurred,
  313. * // this will be less than the sum
  314. * // of the buffer sizes.
  315. * ); @endcode
  316. * Regardless of whether the asynchronous operation completes immediately or
  317. * not, the handler will not be invoked from within this function. Invocation of
  318. * the handler will be performed in a manner equivalent to using
  319. * boost::asio::io_service::post().
  320. *
  321. * @par Example
  322. * To write a single data buffer use the @ref buffer function as follows:
  323. * @code
  324. * boost::asio::async_write(s, boost::asio::buffer(data, size), handler);
  325. * @endcode
  326. * See the @ref buffer documentation for information on writing multiple
  327. * buffers in one go, and how to use it with arrays, boost::array or
  328. * std::vector.
  329. */
  330. template <typename AsyncWriteStream, typename ConstBufferSequence,
  331. typename WriteHandler>
  332. void async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
  333. WriteHandler handler);
  334. /// Start an asynchronous operation to write a certain amount of data to a
  335. /// stream.
  336. /**
  337. * This function is used to asynchronously write a certain number of bytes of
  338. * data to a stream. The function call always returns immediately. The
  339. * asynchronous operation will continue until one of the following conditions
  340. * is true:
  341. *
  342. * @li All of the data in the supplied buffers has been written. That is, the
  343. * bytes transferred is equal to the sum of the buffer sizes.
  344. *
  345. * @li The completion_condition function object returns 0.
  346. *
  347. * This operation is implemented in terms of zero or more calls to the stream's
  348. * async_write_some function, and is known as a <em>composed operation</em>. The
  349. * program must ensure that the stream performs no other write operations (such
  350. * as async_write, the stream's async_write_some function, or any other composed
  351. * operations that perform writes) until this operation completes.
  352. *
  353. * @param s The stream to which the data is to be written. The type must support
  354. * the AsyncWriteStream concept.
  355. *
  356. * @param buffers One or more buffers containing the data to be written.
  357. * Although the buffers object may be copied as necessary, ownership of the
  358. * underlying memory blocks is retained by the caller, which must guarantee
  359. * that they remain valid until the handler is called.
  360. *
  361. * @param completion_condition The function object to be called to determine
  362. * whether the write operation is complete. The signature of the function object
  363. * must be:
  364. * @code std::size_t completion_condition(
  365. * // Result of latest async_write_some operation.
  366. * const boost::system::error_code& error,
  367. *
  368. * // Number of bytes transferred so far.
  369. * std::size_t bytes_transferred
  370. * ); @endcode
  371. * A return value of 0 indicates that the write operation is complete. A
  372. * non-zero return value indicates the maximum number of bytes to be written on
  373. * the next call to the stream's async_write_some function.
  374. *
  375. * @param handler The handler to be called when the write operation completes.
  376. * Copies will be made of the handler as required. The function signature of the
  377. * handler must be:
  378. * @code void handler(
  379. * const boost::system::error_code& error, // Result of operation.
  380. *
  381. * std::size_t bytes_transferred // Number of bytes written from the
  382. * // buffers. If an error occurred,
  383. * // this will be less than the sum
  384. * // of the buffer sizes.
  385. * ); @endcode
  386. * Regardless of whether the asynchronous operation completes immediately or
  387. * not, the handler will not be invoked from within this function. Invocation of
  388. * the handler will be performed in a manner equivalent to using
  389. * boost::asio::io_service::post().
  390. *
  391. * @par Example
  392. * To write a single data buffer use the @ref buffer function as follows:
  393. * @code boost::asio::async_write(s,
  394. * boost::asio::buffer(data, size),
  395. * boost::asio::transfer_at_least(32),
  396. * handler); @endcode
  397. * See the @ref buffer documentation for information on writing multiple
  398. * buffers in one go, and how to use it with arrays, boost::array or
  399. * std::vector.
  400. */
  401. template <typename AsyncWriteStream, typename ConstBufferSequence,
  402. typename CompletionCondition, typename WriteHandler>
  403. void async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
  404. CompletionCondition completion_condition, WriteHandler handler);
  405. #if !defined(BOOST_NO_IOSTREAM)
  406. /// Start an asynchronous operation to write all of the supplied data to a
  407. /// stream.
  408. /**
  409. * This function is used to asynchronously write a certain number of bytes of
  410. * data to a stream. The function call always returns immediately. The
  411. * asynchronous operation will continue until one of the following conditions
  412. * is true:
  413. *
  414. * @li All of the data in the supplied basic_streambuf has been written.
  415. *
  416. * @li An error occurred.
  417. *
  418. * This operation is implemented in terms of zero or more calls to the stream's
  419. * async_write_some function, and is known as a <em>composed operation</em>. The
  420. * program must ensure that the stream performs no other write operations (such
  421. * as async_write, the stream's async_write_some function, or any other composed
  422. * operations that perform writes) until this operation completes.
  423. *
  424. * @param s The stream to which the data is to be written. The type must support
  425. * the AsyncWriteStream concept.
  426. *
  427. * @param b A basic_streambuf object from which data will be written. Ownership
  428. * of the streambuf is retained by the caller, which must guarantee that it
  429. * remains valid until the handler is called.
  430. *
  431. * @param handler The handler to be called when the write operation completes.
  432. * Copies will be made of the handler as required. The function signature of the
  433. * handler must be:
  434. * @code void handler(
  435. * const boost::system::error_code& error, // Result of operation.
  436. *
  437. * std::size_t bytes_transferred // Number of bytes written from the
  438. * // buffers. If an error occurred,
  439. * // this will be less than the sum
  440. * // of the buffer sizes.
  441. * ); @endcode
  442. * Regardless of whether the asynchronous operation completes immediately or
  443. * not, the handler will not be invoked from within this function. Invocation of
  444. * the handler will be performed in a manner equivalent to using
  445. * boost::asio::io_service::post().
  446. */
  447. template <typename AsyncWriteStream, typename Allocator, typename WriteHandler>
  448. void async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
  449. WriteHandler handler);
  450. /// Start an asynchronous operation to write a certain amount of data to a
  451. /// stream.
  452. /**
  453. * This function is used to asynchronously write a certain number of bytes of
  454. * data to a stream. The function call always returns immediately. The
  455. * asynchronous operation will continue until one of the following conditions
  456. * is true:
  457. *
  458. * @li All of the data in the supplied basic_streambuf has been written.
  459. *
  460. * @li The completion_condition function object returns 0.
  461. *
  462. * This operation is implemented in terms of zero or more calls to the stream's
  463. * async_write_some function, and is known as a <em>composed operation</em>. The
  464. * program must ensure that the stream performs no other write operations (such
  465. * as async_write, the stream's async_write_some function, or any other composed
  466. * operations that perform writes) until this operation completes.
  467. *
  468. * @param s The stream to which the data is to be written. The type must support
  469. * the AsyncWriteStream concept.
  470. *
  471. * @param b A basic_streambuf object from which data will be written. Ownership
  472. * of the streambuf is retained by the caller, which must guarantee that it
  473. * remains valid until the handler is called.
  474. *
  475. * @param completion_condition The function object to be called to determine
  476. * whether the write operation is complete. The signature of the function object
  477. * must be:
  478. * @code std::size_t completion_condition(
  479. * // Result of latest async_write_some operation.
  480. * const boost::system::error_code& error,
  481. *
  482. * // Number of bytes transferred so far.
  483. * std::size_t bytes_transferred
  484. * ); @endcode
  485. * A return value of 0 indicates that the write operation is complete. A
  486. * non-zero return value indicates the maximum number of bytes to be written on
  487. * the next call to the stream's async_write_some function.
  488. *
  489. * @param handler The handler to be called when the write operation completes.
  490. * Copies will be made of the handler as required. The function signature of the
  491. * handler must be:
  492. * @code void handler(
  493. * const boost::system::error_code& error, // Result of operation.
  494. *
  495. * std::size_t bytes_transferred // Number of bytes written from the
  496. * // buffers. If an error occurred,
  497. * // this will be less than the sum
  498. * // of the buffer sizes.
  499. * ); @endcode
  500. * Regardless of whether the asynchronous operation completes immediately or
  501. * not, the handler will not be invoked from within this function. Invocation of
  502. * the handler will be performed in a manner equivalent to using
  503. * boost::asio::io_service::post().
  504. */
  505. template <typename AsyncWriteStream, typename Allocator,
  506. typename CompletionCondition, typename WriteHandler>
  507. void async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
  508. CompletionCondition completion_condition, WriteHandler handler);
  509. #endif // !defined(BOOST_NO_IOSTREAM)
  510. /*@}*/
  511. } // namespace asio
  512. } // namespace boost
  513. #include <boost/asio/impl/write.ipp>
  514. #include <boost/asio/detail/pop_options.hpp>
  515. #endif // BOOST_ASIO_WRITE_HPP