boost/asio/write_at.hpp

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