boost/asio/write_at.hpp

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