boost/asio/write.hpp

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