5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_READ_AT_HPP
12 #define BOOST_ASIO_READ_AT_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
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>
25 #include <boost/asio/detail/push_options.hpp>
31 * @defgroup read_at boost::asio::read_at
33 * @brief Attempt to read a certain amount of data at the specified offset
38 /// Attempt to read a certain amount of data at the specified offset before
41 * This function is used to read a certain number of bytes of data from a
42 * random access device at the specified offset. The call will block until one
43 * of the following conditions is true:
45 * @li The supplied buffers are full. That is, the bytes transferred is equal to
46 * the sum of the buffer sizes.
48 * @li An error occurred.
50 * This operation is implemented in terms of zero or more calls to the device's
51 * read_some_at function.
53 * @param d The device from which the data is to be read. The type must support
54 * the SyncRandomAccessReadDevice concept.
56 * @param offset The offset at which the data will be read.
58 * @param buffers One or more buffers into which the data will be read. The sum
59 * of the buffer sizes indicates the maximum number of bytes to read from the
62 * @returns The number of bytes transferred.
64 * @throws boost::system::system_error Thrown on failure.
67 * To read into a single data buffer use the @ref buffer function as follows:
68 * @code boost::asio::read_at(d, 42, boost::asio::buffer(data, size)); @endcode
69 * See the @ref buffer documentation for information on reading into multiple
70 * buffers in one go, and how to use it with arrays, boost::array or
73 * @note This overload is equivalent to calling:
74 * @code boost::asio::read_at(
76 * boost::asio::transfer_all()); @endcode
78 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
79 std::size_t read_at(SyncRandomAccessReadDevice& d,
80 uint64_t offset, const MutableBufferSequence& buffers);
82 /// Attempt to read a certain amount of data at the specified offset before
85 * This function is used to read a certain number of bytes of data from a
86 * random access device at the specified offset. The call will block until one
87 * of the following conditions is true:
89 * @li The supplied buffers are full. That is, the bytes transferred is equal to
90 * the sum of the buffer sizes.
92 * @li An error occurred.
94 * This operation is implemented in terms of zero or more calls to the device's
95 * read_some_at function.
97 * @param d The device from which the data is to be read. The type must support
98 * the SyncRandomAccessReadDevice concept.
100 * @param offset The offset at which the data will be read.
102 * @param buffers One or more buffers into which the data will be read. The sum
103 * of the buffer sizes indicates the maximum number of bytes to read from the
106 * @param ec Set to indicate what error occurred, if any.
108 * @returns The number of bytes transferred.
111 * To read into a single data buffer use the @ref buffer function as follows:
112 * @code boost::asio::read_at(d, 42,
113 * boost::asio::buffer(data, size), ec); @endcode
114 * See the @ref buffer documentation for information on reading into multiple
115 * buffers in one go, and how to use it with arrays, boost::array or
118 * @note This overload is equivalent to calling:
119 * @code boost::asio::read_at(
121 * boost::asio::transfer_all(), ec); @endcode
123 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence>
124 std::size_t read_at(SyncRandomAccessReadDevice& d,
125 uint64_t offset, const MutableBufferSequence& buffers,
126 boost::system::error_code& ec);
128 /// Attempt to read a certain amount of data at the specified offset before
131 * This function is used to read a certain number of bytes of data from a
132 * random access device at the specified offset. The call will block until one
133 * of the following conditions is true:
135 * @li The supplied buffers are full. That is, the bytes transferred is equal to
136 * the sum of the buffer sizes.
138 * @li The completion_condition function object returns 0.
140 * This operation is implemented in terms of zero or more calls to the device's
141 * read_some_at function.
143 * @param d The device from which the data is to be read. The type must support
144 * the SyncRandomAccessReadDevice concept.
146 * @param offset The offset at which the data will be read.
148 * @param buffers One or more buffers into which the data will be read. The sum
149 * of the buffer sizes indicates the maximum number of bytes to read from the
152 * @param completion_condition The function object to be called to determine
153 * whether the read operation is complete. The signature of the function object
155 * @code std::size_t completion_condition(
156 * // Result of latest read_some_at operation.
157 * const boost::system::error_code& error,
159 * // Number of bytes transferred so far.
160 * std::size_t bytes_transferred
162 * A return value of 0 indicates that the read operation is complete. A non-zero
163 * return value indicates the maximum number of bytes to be read on the next
164 * call to the device's read_some_at function.
166 * @returns The number of bytes transferred.
168 * @throws boost::system::system_error Thrown on failure.
171 * To read into a single data buffer use the @ref buffer function as follows:
172 * @code boost::asio::read_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 reading into multiple
175 * buffers in one go, and how to use it with arrays, boost::array or
178 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
179 typename CompletionCondition>
180 std::size_t read_at(SyncRandomAccessReadDevice& d,
181 uint64_t offset, const MutableBufferSequence& buffers,
182 CompletionCondition completion_condition);
184 /// Attempt to read a certain amount of data at the specified offset before
187 * This function is used to read a certain number of bytes of data from a
188 * random access device at the specified offset. The call will block until one
189 * of the following conditions is true:
191 * @li The supplied buffers are full. That is, the bytes transferred is equal to
192 * the sum of the buffer sizes.
194 * @li The completion_condition function object returns 0.
196 * This operation is implemented in terms of zero or more calls to the device's
197 * read_some_at function.
199 * @param d The device from which the data is to be read. The type must support
200 * the SyncRandomAccessReadDevice concept.
202 * @param offset The offset at which the data will be read.
204 * @param buffers One or more buffers into which the data will be read. The sum
205 * of the buffer sizes indicates the maximum number of bytes to read from the
208 * @param completion_condition The function object to be called to determine
209 * whether the read operation is complete. The signature of the function object
211 * @code std::size_t completion_condition(
212 * // Result of latest read_some_at operation.
213 * const boost::system::error_code& error,
215 * // Number of bytes transferred so far.
216 * std::size_t bytes_transferred
218 * A return value of 0 indicates that the read operation is complete. A non-zero
219 * return value indicates the maximum number of bytes to be read on the next
220 * call to the device's read_some_at function.
222 * @param ec Set to indicate what error occurred, if any.
224 * @returns The number of bytes read. If an error occurs, returns the total
225 * number of bytes successfully transferred prior to the error.
227 template <typename SyncRandomAccessReadDevice, typename MutableBufferSequence,
228 typename CompletionCondition>
229 std::size_t read_at(SyncRandomAccessReadDevice& d,
230 uint64_t offset, const MutableBufferSequence& buffers,
231 CompletionCondition completion_condition, boost::system::error_code& ec);
233 #if !defined(BOOST_ASIO_NO_IOSTREAM)
235 /// Attempt to read a certain amount of data at the specified offset before
238 * This function is used to read a certain number of bytes of data from a
239 * random access device at the specified offset. The call will block until one
240 * of the following conditions is true:
242 * @li An error occurred.
244 * This operation is implemented in terms of zero or more calls to the device's
245 * read_some_at function.
247 * @param d The device from which the data is to be read. The type must support
248 * the SyncRandomAccessReadDevice concept.
250 * @param offset The offset at which the data will be read.
252 * @param b The basic_streambuf object into which the data will be read.
254 * @returns The number of bytes transferred.
256 * @throws boost::system::system_error Thrown on failure.
258 * @note This overload is equivalent to calling:
259 * @code boost::asio::read_at(
261 * boost::asio::transfer_all()); @endcode
263 template <typename SyncRandomAccessReadDevice, typename Allocator>
264 std::size_t read_at(SyncRandomAccessReadDevice& d,
265 uint64_t offset, basic_streambuf<Allocator>& b);
267 /// Attempt to read a certain amount of data at the specified offset before
270 * This function is used to read a certain number of bytes of data from a
271 * random access device at the specified offset. The call will block until one
272 * of the following conditions is true:
274 * @li An error occurred.
276 * This operation is implemented in terms of zero or more calls to the device's
277 * read_some_at function.
279 * @param d The device from which the data is to be read. The type must support
280 * the SyncRandomAccessReadDevice concept.
282 * @param offset The offset at which the data will be read.
284 * @param b The basic_streambuf object into which the data will be read.
286 * @param ec Set to indicate what error occurred, if any.
288 * @returns The number of bytes transferred.
290 * @note This overload is equivalent to calling:
291 * @code boost::asio::read_at(
293 * boost::asio::transfer_all(), ec); @endcode
295 template <typename SyncRandomAccessReadDevice, typename Allocator>
296 std::size_t read_at(SyncRandomAccessReadDevice& d,
297 uint64_t offset, basic_streambuf<Allocator>& b,
298 boost::system::error_code& ec);
300 /// Attempt to read a certain amount of data at the specified offset before
303 * This function is used to read a certain number of bytes of data from a
304 * random access device at the specified offset. The call will block until one
305 * of the following conditions is true:
307 * @li The completion_condition function object returns 0.
309 * This operation is implemented in terms of zero or more calls to the device's
310 * read_some_at function.
312 * @param d The device from which the data is to be read. The type must support
313 * the SyncRandomAccessReadDevice concept.
315 * @param offset The offset at which the data will be read.
317 * @param b The basic_streambuf object into which the data will be read.
319 * @param completion_condition The function object to be called to determine
320 * whether the read operation is complete. The signature of the function object
322 * @code std::size_t completion_condition(
323 * // Result of latest read_some_at operation.
324 * const boost::system::error_code& error,
326 * // Number of bytes transferred so far.
327 * std::size_t bytes_transferred
329 * A return value of 0 indicates that the read operation is complete. A non-zero
330 * return value indicates the maximum number of bytes to be read on the next
331 * call to the device's read_some_at function.
333 * @returns The number of bytes transferred.
335 * @throws boost::system::system_error Thrown on failure.
337 template <typename SyncRandomAccessReadDevice, typename Allocator,
338 typename CompletionCondition>
339 std::size_t read_at(SyncRandomAccessReadDevice& d,
340 uint64_t offset, basic_streambuf<Allocator>& b,
341 CompletionCondition completion_condition);
343 /// Attempt to read a certain amount of data at the specified offset before
346 * This function is used to read a certain number of bytes of data from a
347 * random access device at the specified offset. The call will block until one
348 * of the following conditions is true:
350 * @li The completion_condition function object returns 0.
352 * This operation is implemented in terms of zero or more calls to the device's
353 * read_some_at function.
355 * @param d The device from which the data is to be read. The type must support
356 * the SyncRandomAccessReadDevice concept.
358 * @param offset The offset at which the data will be read.
360 * @param b The basic_streambuf object into which the data will be read.
362 * @param completion_condition The function object to be called to determine
363 * whether the read operation is complete. The signature of the function object
365 * @code std::size_t completion_condition(
366 * // Result of latest read_some_at operation.
367 * const boost::system::error_code& error,
369 * // Number of bytes transferred so far.
370 * std::size_t bytes_transferred
372 * A return value of 0 indicates that the read operation is complete. A non-zero
373 * return value indicates the maximum number of bytes to be read on the next
374 * call to the device's read_some_at function.
376 * @param ec Set to indicate what error occurred, if any.
378 * @returns The number of bytes read. If an error occurs, returns the total
379 * number of bytes successfully transferred prior to the error.
381 template <typename SyncRandomAccessReadDevice, typename Allocator,
382 typename CompletionCondition>
383 std::size_t read_at(SyncRandomAccessReadDevice& d,
384 uint64_t offset, basic_streambuf<Allocator>& b,
385 CompletionCondition completion_condition, boost::system::error_code& ec);
387 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
391 * @defgroup async_read_at boost::asio::async_read_at
393 * @brief Start an asynchronous operation to read a certain amount of data at
394 * the specified offset.
398 /// Start an asynchronous operation to read a certain amount of data at the
399 /// specified offset.
401 * This function is used to asynchronously read a certain number of bytes of
402 * data from a random access device at the specified offset. The function call
403 * always returns immediately. The asynchronous operation will continue until
404 * one of the following conditions is true:
406 * @li The supplied buffers are full. That is, the bytes transferred is equal to
407 * the sum of the buffer sizes.
409 * @li An error occurred.
411 * This operation is implemented in terms of zero or more calls to the device's
412 * async_read_some_at function.
414 * @param d The device from which the data is to be read. The type must support
415 * the AsyncRandomAccessReadDevice concept.
417 * @param offset The offset at which the data will be read.
419 * @param buffers One or more buffers into which the data will be read. The sum
420 * of the buffer sizes indicates the maximum number of bytes to read from the
421 * device. Although the buffers object may be copied as necessary, ownership of
422 * the underlying memory blocks is retained by the caller, which must guarantee
423 * that they remain valid until the handler is called.
425 * @param handler The handler to be called when the read operation completes.
426 * Copies will be made of the handler as required. The function signature of the
428 * @code void handler(
429 * // Result of operation.
430 * const boost::system::error_code& error,
432 * // Number of bytes copied into the buffers. If an error
433 * // occurred, this will be the number of bytes successfully
434 * // transferred prior to the error.
435 * std::size_t bytes_transferred
437 * Regardless of whether the asynchronous operation completes immediately or
438 * not, the handler will not be invoked from within this function. Invocation of
439 * the handler will be performed in a manner equivalent to using
440 * boost::asio::io_service::post().
443 * To read into a single data buffer use the @ref buffer function as follows:
445 * boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);
447 * See the @ref buffer documentation for information on reading into multiple
448 * buffers in one go, and how to use it with arrays, boost::array or
451 * @note This overload is equivalent to calling:
452 * @code boost::asio::async_read_at(
454 * boost::asio::transfer_all(),
457 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
458 typename ReadHandler>
459 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
460 void (boost::system::error_code, std::size_t))
461 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
462 const MutableBufferSequence& buffers,
463 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
465 /// Start an asynchronous operation to read a certain amount of data at the
466 /// specified offset.
468 * This function is used to asynchronously read a certain number of bytes of
469 * data from a random access device at the specified offset. The function call
470 * always returns immediately. The asynchronous operation will continue until
471 * one of the following conditions is true:
473 * @li The supplied buffers are full. That is, the bytes transferred is equal to
474 * the sum of the buffer sizes.
476 * @li The completion_condition function object returns 0.
478 * @param d The device from which the data is to be read. The type must support
479 * the AsyncRandomAccessReadDevice concept.
481 * @param offset The offset at which the data will be read.
483 * @param buffers One or more buffers into which the data will be read. The sum
484 * of the buffer sizes indicates the maximum number of bytes to read from the
485 * device. Although the buffers object may be copied as necessary, ownership of
486 * the underlying memory blocks is retained by the caller, which must guarantee
487 * that they remain valid until the handler is called.
489 * @param completion_condition The function object to be called to determine
490 * whether the read operation is complete. The signature of the function object
492 * @code std::size_t completion_condition(
493 * // Result of latest async_read_some_at operation.
494 * const boost::system::error_code& error,
496 * // Number of bytes transferred so far.
497 * std::size_t bytes_transferred
499 * A return value of 0 indicates that the read operation is complete. A non-zero
500 * return value indicates the maximum number of bytes to be read on the next
501 * call to the device's async_read_some_at function.
503 * @param handler The handler to be called when the read operation completes.
504 * Copies will be made of the handler as required. The function signature of the
506 * @code void handler(
507 * // Result of operation.
508 * const boost::system::error_code& error,
510 * // Number of bytes copied into the buffers. If an error
511 * // occurred, this will be the number of bytes successfully
512 * // transferred prior to the error.
513 * std::size_t bytes_transferred
515 * Regardless of whether the asynchronous operation completes immediately or
516 * not, the handler will not be invoked from within this function. Invocation of
517 * the handler will be performed in a manner equivalent to using
518 * boost::asio::io_service::post().
521 * To read into a single data buffer use the @ref buffer function as follows:
522 * @code boost::asio::async_read_at(d, 42,
523 * boost::asio::buffer(data, size),
524 * boost::asio::transfer_at_least(32),
526 * See the @ref buffer documentation for information on reading into multiple
527 * buffers in one go, and how to use it with arrays, boost::array or
530 template <typename AsyncRandomAccessReadDevice, typename MutableBufferSequence,
531 typename CompletionCondition, typename ReadHandler>
532 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
533 void (boost::system::error_code, std::size_t))
534 async_read_at(AsyncRandomAccessReadDevice& d,
535 uint64_t offset, const MutableBufferSequence& buffers,
536 CompletionCondition completion_condition,
537 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
539 #if !defined(BOOST_ASIO_NO_IOSTREAM)
541 /// Start an asynchronous operation to read a certain amount of data at the
542 /// specified offset.
544 * This function is used to asynchronously read a certain number of bytes of
545 * data from a random access device at the specified offset. The function call
546 * always returns immediately. The asynchronous operation will continue until
547 * one of the following conditions is true:
549 * @li An error occurred.
551 * This operation is implemented in terms of zero or more calls to the device's
552 * async_read_some_at function.
554 * @param d The device from which the data is to be read. The type must support
555 * the AsyncRandomAccessReadDevice concept.
557 * @param offset The offset at which the data will be read.
559 * @param b A basic_streambuf object into which the data will be read. Ownership
560 * of the streambuf is retained by the caller, which must guarantee that it
561 * remains valid until the handler is called.
563 * @param handler The handler to be called when the read operation completes.
564 * Copies will be made of the handler as required. The function signature of the
566 * @code void handler(
567 * // Result of operation.
568 * const boost::system::error_code& error,
570 * // Number of bytes copied into the buffers. If an error
571 * // occurred, this will be the number of bytes successfully
572 * // transferred prior to the error.
573 * std::size_t bytes_transferred
575 * Regardless of whether the asynchronous operation completes immediately or
576 * not, the handler will not be invoked from within this function. Invocation of
577 * the handler will be performed in a manner equivalent to using
578 * boost::asio::io_service::post().
580 * @note This overload is equivalent to calling:
581 * @code boost::asio::async_read_at(
583 * boost::asio::transfer_all(),
586 template <typename AsyncRandomAccessReadDevice, typename Allocator,
587 typename ReadHandler>
588 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
589 void (boost::system::error_code, std::size_t))
590 async_read_at(AsyncRandomAccessReadDevice& d, uint64_t offset,
591 basic_streambuf<Allocator>& b, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
593 /// Start an asynchronous operation to read a certain amount of data at the
594 /// specified offset.
596 * This function is used to asynchronously read a certain number of bytes of
597 * data from a random access device at the specified offset. The function call
598 * always returns immediately. The asynchronous operation will continue until
599 * one of the following conditions is true:
601 * @li The completion_condition function object returns 0.
603 * This operation is implemented in terms of zero or more calls to the device's
604 * async_read_some_at function.
606 * @param d The device from which the data is to be read. The type must support
607 * the AsyncRandomAccessReadDevice concept.
609 * @param offset The offset at which the data will be read.
611 * @param b A basic_streambuf object into which the data will be read. Ownership
612 * of the streambuf is retained by the caller, which must guarantee that it
613 * remains valid until the handler is called.
615 * @param completion_condition The function object to be called to determine
616 * whether the read operation is complete. The signature of the function object
618 * @code std::size_t completion_condition(
619 * // Result of latest async_read_some_at operation.
620 * const boost::system::error_code& error,
622 * // Number of bytes transferred so far.
623 * std::size_t bytes_transferred
625 * A return value of 0 indicates that the read operation is complete. A non-zero
626 * return value indicates the maximum number of bytes to be read on the next
627 * call to the device's async_read_some_at function.
629 * @param handler The handler to be called when the read operation completes.
630 * Copies will be made of the handler as required. The function signature of the
632 * @code void handler(
633 * // Result of operation.
634 * const boost::system::error_code& error,
636 * // Number of bytes copied into the buffers. If an error
637 * // occurred, this will be the number of bytes successfully
638 * // transferred prior to the error.
639 * std::size_t bytes_transferred
641 * Regardless of whether the asynchronous operation completes immediately or
642 * not, the handler will not be invoked from within this function. Invocation of
643 * the handler will be performed in a manner equivalent to using
644 * boost::asio::io_service::post().
646 template <typename AsyncRandomAccessReadDevice, typename Allocator,
647 typename CompletionCondition, typename ReadHandler>
648 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
649 void (boost::system::error_code, std::size_t))
650 async_read_at(AsyncRandomAccessReadDevice& d,
651 uint64_t offset, basic_streambuf<Allocator>& b,
652 CompletionCondition completion_condition,
653 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
655 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
662 #include <boost/asio/detail/pop_options.hpp>
664 #include <boost/asio/impl/read_at.hpp>
666 #endif // BOOST_ASIO_READ_AT_HPP