boost_1_45_0/libs/asio/doc/requirements/AsyncRandomAccessReadDevice.qbk

[/
 / Copyright (c) 2003-2010 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:AsyncRandomAccessReadDevice Buffer-oriented asynchronous random-access
read device requirements]

In the table below, `a` denotes an asynchronous random access read device
object, `o` denotes an offset of type `boost::uint64_t`, `mb` denotes an object
satisfying [link boost_asio.reference.MutableBufferSequence mutable buffer sequence]
requirements, and `h` denotes an object satisfying [link
boost_asio.reference.ReadHandler read handler] requirements.

[table Buffer-oriented asynchronous random-access read device requirements
  [[operation] [type] [semantics, pre/post-conditions]]
  [
    [`a.get_io_service();`]
    [`io_service&`]
    [Returns the `io_service` object through which the `async_read_some_at`
    handler `h` will be invoked.]
  ]
  [
    [`a.async_read_some_at(o, mb, h);`]
    [`void`]
    [
      Initiates an asynchronous operation to read one or more bytes of data
      from the device `a` at the offset `o`. The operation is performed via the
      `io_service` object `a.get_io_service()` and behaves according to [link
      boost_asio.reference.asynchronous_operations asynchronous operation]
      requirements.\n
      \n
      The mutable buffer sequence `mb` specifies memory where the data should
      be placed. The `async_read_some_at` operation shall always fill a buffer
      in the sequence completely before proceeding to the next.\n
      \n
      The implementation shall maintain one or more copies of `mb` until such
      time as the read operation no longer requires access to the memory
      specified by the buffers in the sequence. The program must ensure the
      memory is valid until:\n
      \n
      [mdash] the last copy of `mb` is destroyed, or\n
      \n
      [mdash] the handler for the asynchronous read operation is invoked,\n
      \n
      whichever comes first.\n
      \n
      If the total size of all buffers in the sequence `mb` is `0`, the
      asynchronous read operation shall complete immediately and pass `0` as
      the argument to the handler that specifies the number of bytes read.
    ]
  ]
]

[endsect]