annotate DEPENDENCIES/generic/include/boost/asio/write_at.hpp @ 125:34e428693f5d vext

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