2
// basic_random_access_handle.hpp
3
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
// Copyright (c) 2003-2008 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_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
12
#define BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18
#include <boost/asio/detail/push_options.hpp>
20
#include <boost/asio/detail/push_options.hpp>
22
#include <boost/config.hpp>
23
#include <boost/asio/detail/pop_options.hpp>
25
#include <boost/asio/error.hpp>
26
#include <boost/asio/windows/basic_handle.hpp>
27
#include <boost/asio/windows/random_access_handle_service.hpp>
28
#include <boost/asio/detail/throw_error.hpp>
30
#if defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE) \
31
|| defined(GENERATING_DOCUMENTATION)
37
/// Provides random-access handle functionality.
39
* The windows::basic_random_access_handle class template provides asynchronous
40
* and blocking random-access handle functionality.
43
* @e Distinct @e objects: Safe.@n
44
* @e Shared @e objects: Unsafe.
46
template <typename RandomAccessHandleService = random_access_handle_service>
47
class basic_random_access_handle
48
: public basic_handle<RandomAccessHandleService>
51
/// The native representation of a handle.
52
typedef typename RandomAccessHandleService::native_type native_type;
54
/// Construct a basic_random_access_handle without opening it.
56
* This constructor creates a random-access handle without opening it. The
57
* handle needs to be opened before data can be written to or or read from it.
59
* @param io_service The io_service object that the random-access handle will
60
* use to dispatch handlers for any asynchronous operations performed on the
63
explicit basic_random_access_handle(boost::asio::io_service& io_service)
64
: basic_handle<RandomAccessHandleService>(io_service)
68
/// Construct a basic_random_access_handle on an existing native handle.
70
* This constructor creates a random-access handle object to hold an existing
73
* @param io_service The io_service object that the random-access handle will
74
* use to dispatch handlers for any asynchronous operations performed on the
77
* @param native_handle The new underlying handle implementation.
79
* @throws boost::system::system_error Thrown on failure.
81
basic_random_access_handle(boost::asio::io_service& io_service,
82
const native_type& native_handle)
83
: basic_handle<RandomAccessHandleService>(io_service, native_handle)
87
/// Write some data to the handle at the specified offset.
89
* This function is used to write data to the random-access handle. The
90
* function call will block until one or more bytes of the data has been
91
* written successfully, or until an error occurs.
93
* @param offset The offset at which the data will be written.
95
* @param buffers One or more data buffers to be written to the handle.
97
* @returns The number of bytes written.
99
* @throws boost::system::system_error Thrown on failure. An error code of
100
* boost::asio::error::eof indicates that the connection was closed by the
103
* @note The write_some_at operation may not write all of the data. Consider
104
* using the @ref write_at function if you need to ensure that all data is
105
* written before the blocking operation completes.
108
* To write a single data buffer use the @ref buffer function as follows:
110
* handle.write_some_at(42, boost::asio::buffer(data, size));
112
* See the @ref buffer documentation for information on writing multiple
113
* buffers in one go, and how to use it with arrays, boost::array or
116
template <typename ConstBufferSequence>
117
std::size_t write_some_at(boost::uint64_t offset,
118
const ConstBufferSequence& buffers)
120
boost::system::error_code ec;
121
std::size_t s = this->service.write_some_at(
122
this->implementation, offset, buffers, ec);
123
boost::asio::detail::throw_error(ec);
127
/// Write some data to the handle at the specified offset.
129
* This function is used to write data to the random-access handle. The
130
* function call will block until one or more bytes of the data has been
131
* written successfully, or until an error occurs.
133
* @param offset The offset at which the data will be written.
135
* @param buffers One or more data buffers to be written to the handle.
137
* @param ec Set to indicate what error occurred, if any.
139
* @returns The number of bytes written. Returns 0 if an error occurred.
141
* @note The write_some operation may not transmit all of the data to the
142
* peer. Consider using the @ref write_at function if you need to ensure that
143
* all data is written before the blocking operation completes.
145
template <typename ConstBufferSequence>
146
std::size_t write_some_at(boost::uint64_t offset,
147
const ConstBufferSequence& buffers, boost::system::error_code& ec)
149
return this->service.write_some_at(
150
this->implementation, offset, buffers, ec);
153
/// Start an asynchronous write at the specified offset.
155
* This function is used to asynchronously write data to the random-access
156
* handle. The function call always returns immediately.
158
* @param offset The offset at which the data will be written.
160
* @param buffers One or more data buffers to be written to the handle.
161
* Although the buffers object may be copied as necessary, ownership of the
162
* underlying memory blocks is retained by the caller, which must guarantee
163
* that they remain valid until the handler is called.
165
* @param handler The handler to be called when the write operation completes.
166
* Copies will be made of the handler as required. The function signature of
167
* the handler must be:
168
* @code void handler(
169
* const boost::system::error_code& error, // Result of operation.
170
* std::size_t bytes_transferred // Number of bytes written.
172
* Regardless of whether the asynchronous operation completes immediately or
173
* not, the handler will not be invoked from within this function. Invocation
174
* of the handler will be performed in a manner equivalent to using
175
* boost::asio::io_service::post().
177
* @note The write operation may not transmit all of the data to the peer.
178
* Consider using the @ref async_write_at function if you need to ensure that
179
* all data is written before the asynchronous operation completes.
182
* To write a single data buffer use the @ref buffer function as follows:
184
* handle.async_write_some_at(42, boost::asio::buffer(data, size), handler);
186
* See the @ref buffer documentation for information on writing multiple
187
* buffers in one go, and how to use it with arrays, boost::array or
190
template <typename ConstBufferSequence, typename WriteHandler>
191
void async_write_some_at(boost::uint64_t offset,
192
const ConstBufferSequence& buffers, WriteHandler handler)
194
this->service.async_write_some_at(
195
this->implementation, offset, buffers, handler);
198
/// Read some data from the handle at the specified offset.
200
* This function is used to read data from the random-access handle. The
201
* function call will block until one or more bytes of data has been read
202
* successfully, or until an error occurs.
204
* @param offset The offset at which the data will be read.
206
* @param buffers One or more buffers into which the data will be read.
208
* @returns The number of bytes read.
210
* @throws boost::system::system_error Thrown on failure. An error code of
211
* boost::asio::error::eof indicates that the connection was closed by the
214
* @note The read_some operation may not read all of the requested number of
215
* bytes. Consider using the @ref read_at function if you need to ensure that
216
* the requested amount of data is read before the blocking operation
220
* To read into a single data buffer use the @ref buffer function as follows:
222
* handle.read_some_at(42, boost::asio::buffer(data, size));
224
* See the @ref buffer documentation for information on reading into multiple
225
* buffers in one go, and how to use it with arrays, boost::array or
228
template <typename MutableBufferSequence>
229
std::size_t read_some_at(boost::uint64_t offset,
230
const MutableBufferSequence& buffers)
232
boost::system::error_code ec;
233
std::size_t s = this->service.read_some_at(
234
this->implementation, offset, buffers, ec);
235
boost::asio::detail::throw_error(ec);
239
/// Read some data from the handle at the specified offset.
241
* This function is used to read data from the random-access handle. The
242
* function call will block until one or more bytes of data has been read
243
* successfully, or until an error occurs.
245
* @param offset The offset at which the data will be read.
247
* @param buffers One or more buffers into which the data will be read.
249
* @param ec Set to indicate what error occurred, if any.
251
* @returns The number of bytes read. Returns 0 if an error occurred.
253
* @note The read_some operation may not read all of the requested number of
254
* bytes. Consider using the @ref read_at function if you need to ensure that
255
* the requested amount of data is read before the blocking operation
258
template <typename MutableBufferSequence>
259
std::size_t read_some_at(boost::uint64_t offset,
260
const MutableBufferSequence& buffers, boost::system::error_code& ec)
262
return this->service.read_some_at(
263
this->implementation, offset, buffers, ec);
266
/// Start an asynchronous read at the specified offset.
268
* This function is used to asynchronously read data from the random-access
269
* handle. The function call always returns immediately.
271
* @param offset The offset at which the data will be read.
273
* @param buffers One or more buffers into which the data will be read.
274
* Although the buffers object may be copied as necessary, ownership of the
275
* underlying memory blocks is retained by the caller, which must guarantee
276
* that they remain valid until the handler is called.
278
* @param handler The handler to be called when the read operation completes.
279
* Copies will be made of the handler as required. The function signature of
280
* the handler must be:
281
* @code void handler(
282
* const boost::system::error_code& error, // Result of operation.
283
* std::size_t bytes_transferred // Number of bytes read.
285
* Regardless of whether the asynchronous operation completes immediately or
286
* not, the handler will not be invoked from within this function. Invocation
287
* of the handler will be performed in a manner equivalent to using
288
* boost::asio::io_service::post().
290
* @note The read operation may not read all of the requested number of bytes.
291
* Consider using the @ref async_read_at function if you need to ensure that
292
* the requested amount of data is read before the asynchronous operation
296
* To read into a single data buffer use the @ref buffer function as follows:
298
* handle.async_read_some_at(42, boost::asio::buffer(data, size), handler);
300
* See the @ref buffer documentation for information on reading into multiple
301
* buffers in one go, and how to use it with arrays, boost::array or
304
template <typename MutableBufferSequence, typename ReadHandler>
305
void async_read_some_at(boost::uint64_t offset,
306
const MutableBufferSequence& buffers, ReadHandler handler)
308
this->service.async_read_some_at(
309
this->implementation, offset, buffers, handler);
313
} // namespace windows
317
#endif // defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE)
318
// || defined(GENERATING_DOCUMENTATION)
320
#include <boost/asio/detail/pop_options.hpp>
322
#endif // BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
2
// basic_random_access_handle.hpp
3
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
// Copyright (c) 2003-2008 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_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
12
#define BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18
#include <boost/asio/detail/push_options.hpp>
20
#include <boost/asio/detail/push_options.hpp>
22
#include <boost/config.hpp>
23
#include <boost/asio/detail/pop_options.hpp>
25
#include <boost/asio/error.hpp>
26
#include <boost/asio/windows/basic_handle.hpp>
27
#include <boost/asio/windows/random_access_handle_service.hpp>
28
#include <boost/asio/detail/throw_error.hpp>
30
#if defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE) \
31
|| defined(GENERATING_DOCUMENTATION)
37
/// Provides random-access handle functionality.
39
* The windows::basic_random_access_handle class template provides asynchronous
40
* and blocking random-access handle functionality.
43
* @e Distinct @e objects: Safe.@n
44
* @e Shared @e objects: Unsafe.
46
template <typename RandomAccessHandleService = random_access_handle_service>
47
class basic_random_access_handle
48
: public basic_handle<RandomAccessHandleService>
51
/// The native representation of a handle.
52
typedef typename RandomAccessHandleService::native_type native_type;
54
/// Construct a basic_random_access_handle without opening it.
56
* This constructor creates a random-access handle without opening it. The
57
* handle needs to be opened before data can be written to or or read from it.
59
* @param io_service The io_service object that the random-access handle will
60
* use to dispatch handlers for any asynchronous operations performed on the
63
explicit basic_random_access_handle(boost::asio::io_service& io_service)
64
: basic_handle<RandomAccessHandleService>(io_service)
68
/// Construct a basic_random_access_handle on an existing native handle.
70
* This constructor creates a random-access handle object to hold an existing
73
* @param io_service The io_service object that the random-access handle will
74
* use to dispatch handlers for any asynchronous operations performed on the
77
* @param native_handle The new underlying handle implementation.
79
* @throws boost::system::system_error Thrown on failure.
81
basic_random_access_handle(boost::asio::io_service& io_service,
82
const native_type& native_handle)
83
: basic_handle<RandomAccessHandleService>(io_service, native_handle)
87
/// Write some data to the handle at the specified offset.
89
* This function is used to write data to the random-access handle. The
90
* function call will block until one or more bytes of the data has been
91
* written successfully, or until an error occurs.
93
* @param offset The offset at which the data will be written.
95
* @param buffers One or more data buffers to be written to the handle.
97
* @returns The number of bytes written.
99
* @throws boost::system::system_error Thrown on failure. An error code of
100
* boost::asio::error::eof indicates that the connection was closed by the
103
* @note The write_some_at operation may not write all of the data. Consider
104
* using the @ref write_at function if you need to ensure that all data is
105
* written before the blocking operation completes.
108
* To write a single data buffer use the @ref buffer function as follows:
110
* handle.write_some_at(42, boost::asio::buffer(data, size));
112
* See the @ref buffer documentation for information on writing multiple
113
* buffers in one go, and how to use it with arrays, boost::array or
116
template <typename ConstBufferSequence>
117
std::size_t write_some_at(boost::uint64_t offset,
118
const ConstBufferSequence& buffers)
120
boost::system::error_code ec;
121
std::size_t s = this->service.write_some_at(
122
this->implementation, offset, buffers, ec);
123
boost::asio::detail::throw_error(ec);
127
/// Write some data to the handle at the specified offset.
129
* This function is used to write data to the random-access handle. The
130
* function call will block until one or more bytes of the data has been
131
* written successfully, or until an error occurs.
133
* @param offset The offset at which the data will be written.
135
* @param buffers One or more data buffers to be written to the handle.
137
* @param ec Set to indicate what error occurred, if any.
139
* @returns The number of bytes written. Returns 0 if an error occurred.
141
* @note The write_some operation may not transmit all of the data to the
142
* peer. Consider using the @ref write_at function if you need to ensure that
143
* all data is written before the blocking operation completes.
145
template <typename ConstBufferSequence>
146
std::size_t write_some_at(boost::uint64_t offset,
147
const ConstBufferSequence& buffers, boost::system::error_code& ec)
149
return this->service.write_some_at(
150
this->implementation, offset, buffers, ec);
153
/// Start an asynchronous write at the specified offset.
155
* This function is used to asynchronously write data to the random-access
156
* handle. The function call always returns immediately.
158
* @param offset The offset at which the data will be written.
160
* @param buffers One or more data buffers to be written to the handle.
161
* Although the buffers object may be copied as necessary, ownership of the
162
* underlying memory blocks is retained by the caller, which must guarantee
163
* that they remain valid until the handler is called.
165
* @param handler The handler to be called when the write operation completes.
166
* Copies will be made of the handler as required. The function signature of
167
* the handler must be:
168
* @code void handler(
169
* const boost::system::error_code& error, // Result of operation.
170
* std::size_t bytes_transferred // Number of bytes written.
172
* Regardless of whether the asynchronous operation completes immediately or
173
* not, the handler will not be invoked from within this function. Invocation
174
* of the handler will be performed in a manner equivalent to using
175
* boost::asio::io_service::post().
177
* @note The write operation may not transmit all of the data to the peer.
178
* Consider using the @ref async_write_at function if you need to ensure that
179
* all data is written before the asynchronous operation completes.
182
* To write a single data buffer use the @ref buffer function as follows:
184
* handle.async_write_some_at(42, boost::asio::buffer(data, size), handler);
186
* See the @ref buffer documentation for information on writing multiple
187
* buffers in one go, and how to use it with arrays, boost::array or
190
template <typename ConstBufferSequence, typename WriteHandler>
191
void async_write_some_at(boost::uint64_t offset,
192
const ConstBufferSequence& buffers, WriteHandler handler)
194
this->service.async_write_some_at(
195
this->implementation, offset, buffers, handler);
198
/// Read some data from the handle at the specified offset.
200
* This function is used to read data from the random-access handle. The
201
* function call will block until one or more bytes of data has been read
202
* successfully, or until an error occurs.
204
* @param offset The offset at which the data will be read.
206
* @param buffers One or more buffers into which the data will be read.
208
* @returns The number of bytes read.
210
* @throws boost::system::system_error Thrown on failure. An error code of
211
* boost::asio::error::eof indicates that the connection was closed by the
214
* @note The read_some operation may not read all of the requested number of
215
* bytes. Consider using the @ref read_at function if you need to ensure that
216
* the requested amount of data is read before the blocking operation
220
* To read into a single data buffer use the @ref buffer function as follows:
222
* handle.read_some_at(42, boost::asio::buffer(data, size));
224
* See the @ref buffer documentation for information on reading into multiple
225
* buffers in one go, and how to use it with arrays, boost::array or
228
template <typename MutableBufferSequence>
229
std::size_t read_some_at(boost::uint64_t offset,
230
const MutableBufferSequence& buffers)
232
boost::system::error_code ec;
233
std::size_t s = this->service.read_some_at(
234
this->implementation, offset, buffers, ec);
235
boost::asio::detail::throw_error(ec);
239
/// Read some data from the handle at the specified offset.
241
* This function is used to read data from the random-access handle. The
242
* function call will block until one or more bytes of data has been read
243
* successfully, or until an error occurs.
245
* @param offset The offset at which the data will be read.
247
* @param buffers One or more buffers into which the data will be read.
249
* @param ec Set to indicate what error occurred, if any.
251
* @returns The number of bytes read. Returns 0 if an error occurred.
253
* @note The read_some operation may not read all of the requested number of
254
* bytes. Consider using the @ref read_at function if you need to ensure that
255
* the requested amount of data is read before the blocking operation
258
template <typename MutableBufferSequence>
259
std::size_t read_some_at(boost::uint64_t offset,
260
const MutableBufferSequence& buffers, boost::system::error_code& ec)
262
return this->service.read_some_at(
263
this->implementation, offset, buffers, ec);
266
/// Start an asynchronous read at the specified offset.
268
* This function is used to asynchronously read data from the random-access
269
* handle. The function call always returns immediately.
271
* @param offset The offset at which the data will be read.
273
* @param buffers One or more buffers into which the data will be read.
274
* Although the buffers object may be copied as necessary, ownership of the
275
* underlying memory blocks is retained by the caller, which must guarantee
276
* that they remain valid until the handler is called.
278
* @param handler The handler to be called when the read operation completes.
279
* Copies will be made of the handler as required. The function signature of
280
* the handler must be:
281
* @code void handler(
282
* const boost::system::error_code& error, // Result of operation.
283
* std::size_t bytes_transferred // Number of bytes read.
285
* Regardless of whether the asynchronous operation completes immediately or
286
* not, the handler will not be invoked from within this function. Invocation
287
* of the handler will be performed in a manner equivalent to using
288
* boost::asio::io_service::post().
290
* @note The read operation may not read all of the requested number of bytes.
291
* Consider using the @ref async_read_at function if you need to ensure that
292
* the requested amount of data is read before the asynchronous operation
296
* To read into a single data buffer use the @ref buffer function as follows:
298
* handle.async_read_some_at(42, boost::asio::buffer(data, size), handler);
300
* See the @ref buffer documentation for information on reading into multiple
301
* buffers in one go, and how to use it with arrays, boost::array or
304
template <typename MutableBufferSequence, typename ReadHandler>
305
void async_read_some_at(boost::uint64_t offset,
306
const MutableBufferSequence& buffers, ReadHandler handler)
308
this->service.async_read_some_at(
309
this->implementation, offset, buffers, handler);
313
} // namespace windows
317
#endif // defined(BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE)
318
// || defined(GENERATING_DOCUMENTATION)
320
#include <boost/asio/detail/pop_options.hpp>
322
#endif // BOOST_ASIO_WINDOWS_BASIC_RANDOM_ACCESS_HANDLE_HPP
added
removed
boost/boost/asio/windows/basic_random_access_handle.hpp
