1[/ 2 / Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:RandomAccessHandleService Random access handle service requirements] 9 10A random access handle service must meet the requirements for a [link 11boost_asio.reference.HandleService handle service], as well as the additional 12requirements listed below. 13 14In the table below, `X` denotes a random access handle service class, `a` 15denotes a value of type `X`, `b` denotes a value of type 16`X::implementation_type`, `ec` denotes a value of type `error_code`, `o` 17denotes an offset of type boost::uint64_t, `mb` denotes a value satisfying 18[link boost_asio.reference.MutableBufferSequence mutable buffer sequence] 19requirements, `rh` denotes a value meeting [link boost_asio.reference.ReadHandler 20`ReadHandler`] requirements, `cb` denotes a value satisfying [link 21boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and 22`wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`] 23requirements. 24 25[table RandomAccessHandleService requirements 26 [[expression] [return type] [assertion/note\npre/post-condition]] 27 [ 28 [`a.read_some_at(b, o, mb, ec);`] 29 [`size_t`] 30 [ 31 pre: `a.is_open(b)`.\n 32 \n 33 Reads one or more bytes of data from a handle `b` at offset `o`.\n 34 \n 35 The mutable buffer sequence `mb` specifies memory where the data should 36 be placed. The operation shall always fill a buffer in the sequence 37 completely before proceeding to the next.\n 38 \n 39 If successful, returns the number of bytes read. Otherwise returns `0`. 40 If the total size of all buffers in the sequence `mb` is `0`, the 41 function shall return `0` immediately. 42 ] 43 ] 44 [ 45 [`a.async_read_some_at(b, o, mb, rh);`] 46 [`void`] 47 [ 48 pre: `a.is_open(b)`.\n 49 \n 50 Initiates an asynchronous operation to read one or more bytes of data 51 from a handle `b` at offset `o`. The operation is performed via the 52 `io_service` object `a.get_io_service()` and behaves according to [link 53 boost_asio.reference.asynchronous_operations asynchronous operation] 54 requirements.\n 55 \n 56 The mutable buffer sequence `mb` specifies memory where the data should 57 be placed. The operation shall always fill a buffer in the sequence 58 completely before proceeding to the next.\n 59 \n 60 The implementation shall maintain one or more copies of `mb` until such 61 time as the read operation no longer requires access to the memory 62 specified by the buffers in the sequence. The program must ensure the 63 memory is valid until:\n 64 \n 65 [mdash] the last copy of `mb` is destroyed, or\n 66 \n 67 [mdash] the handler for the asynchronous operation is invoked,\n 68 \n 69 whichever comes first. If the total size of all buffers in the sequence 70 `mb` is `0`, the asynchronous read operation shall complete immediately 71 and pass `0` as the argument to the handler that specifies the number of 72 bytes read.\n 73 \n 74 If the operation completes successfully, the `ReadHandler` object 75 `rh` is invoked with the number of bytes transferred. Otherwise it is 76 invoked with `0`. 77 ] 78 ] 79 [ 80 [`a.write_some_at(b, o, cb, ec);`] 81 [`size_t`] 82 [ 83 pre: `a.is_open(b)`.\n 84 \n 85 Writes one or more bytes of data to a handle `b` at offset `o`.\n 86 \n 87 The constant buffer sequence `cb` specifies memory where the data to be 88 written is located. The operation shall always write a buffer in the 89 sequence completely before proceeding to the next.\n 90 \n 91 If successful, returns the number of bytes written. Otherwise returns `0`. 92 If the total size of all buffers in the sequence `cb` is `0`, the 93 function shall return `0` immediately. 94 ] 95 ] 96 [ 97 [`a.async_write_some_at(b, o, cb, wh);`] 98 [`void`] 99 [ 100 pre: `a.is_open(b)`.\n 101 \n 102 Initiates an asynchronous operation to write one or more bytes of data to 103 a handle `b` at offset `o`. The operation is performed via the 104 `io_service` object `a.get_io_service()` and behaves according to [link 105 boost_asio.reference.asynchronous_operations asynchronous operation] 106 requirements.\n 107 \n 108 The constant buffer sequence `cb` specifies memory where the data to be 109 written is located. The operation shall always write a buffer in the 110 sequence completely before proceeding to the next.\n 111 \n 112 The implementation shall maintain one or more copies of `cb` until such 113 time as the write operation no longer requires access to the memory 114 specified by the buffers in the sequence. The program must ensure the 115 memory is valid until:\n 116 \n 117 [mdash] the last copy of `cb` is destroyed, or\n 118 \n 119 [mdash] the handler for the asynchronous operation is invoked,\n 120 \n 121 whichever comes first. If the total size of all buffers in the sequence 122 `cb` is `0`, the asynchronous operation shall complete immediately and 123 pass `0` as the argument to the handler that specifies the number of 124 bytes read.\n 125 \n 126 If the operation completes successfully, the `WriteHandler` object `wh` 127 is invoked with the number of bytes transferred. Otherwise it is invoked 128 with `0`. 129 ] 130 ] 131] 132 133[endsect] 134