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

source code of boost/libs/asio/include/boost/asio/read_at.hpp