boost/asio/write_at.hpp

   1 //
   2 // write_at.hpp
   3 // ~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 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/config.hpp>
  19 #include <cstddef>
  20 #include <boost/asio/async_result.hpp>
  21 #include <boost/asio/detail/cstdint.hpp>
  22 #include <boost/asio/error.hpp>
  23
  24 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  25 # include <boost/asio/basic_streambuf_fwd.hpp>
  26 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  27
  28 #include <boost/asio/detail/push_options.hpp>
  29
  30 namespace boost {
  31 namespace asio {
  32
  33 /**
  34  * @defgroup write_at boost::asio::write_at
  35  *
  36  * @brief The @c write_at function is a composed operation that writes a
  37  * certain amount of data at a specified offset before returning.
  38  */
  39 /*@{*/
  40
  41 /// Write all of the supplied data at the specified offset before returning.
  42 /**
  43  * This function is used to write a certain number of bytes of data to a random
  44  * access device at a specified offset. The call will block until one of the
  45  * following conditions is true:
  46  *
  47  * @li All of the data in the supplied buffers has been written. That is, the
  48  * bytes transferred is equal to the sum of the buffer sizes.
  49  *
  50  * @li An error occurred.
  51  *
  52  * This operation is implemented in terms of zero or more calls to the device's
  53  * write_some_at function.
  54  *
  55  * @param d The device to which the data is to be written. The type must support
  56  * the SyncRandomAccessWriteDevice concept.
  57  *
  58  * @param offset The offset at which the data will be written.
  59  *
  60  * @param buffers One or more buffers containing the data to be written. The sum
  61  * of the buffer sizes indicates the maximum number of bytes to write to the
  62  * device.
  63  *
  64  * @returns The number of bytes transferred.
  65  *
  66  * @throws boost::system::system_error Thrown on failure.
  67  *
  68  * @par Example
  69  * To write a single data buffer use the @ref buffer function as follows:
  70  * @code boost::asio::write_at(d, 42, boost::asio::buffer(data, size)); @endcode
  71  * See the @ref buffer documentation for information on writing multiple
  72  * buffers in one go, and how to use it with arrays, boost::array or
  73  * std::vector.
  74  *
  75  * @note This overload is equivalent to calling:
  76  * @code boost::asio::write_at(
  77  *     d, offset, buffers,
  78  *     boost::asio::transfer_all()); @endcode
  79  */
  80 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence>
  81 std::size_t write_at(SyncRandomAccessWriteDevice& d,
  82     uint64_t offset, const ConstBufferSequence& buffers);
  83
  84 /// Write all of the supplied data at the specified offset before returning.
  85 /**
  86  * This function is used to write a certain number of bytes of data to a random
  87  * access device at a specified offset. The call will block until one of the
  88  * following conditions is true:
  89  *
  90  * @li All of the data in the supplied buffers has been written. That is, the
  91  * bytes transferred is equal to the sum of the buffer sizes.
  92  *
  93  * @li An error occurred.
  94  *
  95  * This operation is implemented in terms of zero or more calls to the device's
  96  * write_some_at function.
  97  *
  98  * @param d The device to which the data is to be written. The type must support
  99  * the SyncRandomAccessWriteDevice concept.
 100  *
 101  * @param offset The offset at which the data will be written.
 102  *
 103  * @param buffers One or more buffers containing the data to be written. The sum
 104  * of the buffer sizes indicates the maximum number of bytes to write to the
 105  * device.
 106  *
 107  * @param ec Set to indicate what error occurred, if any.
 108  *
 109  * @returns The number of bytes transferred.
 110  *
 111  * @par Example
 112  * To write a single data buffer use the @ref buffer function as follows:
 113  * @code boost::asio::write_at(d, 42,
 114  *     boost::asio::buffer(data, size), ec); @endcode
 115  * See the @ref buffer documentation for information on writing multiple
 116  * buffers in one go, and how to use it with arrays, boost::array or
 117  * std::vector.
 118  *
 119  * @note This overload is equivalent to calling:
 120  * @code boost::asio::write_at(
 121  *     d, offset, buffers,
 122  *     boost::asio::transfer_all(), ec); @endcode
 123  */
 124 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence>
 125 std::size_t write_at(SyncRandomAccessWriteDevice& d,
 126     uint64_t offset, const ConstBufferSequence& buffers,
 127     boost::system::error_code& ec);
 128
 129 /// Write a certain amount of data at a specified offset before returning.
 130 /**
 131  * This function is used to write a certain number of bytes of data to a random
 132  * access device at a specified offset. The call will block until one of the
 133  * following conditions is true:
 134  *
 135  * @li All of the data in the supplied buffers has been written. That is, the
 136  * bytes transferred is equal to the sum of the buffer sizes.
 137  *
 138  * @li The completion_condition function object returns 0.
 139  *
 140  * This operation is implemented in terms of zero or more calls to the device's
 141  * write_some_at function.
 142  *
 143  * @param d The device to which the data is to be written. The type must support
 144  * the SyncRandomAccessWriteDevice concept.
 145  *
 146  * @param offset The offset at which the data will be written.
 147  *
 148  * @param buffers One or more buffers containing the data to be written. The sum
 149  * of the buffer sizes indicates the maximum number of bytes to write to the
 150  * device.
 151  *
 152  * @param completion_condition The function object to be called to determine
 153  * whether the write operation is complete. The signature of the function object
 154  * must be:
 155  * @code std::size_t completion_condition(
 156  *   // Result of latest write_some_at operation.
 157  *   const boost::system::error_code& error,
 158  *
 159  *   // Number of bytes transferred so far.
 160  *   std::size_t bytes_transferred
 161  * ); @endcode
 162  * A return value of 0 indicates that the write operation is complete. A
 163  * non-zero return value indicates the maximum number of bytes to be written on
 164  * the next call to the device's write_some_at function.
 165  *
 166  * @returns The number of bytes transferred.
 167  *
 168  * @throws boost::system::system_error Thrown on failure.
 169  *
 170  * @par Example
 171  * To write a single data buffer use the @ref buffer function as follows:
 172  * @code boost::asio::write_at(d, 42, boost::asio::buffer(data, size),
 173  *     boost::asio::transfer_at_least(32)); @endcode
 174  * See the @ref buffer documentation for information on writing multiple
 175  * buffers in one go, and how to use it with arrays, boost::array or
 176  * std::vector.
 177  */
 178 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
 179     typename CompletionCondition>
 180 std::size_t write_at(SyncRandomAccessWriteDevice& d,
 181     uint64_t offset, const ConstBufferSequence& buffers,
 182     CompletionCondition completion_condition);
 183
 184 /// Write a certain amount of data at a specified offset before returning.
 185 /**
 186  * This function is used to write a certain number of bytes of data to a random
 187  * access device at a specified offset. The call will block until one of the
 188  * following conditions is true:
 189  *
 190  * @li All of the data in the supplied buffers has been written. That is, the
 191  * bytes transferred is equal to the sum of the buffer sizes.
 192  *
 193  * @li The completion_condition function object returns 0.
 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 buffers One or more buffers containing the data to be written. The sum
 204  * of the buffer sizes indicates the maximum number of bytes to write to the
 205  * device.
 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_at 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 device's write_some_at function.
 220  *
 221  * @param ec Set to indicate what error occurred, if any.
 222  *
 223  * @returns The number of bytes written. If an error occurs, returns the total
 224  * number of bytes successfully transferred prior to the error.
 225  */
 226 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
 227     typename CompletionCondition>
 228 std::size_t write_at(SyncRandomAccessWriteDevice& d,
 229     uint64_t offset, const ConstBufferSequence& buffers,
 230     CompletionCondition completion_condition, boost::system::error_code& ec);
 231
 232 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 233 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 234
 235 /// Write all of the supplied data at the specified offset before returning.
 236 /**
 237  * This function is used to write a certain number of bytes of data to a random
 238  * access device at a specified offset. The call will block until one of the
 239  * following conditions is true:
 240  *
 241  * @li All of the data in the supplied basic_streambuf has been written.
 242  *
 243  * @li An error occurred.
 244  *
 245  * This operation is implemented in terms of zero or more calls to the device's
 246  * write_some_at function.
 247  *
 248  * @param d The device to which the data is to be written. The type must support
 249  * the SyncRandomAccessWriteDevice concept.
 250  *
 251  * @param offset The offset at which the data will be written.
 252  *
 253  * @param b The basic_streambuf object from which data will be written.
 254  *
 255  * @returns The number of bytes transferred.
 256  *
 257  * @throws boost::system::system_error Thrown on failure.
 258  *
 259  * @note This overload is equivalent to calling:
 260  * @code boost::asio::write_at(
 261  *     d, 42, b,
 262  *     boost::asio::transfer_all()); @endcode
 263  */
 264 template <typename SyncRandomAccessWriteDevice, typename Allocator>
 265 std::size_t write_at(SyncRandomAccessWriteDevice& d,
 266     uint64_t offset, basic_streambuf<Allocator>& b);
 267
 268 /// Write all of the supplied data at the specified offset before returning.
 269 /**
 270  * This function is used to write a certain number of bytes of data to a random
 271  * access device at a specified offset. The call will block until one of the
 272  * following conditions is true:
 273  *
 274  * @li All of the data in the supplied basic_streambuf has been written.
 275  *
 276  * @li An error occurred.
 277  *
 278  * This operation is implemented in terms of zero or more calls to the device's
 279  * write_some_at function.
 280  *
 281  * @param d The device to which the data is to be written. The type must support
 282  * the SyncRandomAccessWriteDevice concept.
 283  *
 284  * @param offset The offset at which the data will be written.
 285  *
 286  * @param b The basic_streambuf object from which data will be written.
 287  *
 288  * @param ec Set to indicate what error occurred, if any.
 289  *
 290  * @returns The number of bytes transferred.
 291  *
 292  * @note This overload is equivalent to calling:
 293  * @code boost::asio::write_at(
 294  *     d, 42, b,
 295  *     boost::asio::transfer_all(), ec); @endcode
 296  */
 297 template <typename SyncRandomAccessWriteDevice, typename Allocator>
 298 std::size_t write_at(SyncRandomAccessWriteDevice& d,
 299     uint64_t offset, basic_streambuf<Allocator>& b,
 300     boost::system::error_code& ec);
 301
 302 /// Write a certain amount of data at a specified offset before returning.
 303 /**
 304  * This function is used to write a certain number of bytes of data to a random
 305  * access device at a specified offset. The call will block until one of the
 306  * following conditions is true:
 307  *
 308  * @li All of the data in the supplied basic_streambuf has been written.
 309  *
 310  * @li The completion_condition function object returns 0.
 311  *
 312  * This operation is implemented in terms of zero or more calls to the device's
 313  * write_some_at function.
 314  *
 315  * @param d The device to which the data is to be written. The type must support
 316  * the SyncRandomAccessWriteDevice concept.
 317  *
 318  * @param offset The offset at which the data will be written.
 319  *
 320  * @param b The basic_streambuf object from which data will be written.
 321  *
 322  * @param completion_condition The function object to be called to determine
 323  * whether the write operation is complete. The signature of the function object
 324  * must be:
 325  * @code std::size_t completion_condition(
 326  *   // Result of latest write_some_at operation.
 327  *   const boost::system::error_code& error,
 328  *
 329  *   // Number of bytes transferred so far.
 330  *   std::size_t bytes_transferred
 331  * ); @endcode
 332  * A return value of 0 indicates that the write operation is complete. A
 333  * non-zero return value indicates the maximum number of bytes to be written on
 334  * the next call to the device's write_some_at function.
 335  *
 336  * @returns The number of bytes transferred.
 337  *
 338  * @throws boost::system::system_error Thrown on failure.
 339  */
 340 template <typename SyncRandomAccessWriteDevice, typename Allocator,
 341     typename CompletionCondition>
 342 std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset,
 343     basic_streambuf<Allocator>& b, CompletionCondition completion_condition);
 344
 345 /// Write a certain amount of data at a specified offset before returning.
 346 /**
 347  * This function is used to write a certain number of bytes of data to a random
 348  * access device at a specified offset. The call will block until one of the
 349  * following conditions is true:
 350  *
 351  * @li All of the data in the supplied basic_streambuf has been written.
 352  *
 353  * @li The completion_condition function object returns 0.
 354  *
 355  * This operation is implemented in terms of zero or more calls to the device's
 356  * write_some_at function.
 357  *
 358  * @param d The device to which the data is to be written. The type must support
 359  * the SyncRandomAccessWriteDevice concept.
 360  *
 361  * @param offset The offset at which the data will be written.
 362  *
 363  * @param b The basic_streambuf object from which data will be written.
 364  *
 365  * @param completion_condition The function object to be called to determine
 366  * whether the write operation is complete. The signature of the function object
 367  * must be:
 368  * @code std::size_t completion_condition(
 369  *   // Result of latest write_some_at operation.
 370  *   const boost::system::error_code& error,
 371  *
 372  *   // Number of bytes transferred so far.
 373  *   std::size_t bytes_transferred
 374  * ); @endcode
 375  * A return value of 0 indicates that the write operation is complete. A
 376  * non-zero return value indicates the maximum number of bytes to be written on
 377  * the next call to the device's write_some_at function.
 378  *
 379  * @param ec Set to indicate what error occurred, if any.
 380  *
 381  * @returns The number of bytes written. If an error occurs, returns the total
 382  * number of bytes successfully transferred prior to the error.
 383  */
 384 template <typename SyncRandomAccessWriteDevice, typename Allocator,
 385     typename CompletionCondition>
 386 std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset,
 387     basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
 388     boost::system::error_code& ec);
 389
 390 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 391 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 392
 393 /*@}*/
 394 /**
 395  * @defgroup async_write_at boost::asio::async_write_at
 396  *
 397  * @brief The @c async_write_at function is a composed asynchronous operation
 398  * that writes a certain amount of data at the specified offset before
 399  * completion.
 400  */
 401 /*@{*/
 402
 403 /// Start an asynchronous operation to write all of the supplied data at the
 404 /// specified offset.
 405 /**
 406  * This function is used to asynchronously write a certain number of bytes of
 407  * data to a random access device at a specified offset. The function call
 408  * always returns immediately. The asynchronous operation will continue until
 409  * one of the following conditions is true:
 410  *
 411  * @li All of the data in the supplied buffers has been written. That is, the
 412  * bytes transferred is equal to the sum of the buffer sizes.
 413  *
 414  * @li An error occurred.
 415  *
 416  * This operation is implemented in terms of zero or more calls to the device's
 417  * async_write_some_at function, and is known as a <em>composed operation</em>.
 418  * The program must ensure that the device performs no <em>overlapping</em>
 419  * write operations (such as async_write_at, the device's async_write_some_at
 420  * function, or any other composed operations that perform writes) until this
 421  * operation completes. Operations are overlapping if the regions defined by
 422  * their offsets, and the numbers of bytes to write, intersect.
 423  *
 424  * @param d The device to which the data is to be written. The type must support
 425  * the AsyncRandomAccessWriteDevice concept.
 426  *
 427  * @param offset The offset at which the data will be written.
 428  *
 429  * @param buffers One or more buffers containing the data to be written.
 430  * Although the buffers object may be copied as necessary, ownership of the
 431  * underlying memory blocks is retained by the caller, which must guarantee
 432  * that they remain valid until the handler is called.
 433  *
 434  * @param handler The handler to be called when the write operation completes.
 435  * Copies will be made of the handler as required. The function signature of
 436  * the handler must be:
 437  * @code void handler(
 438  *   // Result of operation.
 439  *   const boost::system::error_code& error,
 440  *
 441  *   // Number of bytes written from the buffers. If an error
 442  *   // occurred, this will be less than the sum of the buffer sizes.
 443  *   std::size_t bytes_transferred
 444  * ); @endcode
 445  * Regardless of whether the asynchronous operation completes immediately or
 446  * not, the handler will not be invoked from within this function. On
 447  * immediate completion, invocation of the handler will be performed in a
 448  * manner equivalent to using boost::asio::post().
 449  *
 450  * @par Example
 451  * To write a single data buffer use the @ref buffer function as follows:
 452  * @code
 453  * boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler);
 454  * @endcode
 455  * See the @ref buffer documentation for information on writing multiple
 456  * buffers in one go, and how to use it with arrays, boost::array or
 457  * std::vector.
 458  */
 459 template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence,
 460     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 461       std::size_t)) WriteHandler
 462         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 463           typename AsyncRandomAccessWriteDevice::executor_type)>
 464 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
 465     void (boost::system::error_code, std::size_t))
 466 async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset,
 467     const ConstBufferSequence& buffers,
 468     BOOST_ASIO_MOVE_ARG(WriteHandler) handler
 469       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 470         typename AsyncRandomAccessWriteDevice::executor_type));
 471
 472 /// Start an asynchronous operation to write a certain amount of data at the
 473 /// specified offset.
 474 /**
 475  * This function is used to asynchronously write a certain number of bytes of
 476  * data to a random access device at a specified offset. The function call
 477  * always returns immediately. The asynchronous operation will continue until
 478  * one of the following conditions is true:
 479  *
 480  * @li All of the data in the supplied buffers has been written. That is, the
 481  * bytes transferred is equal to the sum of the buffer sizes.
 482  *
 483  * @li The completion_condition function object returns 0.
 484  *
 485  * This operation is implemented in terms of zero or more calls to the device's
 486  * async_write_some_at function, and is known as a <em>composed operation</em>.
 487  * The program must ensure that the device performs no <em>overlapping</em>
 488  * write operations (such as async_write_at, the device's async_write_some_at
 489  * function, or any other composed operations that perform writes) until this
 490  * operation completes. Operations are overlapping if the regions defined by
 491  * their offsets, and the numbers of bytes to write, intersect.
 492  *
 493  * @param d The device to which the data is to be written. The type must support
 494  * the AsyncRandomAccessWriteDevice concept.
 495  *
 496  * @param offset The offset at which the data will be written.
 497  *
 498  * @param buffers One or more buffers containing the data to be written.
 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 completion_condition The function object to be called to determine
 504  * whether the write operation is complete. The signature of the function object
 505  * must be:
 506  * @code std::size_t completion_condition(
 507  *   // Result of latest async_write_some_at operation.
 508  *   const boost::system::error_code& error,
 509  *
 510  *   // Number of bytes transferred so far.
 511  *   std::size_t bytes_transferred
 512  * ); @endcode
 513  * A return value of 0 indicates that the write operation is complete. A
 514  * non-zero return value indicates the maximum number of bytes to be written on
 515  * the next call to the device's async_write_some_at function.
 516  *
 517  * @param handler The handler to be called when the write operation completes.
 518  * Copies will be made of the handler as required. The function signature of the
 519  * handler must be:
 520  * @code void handler(
 521  *   // Result of operation.
 522  *   const boost::system::error_code& error,
 523  *
 524  *   // Number of bytes written from the buffers. If an error
 525  *   // occurred, this will be less than the sum of the buffer sizes.
 526  *   std::size_t bytes_transferred
 527  * ); @endcode
 528  * Regardless of whether the asynchronous operation completes immediately or
 529  * not, the handler will not be invoked from within this function. On
 530  * immediate completion, invocation of the handler will be performed in a
 531  * manner equivalent to using boost::asio::post().
 532  *
 533  * @par Example
 534  * To write a single data buffer use the @ref buffer function as follows:
 535  * @code boost::asio::async_write_at(d, 42,
 536  *     boost::asio::buffer(data, size),
 537  *     boost::asio::transfer_at_least(32),
 538  *     handler); @endcode
 539  * See the @ref buffer documentation for information on writing multiple
 540  * buffers in one go, and how to use it with arrays, boost::array or
 541  * std::vector.
 542  */
 543 template <typename AsyncRandomAccessWriteDevice,
 544     typename ConstBufferSequence, typename CompletionCondition,
 545     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 546       std::size_t)) WriteHandler
 547         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 548           typename AsyncRandomAccessWriteDevice::executor_type)>
 549 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
 550     void (boost::system::error_code, std::size_t))
 551 async_write_at(AsyncRandomAccessWriteDevice& d,
 552     uint64_t offset, const ConstBufferSequence& buffers,
 553     CompletionCondition completion_condition,
 554     BOOST_ASIO_MOVE_ARG(WriteHandler) handler
 555       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 556         typename AsyncRandomAccessWriteDevice::executor_type));
 557
 558 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
 559 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 560
 561 /// Start an asynchronous operation to write all of the supplied data at the
 562 /// specified offset.
 563 /**
 564  * This function is used to asynchronously write a certain number of bytes of
 565  * data to a random access device at a specified offset. The function call
 566  * always returns immediately. The asynchronous operation will continue until
 567  * one of the following conditions is true:
 568  *
 569  * @li All of the data in the supplied basic_streambuf has been written.
 570  *
 571  * @li An error occurred.
 572  *
 573  * This operation is implemented in terms of zero or more calls to the device's
 574  * async_write_some_at function, and is known as a <em>composed operation</em>.
 575  * The program must ensure that the device performs no <em>overlapping</em>
 576  * write operations (such as async_write_at, the device's async_write_some_at
 577  * function, or any other composed operations that perform writes) until this
 578  * operation completes. Operations are overlapping if the regions defined by
 579  * their offsets, and the numbers of bytes to write, intersect.
 580  *
 581  * @param d The device to which the data is to be written. The type must support
 582  * the AsyncRandomAccessWriteDevice concept.
 583  *
 584  * @param offset The offset at which the data will be written.
 585  *
 586  * @param b A basic_streambuf object from which data will be written. Ownership
 587  * of the streambuf is retained by the caller, which must guarantee that it
 588  * remains valid until the handler is called.
 589  *
 590  * @param handler The handler to be called when the write operation completes.
 591  * Copies will be made of the handler as required. The function signature of the
 592  * handler must be:
 593  * @code void handler(
 594  *   // Result of operation.
 595  *   const boost::system::error_code& error,
 596  *
 597  *   // Number of bytes written from the buffers. If an error
 598  *   // occurred, this will be less than the sum of the buffer sizes.
 599  *   std::size_t bytes_transferred
 600  * ); @endcode
 601  * Regardless of whether the asynchronous operation completes immediately or
 602  * not, the handler will not be invoked from within this function. On
 603  * immediate completion, invocation of the handler will be performed in a
 604  * manner equivalent to using boost::asio::post().
 605  */
 606 template <typename AsyncRandomAccessWriteDevice, typename Allocator,
 607     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 608       std::size_t)) WriteHandler
 609         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 610           typename AsyncRandomAccessWriteDevice::executor_type)>
 611 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
 612     void (boost::system::error_code, std::size_t))
 613 async_write_at(AsyncRandomAccessWriteDevice& d,
 614     uint64_t offset, basic_streambuf<Allocator>& b,
 615     BOOST_ASIO_MOVE_ARG(WriteHandler) handler
 616       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 617         typename AsyncRandomAccessWriteDevice::executor_type));
 618
 619 /// Start an asynchronous operation to write a certain amount of data at the
 620 /// specified offset.
 621 /**
 622  * This function is used to asynchronously write a certain number of bytes of
 623  * data to a random access device at a specified offset. The function call
 624  * always returns immediately. The asynchronous operation will continue until
 625  * one of the following conditions is true:
 626  *
 627  * @li All of the data in the supplied basic_streambuf has been written.
 628  *
 629  * @li The completion_condition function object returns 0.
 630  *
 631  * This operation is implemented in terms of zero or more calls to the device's
 632  * async_write_some_at function, and is known as a <em>composed operation</em>.
 633  * The program must ensure that the device performs no <em>overlapping</em>
 634  * write operations (such as async_write_at, the device's async_write_some_at
 635  * function, or any other composed operations that perform writes) until this
 636  * operation completes. Operations are overlapping if the regions defined by
 637  * their offsets, and the numbers of bytes to write, intersect.
 638  *
 639  * @param d The device to which the data is to be written. The type must support
 640  * the AsyncRandomAccessWriteDevice concept.
 641  *
 642  * @param offset The offset at which the data will be written.
 643  *
 644  * @param b A basic_streambuf object from which data will be written. Ownership
 645  * of the streambuf is retained by the caller, which must guarantee that it
 646  * remains valid until the handler is called.
 647  *
 648  * @param completion_condition The function object to be called to determine
 649  * whether the write operation is complete. The signature of the function object
 650  * must be:
 651  * @code std::size_t completion_condition(
 652  *   // Result of latest async_write_some_at operation.
 653  *   const boost::system::error_code& error,
 654  *
 655  *   // Number of bytes transferred so far.
 656  *   std::size_t bytes_transferred
 657  * ); @endcode
 658  * A return value of 0 indicates that the write operation is complete. A
 659  * non-zero return value indicates the maximum number of bytes to be written on
 660  * the next call to the device's async_write_some_at function.
 661  *
 662  * @param handler The handler to be called when the write operation completes.
 663  * Copies will be made of the handler as required. The function signature of the
 664  * handler must be:
 665  * @code void handler(
 666  *   // Result of operation.
 667  *   const boost::system::error_code& error,
 668  *
 669  *   // Number of bytes written from the buffers. If an error
 670  *   // occurred, this will be less than the sum of the buffer sizes.
 671  *   std::size_t bytes_transferred
 672  * ); @endcode
 673  * Regardless of whether the asynchronous operation completes immediately or
 674  * not, the handler will not be invoked from within this function. On
 675  * immediate completion, invocation of the handler will be performed in a
 676  * manner equivalent to using boost::asio::post().
 677  */
 678 template <typename AsyncRandomAccessWriteDevice,
 679     typename Allocator, typename CompletionCondition,
 680     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 681       std::size_t)) WriteHandler
 682         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
 683           typename AsyncRandomAccessWriteDevice::executor_type)>
 684 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
 685     void (boost::system::error_code, std::size_t))
 686 async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset,
 687     basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
 688     BOOST_ASIO_MOVE_ARG(WriteHandler) handler
 689       BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
 690         typename AsyncRandomAccessWriteDevice::executor_type));
 691
 692 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 693 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
 694
 695 /*@}*/
 696
 697 } // namespace asio
 698 } // namespace boost
 699
 700 #include <boost/asio/detail/pop_options.hpp>
 701
 702 #include <boost/asio/impl/write_at.hpp>
 703
 704 #endif // BOOST_ASIO_WRITE_AT_HPP