Chris@16
|
1 //
|
Chris@16
|
2 // write_at.hpp
|
Chris@16
|
3 // ~~~~~~~~~~~~
|
Chris@16
|
4 //
|
Chris@101
|
5 // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
Chris@16
|
6 //
|
Chris@16
|
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
|
Chris@16
|
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
Chris@16
|
9 //
|
Chris@16
|
10
|
Chris@16
|
11 #ifndef BOOST_ASIO_WRITE_AT_HPP
|
Chris@16
|
12 #define BOOST_ASIO_WRITE_AT_HPP
|
Chris@16
|
13
|
Chris@16
|
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
|
Chris@16
|
15 # pragma once
|
Chris@16
|
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
|
Chris@16
|
17
|
Chris@16
|
18 #include <boost/asio/detail/config.hpp>
|
Chris@16
|
19 #include <cstddef>
|
Chris@16
|
20 #include <boost/asio/async_result.hpp>
|
Chris@16
|
21 #include <boost/asio/basic_streambuf_fwd.hpp>
|
Chris@16
|
22 #include <boost/asio/detail/cstdint.hpp>
|
Chris@16
|
23 #include <boost/asio/error.hpp>
|
Chris@16
|
24
|
Chris@16
|
25 #include <boost/asio/detail/push_options.hpp>
|
Chris@16
|
26
|
Chris@16
|
27 namespace boost {
|
Chris@16
|
28 namespace asio {
|
Chris@16
|
29
|
Chris@16
|
30 /**
|
Chris@16
|
31 * @defgroup write_at boost::asio::write_at
|
Chris@16
|
32 *
|
Chris@16
|
33 * @brief Write a certain amount of data at a specified offset before returning.
|
Chris@16
|
34 */
|
Chris@16
|
35 /*@{*/
|
Chris@16
|
36
|
Chris@16
|
37 /// Write all of the supplied data at the specified offset before returning.
|
Chris@16
|
38 /**
|
Chris@16
|
39 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
40 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
41 * following conditions is true:
|
Chris@16
|
42 *
|
Chris@16
|
43 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
44 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
45 *
|
Chris@16
|
46 * @li An error occurred.
|
Chris@16
|
47 *
|
Chris@16
|
48 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
49 * write_some_at function.
|
Chris@16
|
50 *
|
Chris@16
|
51 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
52 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
53 *
|
Chris@16
|
54 * @param offset The offset at which the data will be written.
|
Chris@16
|
55 *
|
Chris@16
|
56 * @param buffers One or more buffers containing the data to be written. The sum
|
Chris@16
|
57 * of the buffer sizes indicates the maximum number of bytes to write to the
|
Chris@16
|
58 * device.
|
Chris@16
|
59 *
|
Chris@16
|
60 * @returns The number of bytes transferred.
|
Chris@16
|
61 *
|
Chris@16
|
62 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
63 *
|
Chris@16
|
64 * @par Example
|
Chris@16
|
65 * To write a single data buffer use the @ref buffer function as follows:
|
Chris@16
|
66 * @code boost::asio::write_at(d, 42, boost::asio::buffer(data, size)); @endcode
|
Chris@16
|
67 * See the @ref buffer documentation for information on writing multiple
|
Chris@16
|
68 * buffers in one go, and how to use it with arrays, boost::array or
|
Chris@16
|
69 * std::vector.
|
Chris@16
|
70 *
|
Chris@16
|
71 * @note This overload is equivalent to calling:
|
Chris@16
|
72 * @code boost::asio::write_at(
|
Chris@16
|
73 * d, offset, buffers,
|
Chris@16
|
74 * boost::asio::transfer_all()); @endcode
|
Chris@16
|
75 */
|
Chris@16
|
76 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence>
|
Chris@16
|
77 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
78 uint64_t offset, const ConstBufferSequence& buffers);
|
Chris@16
|
79
|
Chris@16
|
80 /// Write all of the supplied data at the specified offset before returning.
|
Chris@16
|
81 /**
|
Chris@16
|
82 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
83 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
84 * following conditions is true:
|
Chris@16
|
85 *
|
Chris@16
|
86 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
87 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
88 *
|
Chris@16
|
89 * @li An error occurred.
|
Chris@16
|
90 *
|
Chris@16
|
91 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
92 * write_some_at function.
|
Chris@16
|
93 *
|
Chris@16
|
94 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
95 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
96 *
|
Chris@16
|
97 * @param offset The offset at which the data will be written.
|
Chris@16
|
98 *
|
Chris@16
|
99 * @param buffers One or more buffers containing the data to be written. The sum
|
Chris@16
|
100 * of the buffer sizes indicates the maximum number of bytes to write to the
|
Chris@16
|
101 * device.
|
Chris@16
|
102 *
|
Chris@16
|
103 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
104 *
|
Chris@16
|
105 * @returns The number of bytes transferred.
|
Chris@16
|
106 *
|
Chris@16
|
107 * @par Example
|
Chris@16
|
108 * To write a single data buffer use the @ref buffer function as follows:
|
Chris@16
|
109 * @code boost::asio::write_at(d, 42,
|
Chris@16
|
110 * boost::asio::buffer(data, size), ec); @endcode
|
Chris@16
|
111 * See the @ref buffer documentation for information on writing multiple
|
Chris@16
|
112 * buffers in one go, and how to use it with arrays, boost::array or
|
Chris@16
|
113 * std::vector.
|
Chris@16
|
114 *
|
Chris@16
|
115 * @note This overload is equivalent to calling:
|
Chris@16
|
116 * @code boost::asio::write_at(
|
Chris@16
|
117 * d, offset, buffers,
|
Chris@16
|
118 * boost::asio::transfer_all(), ec); @endcode
|
Chris@16
|
119 */
|
Chris@16
|
120 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence>
|
Chris@16
|
121 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
122 uint64_t offset, const ConstBufferSequence& buffers,
|
Chris@16
|
123 boost::system::error_code& ec);
|
Chris@16
|
124
|
Chris@16
|
125 /// Write a certain amount of data at a specified offset before returning.
|
Chris@16
|
126 /**
|
Chris@16
|
127 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
128 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
129 * following conditions is true:
|
Chris@16
|
130 *
|
Chris@16
|
131 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
132 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
133 *
|
Chris@16
|
134 * @li The completion_condition function object returns 0.
|
Chris@16
|
135 *
|
Chris@16
|
136 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
137 * write_some_at function.
|
Chris@16
|
138 *
|
Chris@16
|
139 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
140 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
141 *
|
Chris@16
|
142 * @param offset The offset at which the data will be written.
|
Chris@16
|
143 *
|
Chris@16
|
144 * @param buffers One or more buffers containing the data to be written. The sum
|
Chris@16
|
145 * of the buffer sizes indicates the maximum number of bytes to write to the
|
Chris@16
|
146 * device.
|
Chris@16
|
147 *
|
Chris@16
|
148 * @param completion_condition The function object to be called to determine
|
Chris@16
|
149 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
150 * must be:
|
Chris@16
|
151 * @code std::size_t completion_condition(
|
Chris@16
|
152 * // Result of latest write_some_at operation.
|
Chris@16
|
153 * const boost::system::error_code& error,
|
Chris@16
|
154 *
|
Chris@16
|
155 * // Number of bytes transferred so far.
|
Chris@16
|
156 * std::size_t bytes_transferred
|
Chris@16
|
157 * ); @endcode
|
Chris@16
|
158 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
159 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
160 * the next call to the device's write_some_at function.
|
Chris@16
|
161 *
|
Chris@16
|
162 * @returns The number of bytes transferred.
|
Chris@16
|
163 *
|
Chris@16
|
164 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
165 *
|
Chris@16
|
166 * @par Example
|
Chris@16
|
167 * To write a single data buffer use the @ref buffer function as follows:
|
Chris@16
|
168 * @code boost::asio::write_at(d, 42, boost::asio::buffer(data, size),
|
Chris@16
|
169 * boost::asio::transfer_at_least(32)); @endcode
|
Chris@16
|
170 * See the @ref buffer documentation for information on writing multiple
|
Chris@16
|
171 * buffers in one go, and how to use it with arrays, boost::array or
|
Chris@16
|
172 * std::vector.
|
Chris@16
|
173 */
|
Chris@16
|
174 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
|
Chris@16
|
175 typename CompletionCondition>
|
Chris@16
|
176 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
177 uint64_t offset, const ConstBufferSequence& buffers,
|
Chris@16
|
178 CompletionCondition completion_condition);
|
Chris@16
|
179
|
Chris@16
|
180 /// Write a certain amount of data at a specified offset before returning.
|
Chris@16
|
181 /**
|
Chris@16
|
182 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
183 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
184 * following conditions is true:
|
Chris@16
|
185 *
|
Chris@16
|
186 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
187 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
188 *
|
Chris@16
|
189 * @li The completion_condition function object returns 0.
|
Chris@16
|
190 *
|
Chris@16
|
191 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
192 * write_some_at function.
|
Chris@16
|
193 *
|
Chris@16
|
194 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
195 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
196 *
|
Chris@16
|
197 * @param offset The offset at which the data will be written.
|
Chris@16
|
198 *
|
Chris@16
|
199 * @param buffers One or more buffers containing the data to be written. The sum
|
Chris@16
|
200 * of the buffer sizes indicates the maximum number of bytes to write to the
|
Chris@16
|
201 * device.
|
Chris@16
|
202 *
|
Chris@16
|
203 * @param completion_condition The function object to be called to determine
|
Chris@16
|
204 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
205 * must be:
|
Chris@16
|
206 * @code std::size_t completion_condition(
|
Chris@16
|
207 * // Result of latest write_some_at operation.
|
Chris@16
|
208 * const boost::system::error_code& error,
|
Chris@16
|
209 *
|
Chris@16
|
210 * // Number of bytes transferred so far.
|
Chris@16
|
211 * std::size_t bytes_transferred
|
Chris@16
|
212 * ); @endcode
|
Chris@16
|
213 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
214 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
215 * the next call to the device's write_some_at function.
|
Chris@16
|
216 *
|
Chris@16
|
217 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
218 *
|
Chris@16
|
219 * @returns The number of bytes written. If an error occurs, returns the total
|
Chris@16
|
220 * number of bytes successfully transferred prior to the error.
|
Chris@16
|
221 */
|
Chris@16
|
222 template <typename SyncRandomAccessWriteDevice, typename ConstBufferSequence,
|
Chris@16
|
223 typename CompletionCondition>
|
Chris@16
|
224 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
225 uint64_t offset, const ConstBufferSequence& buffers,
|
Chris@16
|
226 CompletionCondition completion_condition, boost::system::error_code& ec);
|
Chris@16
|
227
|
Chris@16
|
228 #if !defined(BOOST_ASIO_NO_IOSTREAM)
|
Chris@16
|
229
|
Chris@16
|
230 /// Write all of the supplied data at the specified offset before returning.
|
Chris@16
|
231 /**
|
Chris@16
|
232 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
233 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
234 * following conditions is true:
|
Chris@16
|
235 *
|
Chris@16
|
236 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
237 *
|
Chris@16
|
238 * @li An error occurred.
|
Chris@16
|
239 *
|
Chris@16
|
240 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
241 * write_some_at function.
|
Chris@16
|
242 *
|
Chris@16
|
243 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
244 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
245 *
|
Chris@16
|
246 * @param offset The offset at which the data will be written.
|
Chris@16
|
247 *
|
Chris@16
|
248 * @param b The basic_streambuf object from which data will be written.
|
Chris@16
|
249 *
|
Chris@16
|
250 * @returns The number of bytes transferred.
|
Chris@16
|
251 *
|
Chris@16
|
252 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
253 *
|
Chris@16
|
254 * @note This overload is equivalent to calling:
|
Chris@16
|
255 * @code boost::asio::write_at(
|
Chris@16
|
256 * d, 42, b,
|
Chris@16
|
257 * boost::asio::transfer_all()); @endcode
|
Chris@16
|
258 */
|
Chris@16
|
259 template <typename SyncRandomAccessWriteDevice, typename Allocator>
|
Chris@16
|
260 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
261 uint64_t offset, basic_streambuf<Allocator>& b);
|
Chris@16
|
262
|
Chris@16
|
263 /// Write all of the supplied data at the specified offset before returning.
|
Chris@16
|
264 /**
|
Chris@16
|
265 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
266 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
267 * following conditions is true:
|
Chris@16
|
268 *
|
Chris@16
|
269 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
270 *
|
Chris@16
|
271 * @li An error occurred.
|
Chris@16
|
272 *
|
Chris@16
|
273 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
274 * write_some_at function.
|
Chris@16
|
275 *
|
Chris@16
|
276 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
277 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
278 *
|
Chris@16
|
279 * @param offset The offset at which the data will be written.
|
Chris@16
|
280 *
|
Chris@16
|
281 * @param b The basic_streambuf object from which data will be written.
|
Chris@16
|
282 *
|
Chris@16
|
283 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
284 *
|
Chris@16
|
285 * @returns The number of bytes transferred.
|
Chris@16
|
286 *
|
Chris@16
|
287 * @note This overload is equivalent to calling:
|
Chris@16
|
288 * @code boost::asio::write_at(
|
Chris@16
|
289 * d, 42, b,
|
Chris@16
|
290 * boost::asio::transfer_all(), ec); @endcode
|
Chris@16
|
291 */
|
Chris@16
|
292 template <typename SyncRandomAccessWriteDevice, typename Allocator>
|
Chris@16
|
293 std::size_t write_at(SyncRandomAccessWriteDevice& d,
|
Chris@16
|
294 uint64_t offset, basic_streambuf<Allocator>& b,
|
Chris@16
|
295 boost::system::error_code& ec);
|
Chris@16
|
296
|
Chris@16
|
297 /// Write a certain amount of data at a specified offset before returning.
|
Chris@16
|
298 /**
|
Chris@16
|
299 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
300 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
301 * following conditions is true:
|
Chris@16
|
302 *
|
Chris@16
|
303 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
304 *
|
Chris@16
|
305 * @li The completion_condition function object returns 0.
|
Chris@16
|
306 *
|
Chris@16
|
307 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
308 * write_some_at function.
|
Chris@16
|
309 *
|
Chris@16
|
310 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
311 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
312 *
|
Chris@16
|
313 * @param offset The offset at which the data will be written.
|
Chris@16
|
314 *
|
Chris@16
|
315 * @param b The basic_streambuf object from which data will be written.
|
Chris@16
|
316 *
|
Chris@16
|
317 * @param completion_condition The function object to be called to determine
|
Chris@16
|
318 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
319 * must be:
|
Chris@16
|
320 * @code std::size_t completion_condition(
|
Chris@16
|
321 * // Result of latest write_some_at operation.
|
Chris@16
|
322 * const boost::system::error_code& error,
|
Chris@16
|
323 *
|
Chris@16
|
324 * // Number of bytes transferred so far.
|
Chris@16
|
325 * std::size_t bytes_transferred
|
Chris@16
|
326 * ); @endcode
|
Chris@16
|
327 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
328 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
329 * the next call to the device's write_some_at function.
|
Chris@16
|
330 *
|
Chris@16
|
331 * @returns The number of bytes transferred.
|
Chris@16
|
332 *
|
Chris@16
|
333 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
334 */
|
Chris@16
|
335 template <typename SyncRandomAccessWriteDevice, typename Allocator,
|
Chris@16
|
336 typename CompletionCondition>
|
Chris@16
|
337 std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset,
|
Chris@16
|
338 basic_streambuf<Allocator>& b, CompletionCondition completion_condition);
|
Chris@16
|
339
|
Chris@16
|
340 /// Write a certain amount of data at a specified offset before returning.
|
Chris@16
|
341 /**
|
Chris@16
|
342 * This function is used to write a certain number of bytes of data to a random
|
Chris@16
|
343 * access device at a specified offset. The call will block until one of the
|
Chris@16
|
344 * following conditions is true:
|
Chris@16
|
345 *
|
Chris@16
|
346 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
347 *
|
Chris@16
|
348 * @li The completion_condition function object returns 0.
|
Chris@16
|
349 *
|
Chris@16
|
350 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
351 * write_some_at function.
|
Chris@16
|
352 *
|
Chris@16
|
353 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
354 * the SyncRandomAccessWriteDevice concept.
|
Chris@16
|
355 *
|
Chris@16
|
356 * @param offset The offset at which the data will be written.
|
Chris@16
|
357 *
|
Chris@16
|
358 * @param b The basic_streambuf object from which data will be written.
|
Chris@16
|
359 *
|
Chris@16
|
360 * @param completion_condition The function object to be called to determine
|
Chris@16
|
361 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
362 * must be:
|
Chris@16
|
363 * @code std::size_t completion_condition(
|
Chris@16
|
364 * // Result of latest write_some_at operation.
|
Chris@16
|
365 * const boost::system::error_code& error,
|
Chris@16
|
366 *
|
Chris@16
|
367 * // Number of bytes transferred so far.
|
Chris@16
|
368 * std::size_t bytes_transferred
|
Chris@16
|
369 * ); @endcode
|
Chris@16
|
370 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
371 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
372 * the next call to the device's write_some_at function.
|
Chris@16
|
373 *
|
Chris@16
|
374 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
375 *
|
Chris@16
|
376 * @returns The number of bytes written. If an error occurs, returns the total
|
Chris@16
|
377 * number of bytes successfully transferred prior to the error.
|
Chris@16
|
378 */
|
Chris@16
|
379 template <typename SyncRandomAccessWriteDevice, typename Allocator,
|
Chris@16
|
380 typename CompletionCondition>
|
Chris@16
|
381 std::size_t write_at(SyncRandomAccessWriteDevice& d, uint64_t offset,
|
Chris@16
|
382 basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
|
Chris@16
|
383 boost::system::error_code& ec);
|
Chris@16
|
384
|
Chris@16
|
385 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
|
Chris@16
|
386
|
Chris@16
|
387 /*@}*/
|
Chris@16
|
388 /**
|
Chris@16
|
389 * @defgroup async_write_at boost::asio::async_write_at
|
Chris@16
|
390 *
|
Chris@16
|
391 * @brief Start an asynchronous operation to write a certain amount of data at
|
Chris@16
|
392 * the specified offset.
|
Chris@16
|
393 */
|
Chris@16
|
394 /*@{*/
|
Chris@16
|
395
|
Chris@16
|
396 /// Start an asynchronous operation to write all of the supplied data at the
|
Chris@16
|
397 /// specified offset.
|
Chris@16
|
398 /**
|
Chris@16
|
399 * This function is used to asynchronously write a certain number of bytes of
|
Chris@16
|
400 * data to a random access device at a specified offset. The function call
|
Chris@16
|
401 * always returns immediately. The asynchronous operation will continue until
|
Chris@16
|
402 * one of the following conditions is true:
|
Chris@16
|
403 *
|
Chris@16
|
404 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
405 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
406 *
|
Chris@16
|
407 * @li An error occurred.
|
Chris@16
|
408 *
|
Chris@16
|
409 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
410 * async_write_some_at function, and is known as a <em>composed operation</em>.
|
Chris@16
|
411 * The program must ensure that the device performs no <em>overlapping</em>
|
Chris@16
|
412 * write operations (such as async_write_at, the device's async_write_some_at
|
Chris@16
|
413 * function, or any other composed operations that perform writes) until this
|
Chris@16
|
414 * operation completes. Operations are overlapping if the regions defined by
|
Chris@16
|
415 * their offsets, and the numbers of bytes to write, intersect.
|
Chris@16
|
416 *
|
Chris@16
|
417 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
418 * the AsyncRandomAccessWriteDevice concept.
|
Chris@16
|
419 *
|
Chris@16
|
420 * @param offset The offset at which the data will be written.
|
Chris@16
|
421 *
|
Chris@16
|
422 * @param buffers One or more buffers containing the data to be written.
|
Chris@16
|
423 * Although the buffers object may be copied as necessary, ownership of the
|
Chris@16
|
424 * underlying memory blocks is retained by the caller, which must guarantee
|
Chris@16
|
425 * that they remain valid until the handler is called.
|
Chris@16
|
426 *
|
Chris@16
|
427 * @param handler The handler to be called when the write operation completes.
|
Chris@16
|
428 * Copies will be made of the handler as required. The function signature of
|
Chris@16
|
429 * the handler must be:
|
Chris@16
|
430 * @code void handler(
|
Chris@16
|
431 * // Result of operation.
|
Chris@16
|
432 * const boost::system::error_code& error,
|
Chris@16
|
433 *
|
Chris@16
|
434 * // Number of bytes written from the buffers. If an error
|
Chris@16
|
435 * // occurred, this will be less than the sum of the buffer sizes.
|
Chris@16
|
436 * std::size_t bytes_transferred
|
Chris@16
|
437 * ); @endcode
|
Chris@16
|
438 * Regardless of whether the asynchronous operation completes immediately or
|
Chris@16
|
439 * not, the handler will not be invoked from within this function. Invocation of
|
Chris@16
|
440 * the handler will be performed in a manner equivalent to using
|
Chris@16
|
441 * boost::asio::io_service::post().
|
Chris@16
|
442 *
|
Chris@16
|
443 * @par Example
|
Chris@16
|
444 * To write a single data buffer use the @ref buffer function as follows:
|
Chris@16
|
445 * @code
|
Chris@16
|
446 * boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler);
|
Chris@16
|
447 * @endcode
|
Chris@16
|
448 * See the @ref buffer documentation for information on writing multiple
|
Chris@16
|
449 * buffers in one go, and how to use it with arrays, boost::array or
|
Chris@16
|
450 * std::vector.
|
Chris@16
|
451 */
|
Chris@16
|
452 template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence,
|
Chris@16
|
453 typename WriteHandler>
|
Chris@16
|
454 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
|
Chris@16
|
455 void (boost::system::error_code, std::size_t))
|
Chris@16
|
456 async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset,
|
Chris@16
|
457 const ConstBufferSequence& buffers,
|
Chris@16
|
458 BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
|
Chris@16
|
459
|
Chris@16
|
460 /// Start an asynchronous operation to write a certain amount of data at the
|
Chris@16
|
461 /// specified offset.
|
Chris@16
|
462 /**
|
Chris@16
|
463 * This function is used to asynchronously write a certain number of bytes of
|
Chris@16
|
464 * data to a random access device at a specified offset. The function call
|
Chris@16
|
465 * always returns immediately. The asynchronous operation will continue until
|
Chris@16
|
466 * one of the following conditions is true:
|
Chris@16
|
467 *
|
Chris@16
|
468 * @li All of the data in the supplied buffers has been written. That is, the
|
Chris@16
|
469 * bytes transferred is equal to the sum of the buffer sizes.
|
Chris@16
|
470 *
|
Chris@16
|
471 * @li The completion_condition function object returns 0.
|
Chris@16
|
472 *
|
Chris@16
|
473 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
474 * async_write_some_at function, and is known as a <em>composed operation</em>.
|
Chris@16
|
475 * The program must ensure that the device performs no <em>overlapping</em>
|
Chris@16
|
476 * write operations (such as async_write_at, the device's async_write_some_at
|
Chris@16
|
477 * function, or any other composed operations that perform writes) until this
|
Chris@16
|
478 * operation completes. Operations are overlapping if the regions defined by
|
Chris@16
|
479 * their offsets, and the numbers of bytes to write, intersect.
|
Chris@16
|
480 *
|
Chris@16
|
481 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
482 * the AsyncRandomAccessWriteDevice concept.
|
Chris@16
|
483 *
|
Chris@16
|
484 * @param offset The offset at which the data will be written.
|
Chris@16
|
485 *
|
Chris@16
|
486 * @param buffers One or more buffers containing the data to be written.
|
Chris@16
|
487 * Although the buffers object may be copied as necessary, ownership of the
|
Chris@16
|
488 * underlying memory blocks is retained by the caller, which must guarantee
|
Chris@16
|
489 * that they remain valid until the handler is called.
|
Chris@16
|
490 *
|
Chris@16
|
491 * @param completion_condition The function object to be called to determine
|
Chris@16
|
492 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
493 * must be:
|
Chris@16
|
494 * @code std::size_t completion_condition(
|
Chris@16
|
495 * // Result of latest async_write_some_at operation.
|
Chris@16
|
496 * const boost::system::error_code& error,
|
Chris@16
|
497 *
|
Chris@16
|
498 * // Number of bytes transferred so far.
|
Chris@16
|
499 * std::size_t bytes_transferred
|
Chris@16
|
500 * ); @endcode
|
Chris@16
|
501 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
502 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
503 * the next call to the device's async_write_some_at function.
|
Chris@16
|
504 *
|
Chris@16
|
505 * @param handler The handler to be called when the write operation completes.
|
Chris@16
|
506 * Copies will be made of the handler as required. The function signature of the
|
Chris@16
|
507 * handler must be:
|
Chris@16
|
508 * @code void handler(
|
Chris@16
|
509 * // Result of operation.
|
Chris@16
|
510 * const boost::system::error_code& error,
|
Chris@16
|
511 *
|
Chris@16
|
512 * // Number of bytes written from the buffers. If an error
|
Chris@16
|
513 * // occurred, this will be less than the sum of the buffer sizes.
|
Chris@16
|
514 * std::size_t bytes_transferred
|
Chris@16
|
515 * ); @endcode
|
Chris@16
|
516 * Regardless of whether the asynchronous operation completes immediately or
|
Chris@16
|
517 * not, the handler will not be invoked from within this function. Invocation of
|
Chris@16
|
518 * the handler will be performed in a manner equivalent to using
|
Chris@16
|
519 * boost::asio::io_service::post().
|
Chris@16
|
520 *
|
Chris@16
|
521 * @par Example
|
Chris@16
|
522 * To write a single data buffer use the @ref buffer function as follows:
|
Chris@16
|
523 * @code boost::asio::async_write_at(d, 42,
|
Chris@16
|
524 * boost::asio::buffer(data, size),
|
Chris@16
|
525 * boost::asio::transfer_at_least(32),
|
Chris@16
|
526 * handler); @endcode
|
Chris@16
|
527 * See the @ref buffer documentation for information on writing multiple
|
Chris@16
|
528 * buffers in one go, and how to use it with arrays, boost::array or
|
Chris@16
|
529 * std::vector.
|
Chris@16
|
530 */
|
Chris@16
|
531 template <typename AsyncRandomAccessWriteDevice, typename ConstBufferSequence,
|
Chris@16
|
532 typename CompletionCondition, typename WriteHandler>
|
Chris@16
|
533 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
|
Chris@16
|
534 void (boost::system::error_code, std::size_t))
|
Chris@16
|
535 async_write_at(AsyncRandomAccessWriteDevice& d,
|
Chris@16
|
536 uint64_t offset, const ConstBufferSequence& buffers,
|
Chris@16
|
537 CompletionCondition completion_condition,
|
Chris@16
|
538 BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
|
Chris@16
|
539
|
Chris@16
|
540 #if !defined(BOOST_ASIO_NO_IOSTREAM)
|
Chris@16
|
541
|
Chris@16
|
542 /// Start an asynchronous operation to write all of the supplied data at the
|
Chris@16
|
543 /// specified offset.
|
Chris@16
|
544 /**
|
Chris@16
|
545 * This function is used to asynchronously write a certain number of bytes of
|
Chris@16
|
546 * data to a random access device at a specified offset. The function call
|
Chris@16
|
547 * always returns immediately. The asynchronous operation will continue until
|
Chris@16
|
548 * one of the following conditions is true:
|
Chris@16
|
549 *
|
Chris@16
|
550 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
551 *
|
Chris@16
|
552 * @li An error occurred.
|
Chris@16
|
553 *
|
Chris@16
|
554 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
555 * async_write_some_at function, and is known as a <em>composed operation</em>.
|
Chris@16
|
556 * The program must ensure that the device performs no <em>overlapping</em>
|
Chris@16
|
557 * write operations (such as async_write_at, the device's async_write_some_at
|
Chris@16
|
558 * function, or any other composed operations that perform writes) until this
|
Chris@16
|
559 * operation completes. Operations are overlapping if the regions defined by
|
Chris@16
|
560 * their offsets, and the numbers of bytes to write, intersect.
|
Chris@16
|
561 *
|
Chris@16
|
562 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
563 * the AsyncRandomAccessWriteDevice concept.
|
Chris@16
|
564 *
|
Chris@16
|
565 * @param offset The offset at which the data will be written.
|
Chris@16
|
566 *
|
Chris@16
|
567 * @param b A basic_streambuf object from which data will be written. Ownership
|
Chris@16
|
568 * of the streambuf is retained by the caller, which must guarantee that it
|
Chris@16
|
569 * remains valid until the handler is called.
|
Chris@16
|
570 *
|
Chris@16
|
571 * @param handler The handler to be called when the write operation completes.
|
Chris@16
|
572 * Copies will be made of the handler as required. The function signature of the
|
Chris@16
|
573 * handler must be:
|
Chris@16
|
574 * @code void handler(
|
Chris@16
|
575 * // Result of operation.
|
Chris@16
|
576 * const boost::system::error_code& error,
|
Chris@16
|
577 *
|
Chris@16
|
578 * // Number of bytes written from the buffers. If an error
|
Chris@16
|
579 * // occurred, this will be less than the sum of the buffer sizes.
|
Chris@16
|
580 * std::size_t bytes_transferred
|
Chris@16
|
581 * ); @endcode
|
Chris@16
|
582 * Regardless of whether the asynchronous operation completes immediately or
|
Chris@16
|
583 * not, the handler will not be invoked from within this function. Invocation of
|
Chris@16
|
584 * the handler will be performed in a manner equivalent to using
|
Chris@16
|
585 * boost::asio::io_service::post().
|
Chris@16
|
586 */
|
Chris@16
|
587 template <typename AsyncRandomAccessWriteDevice, typename Allocator,
|
Chris@16
|
588 typename WriteHandler>
|
Chris@16
|
589 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
|
Chris@16
|
590 void (boost::system::error_code, std::size_t))
|
Chris@16
|
591 async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset,
|
Chris@16
|
592 basic_streambuf<Allocator>& b, BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
|
Chris@16
|
593
|
Chris@16
|
594 /// Start an asynchronous operation to write a certain amount of data at the
|
Chris@16
|
595 /// specified offset.
|
Chris@16
|
596 /**
|
Chris@16
|
597 * This function is used to asynchronously write a certain number of bytes of
|
Chris@16
|
598 * data to a random access device at a specified offset. The function call
|
Chris@16
|
599 * always returns immediately. The asynchronous operation will continue until
|
Chris@16
|
600 * one of the following conditions is true:
|
Chris@16
|
601 *
|
Chris@16
|
602 * @li All of the data in the supplied basic_streambuf has been written.
|
Chris@16
|
603 *
|
Chris@16
|
604 * @li The completion_condition function object returns 0.
|
Chris@16
|
605 *
|
Chris@16
|
606 * This operation is implemented in terms of zero or more calls to the device's
|
Chris@16
|
607 * async_write_some_at function, and is known as a <em>composed operation</em>.
|
Chris@16
|
608 * The program must ensure that the device performs no <em>overlapping</em>
|
Chris@16
|
609 * write operations (such as async_write_at, the device's async_write_some_at
|
Chris@16
|
610 * function, or any other composed operations that perform writes) until this
|
Chris@16
|
611 * operation completes. Operations are overlapping if the regions defined by
|
Chris@16
|
612 * their offsets, and the numbers of bytes to write, intersect.
|
Chris@16
|
613 *
|
Chris@16
|
614 * @param d The device to which the data is to be written. The type must support
|
Chris@16
|
615 * the AsyncRandomAccessWriteDevice concept.
|
Chris@16
|
616 *
|
Chris@16
|
617 * @param offset The offset at which the data will be written.
|
Chris@16
|
618 *
|
Chris@16
|
619 * @param b A basic_streambuf object from which data will be written. Ownership
|
Chris@16
|
620 * of the streambuf is retained by the caller, which must guarantee that it
|
Chris@16
|
621 * remains valid until the handler is called.
|
Chris@16
|
622 *
|
Chris@16
|
623 * @param completion_condition The function object to be called to determine
|
Chris@16
|
624 * whether the write operation is complete. The signature of the function object
|
Chris@16
|
625 * must be:
|
Chris@16
|
626 * @code std::size_t completion_condition(
|
Chris@16
|
627 * // Result of latest async_write_some_at operation.
|
Chris@16
|
628 * const boost::system::error_code& error,
|
Chris@16
|
629 *
|
Chris@16
|
630 * // Number of bytes transferred so far.
|
Chris@16
|
631 * std::size_t bytes_transferred
|
Chris@16
|
632 * ); @endcode
|
Chris@16
|
633 * A return value of 0 indicates that the write operation is complete. A
|
Chris@16
|
634 * non-zero return value indicates the maximum number of bytes to be written on
|
Chris@16
|
635 * the next call to the device's async_write_some_at function.
|
Chris@16
|
636 *
|
Chris@16
|
637 * @param handler The handler to be called when the write operation completes.
|
Chris@16
|
638 * Copies will be made of the handler as required. The function signature of the
|
Chris@16
|
639 * handler must be:
|
Chris@16
|
640 * @code void handler(
|
Chris@16
|
641 * // Result of operation.
|
Chris@16
|
642 * const boost::system::error_code& error,
|
Chris@16
|
643 *
|
Chris@16
|
644 * // Number of bytes written from the buffers. If an error
|
Chris@16
|
645 * // occurred, this will be less than the sum of the buffer sizes.
|
Chris@16
|
646 * std::size_t bytes_transferred
|
Chris@16
|
647 * ); @endcode
|
Chris@16
|
648 * Regardless of whether the asynchronous operation completes immediately or
|
Chris@16
|
649 * not, the handler will not be invoked from within this function. Invocation of
|
Chris@16
|
650 * the handler will be performed in a manner equivalent to using
|
Chris@16
|
651 * boost::asio::io_service::post().
|
Chris@16
|
652 */
|
Chris@16
|
653 template <typename AsyncRandomAccessWriteDevice, typename Allocator,
|
Chris@16
|
654 typename CompletionCondition, typename WriteHandler>
|
Chris@16
|
655 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
|
Chris@16
|
656 void (boost::system::error_code, std::size_t))
|
Chris@16
|
657 async_write_at(AsyncRandomAccessWriteDevice& d, uint64_t offset,
|
Chris@16
|
658 basic_streambuf<Allocator>& b, CompletionCondition completion_condition,
|
Chris@16
|
659 BOOST_ASIO_MOVE_ARG(WriteHandler) handler);
|
Chris@16
|
660
|
Chris@16
|
661 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
|
Chris@16
|
662
|
Chris@16
|
663 /*@}*/
|
Chris@16
|
664
|
Chris@16
|
665 } // namespace asio
|
Chris@16
|
666 } // namespace boost
|
Chris@16
|
667
|
Chris@16
|
668 #include <boost/asio/detail/pop_options.hpp>
|
Chris@16
|
669
|
Chris@16
|
670 #include <boost/asio/impl/write_at.hpp>
|
Chris@16
|
671
|
Chris@16
|
672 #endif // BOOST_ASIO_WRITE_AT_HPP
|