1 | // |
2 | // write.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_WRITE_HPP |
12 | #define BOOST_ASIO_WRITE_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/buffer.hpp> |
22 | #include <boost/asio/completion_condition.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 | |
31 | namespace boost { |
32 | namespace asio { |
33 | namespace detail { |
34 | |
35 | template <typename> class initiate_async_write; |
36 | #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
37 | template <typename> class initiate_async_write_dynbuf_v1; |
38 | #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
39 | template <typename> class initiate_async_write_dynbuf_v2; |
40 | |
41 | } // namespace detail |
42 | |
43 | /** |
44 | * @defgroup write boost::asio::write |
45 | * |
46 | * @brief The @c write function is a composed operation that writes a certain |
47 | * amount of data to a stream before returning. |
48 | */ |
49 | /*@{*/ |
50 | |
51 | /// Write all of the supplied data to a stream before returning. |
52 | /** |
53 | * This function is used to write a certain number of bytes of data to a stream. |
54 | * The call will block until one of the following conditions is true: |
55 | * |
56 | * @li All of the data in the supplied buffers has been written. That is, the |
57 | * bytes transferred is equal to the sum of the buffer sizes. |
58 | * |
59 | * @li An error occurred. |
60 | * |
61 | * This operation is implemented in terms of zero or more calls to the stream's |
62 | * write_some function. |
63 | * |
64 | * @param s The stream to which the data is to be written. The type must support |
65 | * the SyncWriteStream concept. |
66 | * |
67 | * @param buffers One or more buffers containing the data to be written. The sum |
68 | * of the buffer sizes indicates the maximum number of bytes to write to the |
69 | * stream. |
70 | * |
71 | * @returns The number of bytes transferred. |
72 | * |
73 | * @throws boost::system::system_error Thrown on failure. |
74 | * |
75 | * @par Example |
76 | * To write a single data buffer use the @ref buffer function as follows: |
77 | * @code boost::asio::write(s, boost::asio::buffer(data, size)); @endcode |
78 | * See the @ref buffer documentation for information on writing multiple |
79 | * buffers in one go, and how to use it with arrays, boost::array or |
80 | * std::vector. |
81 | * |
82 | * @note This overload is equivalent to calling: |
83 | * @code boost::asio::write( |
84 | * s, buffers, |
85 | * boost::asio::transfer_all()); @endcode |
86 | */ |
87 | template <typename SyncWriteStream, typename ConstBufferSequence> |
88 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, |
89 | constraint_t< |
90 | is_const_buffer_sequence<ConstBufferSequence>::value |
91 | > = 0); |
92 | |
93 | /// Write all of the supplied data to a stream before returning. |
94 | /** |
95 | * This function is used to write a certain number of bytes of data to a stream. |
96 | * The call will block until one of the following conditions is true: |
97 | * |
98 | * @li All of the data in the supplied buffers has been written. That is, the |
99 | * bytes transferred is equal to the sum of the buffer sizes. |
100 | * |
101 | * @li An error occurred. |
102 | * |
103 | * This operation is implemented in terms of zero or more calls to the stream's |
104 | * write_some function. |
105 | * |
106 | * @param s The stream to which the data is to be written. The type must support |
107 | * the SyncWriteStream concept. |
108 | * |
109 | * @param buffers One or more buffers containing the data to be written. The sum |
110 | * of the buffer sizes indicates the maximum number of bytes to write to the |
111 | * stream. |
112 | * |
113 | * @param ec Set to indicate what error occurred, if any. |
114 | * |
115 | * @returns The number of bytes transferred. |
116 | * |
117 | * @par Example |
118 | * To write a single data buffer use the @ref buffer function as follows: |
119 | * @code boost::asio::write(s, boost::asio::buffer(data, size), ec); @endcode |
120 | * See the @ref buffer documentation for information on writing multiple |
121 | * buffers in one go, and how to use it with arrays, boost::array or |
122 | * std::vector. |
123 | * |
124 | * @note This overload is equivalent to calling: |
125 | * @code boost::asio::write( |
126 | * s, buffers, |
127 | * boost::asio::transfer_all(), ec); @endcode |
128 | */ |
129 | template <typename SyncWriteStream, typename ConstBufferSequence> |
130 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, |
131 | boost::system::error_code& ec, |
132 | constraint_t< |
133 | is_const_buffer_sequence<ConstBufferSequence>::value |
134 | > = 0); |
135 | |
136 | /// Write a certain amount of data to a stream before returning. |
137 | /** |
138 | * This function is used to write a certain number of bytes of data to a stream. |
139 | * The call will block until one of the following conditions is true: |
140 | * |
141 | * @li All of the data in the supplied buffers has been written. That is, the |
142 | * bytes transferred is equal to the sum of the buffer sizes. |
143 | * |
144 | * @li The completion_condition function object returns 0. |
145 | * |
146 | * This operation is implemented in terms of zero or more calls to the stream's |
147 | * write_some function. |
148 | * |
149 | * @param s The stream to which the data is to be written. The type must support |
150 | * the SyncWriteStream concept. |
151 | * |
152 | * @param buffers One or more buffers containing the data to be written. The sum |
153 | * of the buffer sizes indicates the maximum number of bytes to write to the |
154 | * stream. |
155 | * |
156 | * @param completion_condition The function object to be called to determine |
157 | * whether the write operation is complete. The signature of the function object |
158 | * must be: |
159 | * @code std::size_t completion_condition( |
160 | * // Result of latest write_some operation. |
161 | * const boost::system::error_code& error, |
162 | * |
163 | * // Number of bytes transferred so far. |
164 | * std::size_t bytes_transferred |
165 | * ); @endcode |
166 | * A return value of 0 indicates that the write operation is complete. A |
167 | * non-zero return value indicates the maximum number of bytes to be written on |
168 | * the next call to the stream's write_some function. |
169 | * |
170 | * @returns The number of bytes transferred. |
171 | * |
172 | * @throws boost::system::system_error Thrown on failure. |
173 | * |
174 | * @par Example |
175 | * To write a single data buffer use the @ref buffer function as follows: |
176 | * @code boost::asio::write(s, boost::asio::buffer(data, size), |
177 | * boost::asio::transfer_at_least(32)); @endcode |
178 | * See the @ref buffer documentation for information on writing multiple |
179 | * buffers in one go, and how to use it with arrays, boost::array or |
180 | * std::vector. |
181 | */ |
182 | template <typename SyncWriteStream, typename ConstBufferSequence, |
183 | typename CompletionCondition> |
184 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, |
185 | CompletionCondition completion_condition, |
186 | constraint_t< |
187 | is_const_buffer_sequence<ConstBufferSequence>::value |
188 | > = 0); |
189 | |
190 | /// Write a certain amount of data to a stream before returning. |
191 | /** |
192 | * This function is used to write a certain number of bytes of data to a stream. |
193 | * The call will block until one of the following conditions is true: |
194 | * |
195 | * @li All of the data in the supplied buffers has been written. That is, the |
196 | * bytes transferred is equal to the sum of the buffer sizes. |
197 | * |
198 | * @li The completion_condition function object returns 0. |
199 | * |
200 | * This operation is implemented in terms of zero or more calls to the stream's |
201 | * write_some function. |
202 | * |
203 | * @param s The stream to which the data is to be written. The type must support |
204 | * the SyncWriteStream concept. |
205 | * |
206 | * @param buffers One or more buffers containing the data to be written. The sum |
207 | * of the buffer sizes indicates the maximum number of bytes to write to the |
208 | * stream. |
209 | * |
210 | * @param completion_condition The function object to be called to determine |
211 | * whether the write operation is complete. The signature of the function object |
212 | * must be: |
213 | * @code std::size_t completion_condition( |
214 | * // Result of latest write_some operation. |
215 | * const boost::system::error_code& error, |
216 | * |
217 | * // Number of bytes transferred so far. |
218 | * std::size_t bytes_transferred |
219 | * ); @endcode |
220 | * A return value of 0 indicates that the write operation is complete. A |
221 | * non-zero return value indicates the maximum number of bytes to be written on |
222 | * the next call to the stream's write_some function. |
223 | * |
224 | * @param ec Set to indicate what error occurred, if any. |
225 | * |
226 | * @returns The number of bytes written. If an error occurs, returns the total |
227 | * number of bytes successfully transferred prior to the error. |
228 | */ |
229 | template <typename SyncWriteStream, typename ConstBufferSequence, |
230 | typename CompletionCondition> |
231 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, |
232 | CompletionCondition completion_condition, boost::system::error_code& ec, |
233 | constraint_t< |
234 | is_const_buffer_sequence<ConstBufferSequence>::value |
235 | > = 0); |
236 | |
237 | #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
238 | |
239 | /// Write all of the supplied data to a stream before returning. |
240 | /** |
241 | * This function is used to write a certain number of bytes of data to a stream. |
242 | * The call will block until one of the following conditions is true: |
243 | * |
244 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
245 | * |
246 | * @li An error occurred. |
247 | * |
248 | * This operation is implemented in terms of zero or more calls to the stream's |
249 | * write_some function. |
250 | * |
251 | * @param s The stream to which the data is to be written. The type must support |
252 | * the SyncWriteStream concept. |
253 | * |
254 | * @param buffers The dynamic buffer sequence from which data will be written. |
255 | * Successfully written data is automatically consumed from the buffers. |
256 | * |
257 | * @returns The number of bytes transferred. |
258 | * |
259 | * @throws boost::system::system_error Thrown on failure. |
260 | * |
261 | * @note This overload is equivalent to calling: |
262 | * @code boost::asio::write( |
263 | * s, buffers, |
264 | * boost::asio::transfer_all()); @endcode |
265 | */ |
266 | template <typename SyncWriteStream, typename DynamicBuffer_v1> |
267 | std::size_t write(SyncWriteStream& s, |
268 | DynamicBuffer_v1&& buffers, |
269 | constraint_t< |
270 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
271 | > = 0, |
272 | constraint_t< |
273 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
274 | > = 0); |
275 | |
276 | /// Write all of the supplied data to a stream before returning. |
277 | /** |
278 | * This function is used to write a certain number of bytes of data to a stream. |
279 | * The call will block until one of the following conditions is true: |
280 | * |
281 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
282 | * |
283 | * @li An error occurred. |
284 | * |
285 | * This operation is implemented in terms of zero or more calls to the stream's |
286 | * write_some function. |
287 | * |
288 | * @param s The stream to which the data is to be written. The type must support |
289 | * the SyncWriteStream concept. |
290 | * |
291 | * @param buffers The dynamic buffer sequence from which data will be written. |
292 | * Successfully written data is automatically consumed from the buffers. |
293 | * |
294 | * @param ec Set to indicate what error occurred, if any. |
295 | * |
296 | * @returns The number of bytes transferred. |
297 | * |
298 | * @note This overload is equivalent to calling: |
299 | * @code boost::asio::write( |
300 | * s, buffers, |
301 | * boost::asio::transfer_all(), ec); @endcode |
302 | */ |
303 | template <typename SyncWriteStream, typename DynamicBuffer_v1> |
304 | std::size_t write(SyncWriteStream& s, |
305 | DynamicBuffer_v1&& buffers, |
306 | boost::system::error_code& ec, |
307 | constraint_t< |
308 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
309 | > = 0, |
310 | constraint_t< |
311 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
312 | > = 0); |
313 | |
314 | /// Write a certain amount of data to a stream before returning. |
315 | /** |
316 | * This function is used to write a certain number of bytes of data to a stream. |
317 | * The call will block until one of the following conditions is true: |
318 | * |
319 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
320 | * |
321 | * @li The completion_condition function object returns 0. |
322 | * |
323 | * This operation is implemented in terms of zero or more calls to the stream's |
324 | * write_some function. |
325 | * |
326 | * @param s The stream to which the data is to be written. The type must support |
327 | * the SyncWriteStream concept. |
328 | * |
329 | * @param buffers The dynamic buffer sequence from which data will be written. |
330 | * Successfully written data is automatically consumed from the buffers. |
331 | * |
332 | * @param completion_condition The function object to be called to determine |
333 | * whether the write operation is complete. The signature of the function object |
334 | * must be: |
335 | * @code std::size_t completion_condition( |
336 | * // Result of latest write_some 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 write operation is complete. A |
343 | * non-zero return value indicates the maximum number of bytes to be written on |
344 | * the next call to the stream's write_some function. |
345 | * |
346 | * @returns The number of bytes transferred. |
347 | * |
348 | * @throws boost::system::system_error Thrown on failure. |
349 | */ |
350 | template <typename SyncWriteStream, typename DynamicBuffer_v1, |
351 | typename CompletionCondition> |
352 | std::size_t write(SyncWriteStream& s, |
353 | DynamicBuffer_v1&& buffers, |
354 | CompletionCondition completion_condition, |
355 | constraint_t< |
356 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
357 | > = 0, |
358 | constraint_t< |
359 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
360 | > = 0); |
361 | |
362 | /// Write a certain amount of data to a stream before returning. |
363 | /** |
364 | * This function is used to write a certain number of bytes of data to a stream. |
365 | * The call will block until one of the following conditions is true: |
366 | * |
367 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
368 | * |
369 | * @li The completion_condition function object returns 0. |
370 | * |
371 | * This operation is implemented in terms of zero or more calls to the stream's |
372 | * write_some function. |
373 | * |
374 | * @param s The stream to which the data is to be written. The type must support |
375 | * the SyncWriteStream concept. |
376 | * |
377 | * @param buffers The dynamic buffer sequence from which data will be written. |
378 | * Successfully written data is automatically consumed from the buffers. |
379 | * |
380 | * @param completion_condition The function object to be called to determine |
381 | * whether the write operation is complete. The signature of the function object |
382 | * must be: |
383 | * @code std::size_t completion_condition( |
384 | * // Result of latest write_some operation. |
385 | * const boost::system::error_code& error, |
386 | * |
387 | * // Number of bytes transferred so far. |
388 | * std::size_t bytes_transferred |
389 | * ); @endcode |
390 | * A return value of 0 indicates that the write operation is complete. A |
391 | * non-zero return value indicates the maximum number of bytes to be written on |
392 | * the next call to the stream's write_some function. |
393 | * |
394 | * @param ec Set to indicate what error occurred, if any. |
395 | * |
396 | * @returns The number of bytes written. If an error occurs, returns the total |
397 | * number of bytes successfully transferred prior to the error. |
398 | */ |
399 | template <typename SyncWriteStream, typename DynamicBuffer_v1, |
400 | typename CompletionCondition> |
401 | std::size_t write(SyncWriteStream& s, |
402 | DynamicBuffer_v1&& buffers, |
403 | CompletionCondition completion_condition, boost::system::error_code& ec, |
404 | constraint_t< |
405 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
406 | > = 0, |
407 | constraint_t< |
408 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
409 | > = 0); |
410 | |
411 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
412 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
413 | |
414 | /// Write all of the supplied data to a stream before returning. |
415 | /** |
416 | * This function is used to write a certain number of bytes of data to a stream. |
417 | * The call will block until one of the following conditions is true: |
418 | * |
419 | * @li All of the data in the supplied basic_streambuf has been written. |
420 | * |
421 | * @li An error occurred. |
422 | * |
423 | * This operation is implemented in terms of zero or more calls to the stream's |
424 | * write_some function. |
425 | * |
426 | * @param s The stream to which the data is to be written. The type must support |
427 | * the SyncWriteStream concept. |
428 | * |
429 | * @param b The basic_streambuf object from which data will be written. |
430 | * |
431 | * @returns The number of bytes transferred. |
432 | * |
433 | * @throws boost::system::system_error Thrown on failure. |
434 | * |
435 | * @note This overload is equivalent to calling: |
436 | * @code boost::asio::write( |
437 | * s, b, |
438 | * boost::asio::transfer_all()); @endcode |
439 | */ |
440 | template <typename SyncWriteStream, typename Allocator> |
441 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b); |
442 | |
443 | /// Write all of the supplied data to a stream before returning. |
444 | /** |
445 | * This function is used to write a certain number of bytes of data to a stream. |
446 | * The call will block until one of the following conditions is true: |
447 | * |
448 | * @li All of the data in the supplied basic_streambuf has been written. |
449 | * |
450 | * @li An error occurred. |
451 | * |
452 | * This operation is implemented in terms of zero or more calls to the stream's |
453 | * write_some function. |
454 | * |
455 | * @param s The stream to which the data is to be written. The type must support |
456 | * the SyncWriteStream concept. |
457 | * |
458 | * @param b The basic_streambuf object from which data will be written. |
459 | * |
460 | * @param ec Set to indicate what error occurred, if any. |
461 | * |
462 | * @returns The number of bytes transferred. |
463 | * |
464 | * @note This overload is equivalent to calling: |
465 | * @code boost::asio::write( |
466 | * s, b, |
467 | * boost::asio::transfer_all(), ec); @endcode |
468 | */ |
469 | template <typename SyncWriteStream, typename Allocator> |
470 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, |
471 | boost::system::error_code& ec); |
472 | |
473 | /// Write a certain amount of data to a stream before returning. |
474 | /** |
475 | * This function is used to write a certain number of bytes of data to a stream. |
476 | * The call will block until one of the following conditions is true: |
477 | * |
478 | * @li All of the data in the supplied basic_streambuf has been written. |
479 | * |
480 | * @li The completion_condition function object returns 0. |
481 | * |
482 | * This operation is implemented in terms of zero or more calls to the stream's |
483 | * write_some function. |
484 | * |
485 | * @param s The stream to which the data is to be written. The type must support |
486 | * the SyncWriteStream concept. |
487 | * |
488 | * @param b The basic_streambuf object from which data will be written. |
489 | * |
490 | * @param completion_condition The function object to be called to determine |
491 | * whether the write operation is complete. The signature of the function object |
492 | * must be: |
493 | * @code std::size_t completion_condition( |
494 | * // Result of latest write_some operation. |
495 | * const boost::system::error_code& error, |
496 | * |
497 | * // Number of bytes transferred so far. |
498 | * std::size_t bytes_transferred |
499 | * ); @endcode |
500 | * A return value of 0 indicates that the write operation is complete. A |
501 | * non-zero return value indicates the maximum number of bytes to be written on |
502 | * the next call to the stream's write_some function. |
503 | * |
504 | * @returns The number of bytes transferred. |
505 | * |
506 | * @throws boost::system::system_error Thrown on failure. |
507 | */ |
508 | template <typename SyncWriteStream, typename Allocator, |
509 | typename CompletionCondition> |
510 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, |
511 | CompletionCondition completion_condition); |
512 | |
513 | /// Write a certain amount of data to a stream before returning. |
514 | /** |
515 | * This function is used to write a certain number of bytes of data to a stream. |
516 | * The call will block until one of the following conditions is true: |
517 | * |
518 | * @li All of the data in the supplied basic_streambuf has been written. |
519 | * |
520 | * @li The completion_condition function object returns 0. |
521 | * |
522 | * This operation is implemented in terms of zero or more calls to the stream's |
523 | * write_some function. |
524 | * |
525 | * @param s The stream to which the data is to be written. The type must support |
526 | * the SyncWriteStream concept. |
527 | * |
528 | * @param b The basic_streambuf object from which data will be written. |
529 | * |
530 | * @param completion_condition The function object to be called to determine |
531 | * whether the write operation is complete. The signature of the function object |
532 | * must be: |
533 | * @code std::size_t completion_condition( |
534 | * // Result of latest write_some operation. |
535 | * const boost::system::error_code& error, |
536 | * |
537 | * // Number of bytes transferred so far. |
538 | * std::size_t bytes_transferred |
539 | * ); @endcode |
540 | * A return value of 0 indicates that the write operation is complete. A |
541 | * non-zero return value indicates the maximum number of bytes to be written on |
542 | * the next call to the stream's write_some function. |
543 | * |
544 | * @param ec Set to indicate what error occurred, if any. |
545 | * |
546 | * @returns The number of bytes written. If an error occurs, returns the total |
547 | * number of bytes successfully transferred prior to the error. |
548 | */ |
549 | template <typename SyncWriteStream, typename Allocator, |
550 | typename CompletionCondition> |
551 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, |
552 | CompletionCondition completion_condition, boost::system::error_code& ec); |
553 | |
554 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) |
555 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
556 | #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
557 | |
558 | /// Write all of the supplied data to a stream before returning. |
559 | /** |
560 | * This function is used to write a certain number of bytes of data to a stream. |
561 | * The call will block until one of the following conditions is true: |
562 | * |
563 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
564 | * |
565 | * @li An error occurred. |
566 | * |
567 | * This operation is implemented in terms of zero or more calls to the stream's |
568 | * write_some function. |
569 | * |
570 | * @param s The stream to which the data is to be written. The type must support |
571 | * the SyncWriteStream concept. |
572 | * |
573 | * @param buffers The dynamic buffer sequence from which data will be written. |
574 | * Successfully written data is automatically consumed from the buffers. |
575 | * |
576 | * @returns The number of bytes transferred. |
577 | * |
578 | * @throws boost::system::system_error Thrown on failure. |
579 | * |
580 | * @note This overload is equivalent to calling: |
581 | * @code boost::asio::write( |
582 | * s, buffers, |
583 | * boost::asio::transfer_all()); @endcode |
584 | */ |
585 | template <typename SyncWriteStream, typename DynamicBuffer_v2> |
586 | std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, |
587 | constraint_t< |
588 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
589 | > = 0); |
590 | |
591 | /// Write all of the supplied data to a stream before returning. |
592 | /** |
593 | * This function is used to write a certain number of bytes of data to a stream. |
594 | * The call will block until one of the following conditions is true: |
595 | * |
596 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
597 | * |
598 | * @li An error occurred. |
599 | * |
600 | * This operation is implemented in terms of zero or more calls to the stream's |
601 | * write_some function. |
602 | * |
603 | * @param s The stream to which the data is to be written. The type must support |
604 | * the SyncWriteStream concept. |
605 | * |
606 | * @param buffers The dynamic buffer sequence from which data will be written. |
607 | * Successfully written data is automatically consumed from the buffers. |
608 | * |
609 | * @param ec Set to indicate what error occurred, if any. |
610 | * |
611 | * @returns The number of bytes transferred. |
612 | * |
613 | * @note This overload is equivalent to calling: |
614 | * @code boost::asio::write( |
615 | * s, buffers, |
616 | * boost::asio::transfer_all(), ec); @endcode |
617 | */ |
618 | template <typename SyncWriteStream, typename DynamicBuffer_v2> |
619 | std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, |
620 | boost::system::error_code& ec, |
621 | constraint_t< |
622 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
623 | > = 0); |
624 | |
625 | /// Write a certain amount of data to a stream before returning. |
626 | /** |
627 | * This function is used to write a certain number of bytes of data to a stream. |
628 | * The call will block until one of the following conditions is true: |
629 | * |
630 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
631 | * |
632 | * @li The completion_condition function object returns 0. |
633 | * |
634 | * This operation is implemented in terms of zero or more calls to the stream's |
635 | * write_some function. |
636 | * |
637 | * @param s The stream to which the data is to be written. The type must support |
638 | * the SyncWriteStream concept. |
639 | * |
640 | * @param buffers The dynamic buffer sequence from which data will be written. |
641 | * Successfully written data is automatically consumed from the buffers. |
642 | * |
643 | * @param completion_condition The function object to be called to determine |
644 | * whether the write operation is complete. The signature of the function object |
645 | * must be: |
646 | * @code std::size_t completion_condition( |
647 | * // Result of latest write_some operation. |
648 | * const boost::system::error_code& error, |
649 | * |
650 | * // Number of bytes transferred so far. |
651 | * std::size_t bytes_transferred |
652 | * ); @endcode |
653 | * A return value of 0 indicates that the write operation is complete. A |
654 | * non-zero return value indicates the maximum number of bytes to be written on |
655 | * the next call to the stream's write_some function. |
656 | * |
657 | * @returns The number of bytes transferred. |
658 | * |
659 | * @throws boost::system::system_error Thrown on failure. |
660 | */ |
661 | template <typename SyncWriteStream, typename DynamicBuffer_v2, |
662 | typename CompletionCondition> |
663 | std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, |
664 | CompletionCondition completion_condition, |
665 | constraint_t< |
666 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
667 | > = 0); |
668 | |
669 | /// Write a certain amount of data to a stream before returning. |
670 | /** |
671 | * This function is used to write a certain number of bytes of data to a stream. |
672 | * The call will block until one of the following conditions is true: |
673 | * |
674 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
675 | * |
676 | * @li The completion_condition function object returns 0. |
677 | * |
678 | * This operation is implemented in terms of zero or more calls to the stream's |
679 | * write_some function. |
680 | * |
681 | * @param s The stream to which the data is to be written. The type must support |
682 | * the SyncWriteStream concept. |
683 | * |
684 | * @param buffers The dynamic buffer sequence from which data will be written. |
685 | * Successfully written data is automatically consumed from the buffers. |
686 | * |
687 | * @param completion_condition The function object to be called to determine |
688 | * whether the write operation is complete. The signature of the function object |
689 | * must be: |
690 | * @code std::size_t completion_condition( |
691 | * // Result of latest write_some operation. |
692 | * const boost::system::error_code& error, |
693 | * |
694 | * // Number of bytes transferred so far. |
695 | * std::size_t bytes_transferred |
696 | * ); @endcode |
697 | * A return value of 0 indicates that the write operation is complete. A |
698 | * non-zero return value indicates the maximum number of bytes to be written on |
699 | * the next call to the stream's write_some function. |
700 | * |
701 | * @param ec Set to indicate what error occurred, if any. |
702 | * |
703 | * @returns The number of bytes written. If an error occurs, returns the total |
704 | * number of bytes successfully transferred prior to the error. |
705 | */ |
706 | template <typename SyncWriteStream, typename DynamicBuffer_v2, |
707 | typename CompletionCondition> |
708 | std::size_t write(SyncWriteStream& s, DynamicBuffer_v2 buffers, |
709 | CompletionCondition completion_condition, boost::system::error_code& ec, |
710 | constraint_t< |
711 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
712 | > = 0); |
713 | |
714 | /*@}*/ |
715 | /** |
716 | * @defgroup async_write boost::asio::async_write |
717 | * |
718 | * @brief The @c async_write function is a composed asynchronous operation that |
719 | * writes a certain amount of data to a stream before completion. |
720 | */ |
721 | /*@{*/ |
722 | |
723 | /// Start an asynchronous operation to write all of the supplied data to a |
724 | /// stream. |
725 | /** |
726 | * This function is used to asynchronously write a certain number of bytes of |
727 | * data to a stream. It is an initiating function for an @ref |
728 | * asynchronous_operation, and always returns immediately. The asynchronous |
729 | * operation will continue until one of the following conditions is true: |
730 | * |
731 | * @li All of the data in the supplied buffers has been written. That is, the |
732 | * bytes transferred is equal to the sum of the buffer sizes. |
733 | * |
734 | * @li An error occurred. |
735 | * |
736 | * This operation is implemented in terms of zero or more calls to the stream's |
737 | * async_write_some function, and is known as a <em>composed operation</em>. The |
738 | * program must ensure that the stream performs no other write operations (such |
739 | * as async_write, the stream's async_write_some function, or any other composed |
740 | * operations that perform writes) until this operation completes. |
741 | * |
742 | * @param s The stream to which the data is to be written. The type must support |
743 | * the AsyncWriteStream concept. |
744 | * |
745 | * @param buffers One or more buffers containing the data to be written. |
746 | * Although the buffers object may be copied as necessary, ownership of the |
747 | * underlying memory blocks is retained by the caller, which must guarantee |
748 | * that they remain valid until the completion handler is called. |
749 | * |
750 | * @param token The @ref completion_token that will be used to produce a |
751 | * completion handler, which will be called when the write completes. |
752 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
753 | * @ref yield_context, or a function object with the correct completion |
754 | * signature. The function signature of the completion handler must be: |
755 | * @code void handler( |
756 | * // Result of operation. |
757 | * const boost::system::error_code& error, |
758 | * |
759 | * // Number of bytes written from the buffers. If an error |
760 | * // occurred, this will be less than the sum of the buffer sizes. |
761 | * std::size_t bytes_transferred |
762 | * ); @endcode |
763 | * Regardless of whether the asynchronous operation completes immediately or |
764 | * not, the completion handler will not be invoked from within this function. |
765 | * On immediate completion, invocation of the handler will be performed in a |
766 | * manner equivalent to using boost::asio::post(). |
767 | * |
768 | * @par Completion Signature |
769 | * @code void(boost::system::error_code, std::size_t) @endcode |
770 | * |
771 | * @par Example |
772 | * To write a single data buffer use the @ref buffer function as follows: |
773 | * @code |
774 | * boost::asio::async_write(s, boost::asio::buffer(data, size), handler); |
775 | * @endcode |
776 | * See the @ref buffer documentation for information on writing multiple |
777 | * buffers in one go, and how to use it with arrays, boost::array or |
778 | * std::vector. |
779 | * |
780 | * @par Per-Operation Cancellation |
781 | * This asynchronous operation supports cancellation for the following |
782 | * boost::asio::cancellation_type values: |
783 | * |
784 | * @li @c cancellation_type::terminal |
785 | * |
786 | * @li @c cancellation_type::partial |
787 | * |
788 | * if they are also supported by the @c AsyncWriteStream type's |
789 | * @c async_write_some operation. |
790 | */ |
791 | template <typename AsyncWriteStream, typename ConstBufferSequence, |
792 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
793 | std::size_t)) WriteToken |
794 | = default_completion_token_t<typename AsyncWriteStream::executor_type>> |
795 | auto async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, |
796 | WriteToken&& token |
797 | = default_completion_token_t<typename AsyncWriteStream::executor_type>(), |
798 | constraint_t< |
799 | is_const_buffer_sequence<ConstBufferSequence>::value |
800 | > = 0) |
801 | -> decltype( |
802 | async_initiate<WriteToken, |
803 | void (boost::system::error_code, std::size_t)>( |
804 | declval<detail::initiate_async_write<AsyncWriteStream>>(), |
805 | token, buffers, transfer_all())); |
806 | |
807 | /// Start an asynchronous operation to write a certain amount of data to a |
808 | /// stream. |
809 | /** |
810 | * This function is used to asynchronously write a certain number of bytes of |
811 | * data to a stream. It is an initiating function for an @ref |
812 | * asynchronous_operation, and always returns immediately. The asynchronous |
813 | * operation will continue until one of the following conditions is true: |
814 | * |
815 | * @li All of the data in the supplied buffers has been written. That is, the |
816 | * bytes transferred is equal to the sum of the buffer sizes. |
817 | * |
818 | * @li The completion_condition function object returns 0. |
819 | * |
820 | * This operation is implemented in terms of zero or more calls to the stream's |
821 | * async_write_some function, and is known as a <em>composed operation</em>. The |
822 | * program must ensure that the stream performs no other write operations (such |
823 | * as async_write, the stream's async_write_some function, or any other composed |
824 | * operations that perform writes) until this operation completes. |
825 | * |
826 | * @param s The stream to which the data is to be written. The type must support |
827 | * the AsyncWriteStream concept. |
828 | * |
829 | * @param buffers One or more buffers containing the data to be written. |
830 | * Although the buffers object may be copied as necessary, ownership of the |
831 | * underlying memory blocks is retained by the caller, which must guarantee |
832 | * that they remain valid until the completion handler is called. |
833 | * |
834 | * @param completion_condition The function object to be called to determine |
835 | * whether the write operation is complete. The signature of the function object |
836 | * must be: |
837 | * @code std::size_t completion_condition( |
838 | * // Result of latest async_write_some operation. |
839 | * const boost::system::error_code& error, |
840 | * |
841 | * // Number of bytes transferred so far. |
842 | * std::size_t bytes_transferred |
843 | * ); @endcode |
844 | * A return value of 0 indicates that the write operation is complete. A |
845 | * non-zero return value indicates the maximum number of bytes to be written on |
846 | * the next call to the stream's async_write_some function. |
847 | * |
848 | * @param token The @ref completion_token that will be used to produce a |
849 | * completion handler, which will be called when the write completes. |
850 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
851 | * @ref yield_context, or a function object with the correct completion |
852 | * signature. The function signature of the completion handler must be: |
853 | * @code void handler( |
854 | * // Result of operation. |
855 | * const boost::system::error_code& error, |
856 | * |
857 | * // Number of bytes written from the buffers. If an error |
858 | * // occurred, this will be less than the sum of the buffer sizes. |
859 | * std::size_t bytes_transferred |
860 | * ); @endcode |
861 | * Regardless of whether the asynchronous operation completes immediately or |
862 | * not, the completion handler will not be invoked from within this function. |
863 | * On immediate completion, invocation of the handler will be performed in a |
864 | * manner equivalent to using boost::asio::post(). |
865 | * |
866 | * @par Completion Signature |
867 | * @code void(boost::system::error_code, std::size_t) @endcode |
868 | * |
869 | * @par Example |
870 | * To write a single data buffer use the @ref buffer function as follows: |
871 | * @code boost::asio::async_write(s, |
872 | * boost::asio::buffer(data, size), |
873 | * boost::asio::transfer_at_least(32), |
874 | * handler); @endcode |
875 | * See the @ref buffer documentation for information on writing multiple |
876 | * buffers in one go, and how to use it with arrays, boost::array or |
877 | * std::vector. |
878 | * |
879 | * @par Per-Operation Cancellation |
880 | * This asynchronous operation supports cancellation for the following |
881 | * boost::asio::cancellation_type values: |
882 | * |
883 | * @li @c cancellation_type::terminal |
884 | * |
885 | * @li @c cancellation_type::partial |
886 | * |
887 | * if they are also supported by the @c AsyncWriteStream type's |
888 | * @c async_write_some operation. |
889 | */ |
890 | template <typename AsyncWriteStream, |
891 | typename ConstBufferSequence, typename CompletionCondition, |
892 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
893 | std::size_t)) WriteToken> |
894 | auto async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, |
895 | CompletionCondition completion_condition, |
896 | WriteToken&& token, |
897 | constraint_t< |
898 | is_const_buffer_sequence<ConstBufferSequence>::value |
899 | > = 0) |
900 | -> decltype( |
901 | async_initiate<WriteToken, |
902 | void (boost::system::error_code, std::size_t)>( |
903 | declval<detail::initiate_async_write<AsyncWriteStream>>(), |
904 | token, buffers, |
905 | static_cast<CompletionCondition&&>(completion_condition))); |
906 | |
907 | #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
908 | |
909 | /// Start an asynchronous operation to write all of the supplied data to a |
910 | /// stream. |
911 | /** |
912 | * This function is used to asynchronously write a certain number of bytes of |
913 | * data to a stream. It is an initiating function for an @ref |
914 | * asynchronous_operation, and always returns immediately. The asynchronous |
915 | * operation will continue until one of the following conditions is true: |
916 | * |
917 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
918 | * |
919 | * @li An error occurred. |
920 | * |
921 | * This operation is implemented in terms of zero or more calls to the stream's |
922 | * async_write_some function, and is known as a <em>composed operation</em>. The |
923 | * program must ensure that the stream performs no other write operations (such |
924 | * as async_write, the stream's async_write_some function, or any other composed |
925 | * operations that perform writes) until this operation completes. |
926 | * |
927 | * @param s The stream to which the data is to be written. The type must support |
928 | * the AsyncWriteStream concept. |
929 | * |
930 | * @param buffers The dynamic buffer sequence from which data will be written. |
931 | * Although the buffers object may be copied as necessary, ownership of the |
932 | * underlying memory blocks is retained by the caller, which must guarantee |
933 | * that they remain valid until the completion handler is called. Successfully |
934 | * written data is automatically consumed from the buffers. |
935 | * |
936 | * @param token The @ref completion_token that will be used to produce a |
937 | * completion handler, which will be called when the write completes. |
938 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
939 | * @ref yield_context, or a function object with the correct completion |
940 | * signature. The function signature of the completion handler must be: |
941 | * @code void handler( |
942 | * // Result of operation. |
943 | * const boost::system::error_code& error, |
944 | * |
945 | * // Number of bytes written from the buffers. If an error |
946 | * // occurred, this will be less than the sum of the buffer sizes. |
947 | * std::size_t bytes_transferred |
948 | * ); @endcode |
949 | * Regardless of whether the asynchronous operation completes immediately or |
950 | * not, the completion handler will not be invoked from within this function. |
951 | * On immediate completion, invocation of the handler will be performed in a |
952 | * manner equivalent to using boost::asio::post(). |
953 | * |
954 | * @par Completion Signature |
955 | * @code void(boost::system::error_code, std::size_t) @endcode |
956 | * |
957 | * @par Per-Operation Cancellation |
958 | * This asynchronous operation supports cancellation for the following |
959 | * boost::asio::cancellation_type values: |
960 | * |
961 | * @li @c cancellation_type::terminal |
962 | * |
963 | * @li @c cancellation_type::partial |
964 | * |
965 | * if they are also supported by the @c AsyncWriteStream type's |
966 | * @c async_write_some operation. |
967 | */ |
968 | template <typename AsyncWriteStream, typename DynamicBuffer_v1, |
969 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
970 | std::size_t)) WriteToken |
971 | = default_completion_token_t<typename AsyncWriteStream::executor_type>> |
972 | auto async_write(AsyncWriteStream& s, DynamicBuffer_v1&& buffers, |
973 | WriteToken&& token |
974 | = default_completion_token_t<typename AsyncWriteStream::executor_type>(), |
975 | constraint_t< |
976 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
977 | > = 0, |
978 | constraint_t< |
979 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
980 | > = 0) |
981 | -> decltype( |
982 | async_initiate<WriteToken, |
983 | void (boost::system::error_code, std::size_t)>( |
984 | declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(), |
985 | token, static_cast<DynamicBuffer_v1&&>(buffers), |
986 | transfer_all())); |
987 | |
988 | /// Start an asynchronous operation to write a certain amount of data to a |
989 | /// stream. |
990 | /** |
991 | * This function is used to asynchronously write a certain number of bytes of |
992 | * data to a stream. It is an initiating function for an @ref |
993 | * asynchronous_operation, and always returns immediately. The asynchronous |
994 | * operation will continue until one of the following conditions is true: |
995 | * |
996 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
997 | * |
998 | * @li The completion_condition function object returns 0. |
999 | * |
1000 | * This operation is implemented in terms of zero or more calls to the stream's |
1001 | * async_write_some function, and is known as a <em>composed operation</em>. The |
1002 | * program must ensure that the stream performs no other write operations (such |
1003 | * as async_write, the stream's async_write_some function, or any other composed |
1004 | * operations that perform writes) until this operation completes. |
1005 | * |
1006 | * @param s The stream to which the data is to be written. The type must support |
1007 | * the AsyncWriteStream concept. |
1008 | * |
1009 | * @param buffers The dynamic buffer sequence from which data will be written. |
1010 | * Although the buffers object may be copied as necessary, ownership of the |
1011 | * underlying memory blocks is retained by the caller, which must guarantee |
1012 | * that they remain valid until the completion handler is called. Successfully |
1013 | * written data is automatically consumed from the buffers. |
1014 | * |
1015 | * @param completion_condition The function object to be called to determine |
1016 | * whether the write operation is complete. The signature of the function object |
1017 | * must be: |
1018 | * @code std::size_t completion_condition( |
1019 | * // Result of latest async_write_some operation. |
1020 | * const boost::system::error_code& error, |
1021 | * |
1022 | * // Number of bytes transferred so far. |
1023 | * std::size_t bytes_transferred |
1024 | * ); @endcode |
1025 | * A return value of 0 indicates that the write operation is complete. A |
1026 | * non-zero return value indicates the maximum number of bytes to be written on |
1027 | * the next call to the stream's async_write_some function. |
1028 | * |
1029 | * @param token The @ref completion_token that will be used to produce a |
1030 | * completion handler, which will be called when the write completes. |
1031 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
1032 | * @ref yield_context, or a function object with the correct completion |
1033 | * signature. The function signature of the completion handler must be: |
1034 | * @code void handler( |
1035 | * // Result of operation. |
1036 | * const boost::system::error_code& error, |
1037 | * |
1038 | * // Number of bytes written from the buffers. If an error |
1039 | * // occurred, this will be less than the sum of the buffer sizes. |
1040 | * std::size_t bytes_transferred |
1041 | * ); @endcode |
1042 | * Regardless of whether the asynchronous operation completes immediately or |
1043 | * not, the completion handler will not be invoked from within this function. |
1044 | * On immediate completion, invocation of the handler will be performed in a |
1045 | * manner equivalent to using boost::asio::post(). |
1046 | * |
1047 | * @par Completion Signature |
1048 | * @code void(boost::system::error_code, std::size_t) @endcode |
1049 | * |
1050 | * @par Per-Operation Cancellation |
1051 | * This asynchronous operation supports cancellation for the following |
1052 | * boost::asio::cancellation_type values: |
1053 | * |
1054 | * @li @c cancellation_type::terminal |
1055 | * |
1056 | * @li @c cancellation_type::partial |
1057 | * |
1058 | * if they are also supported by the @c AsyncWriteStream type's |
1059 | * @c async_write_some operation. |
1060 | */ |
1061 | template <typename AsyncWriteStream, |
1062 | typename DynamicBuffer_v1, typename CompletionCondition, |
1063 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
1064 | std::size_t)) WriteToken> |
1065 | auto async_write(AsyncWriteStream& s, DynamicBuffer_v1&& buffers, |
1066 | CompletionCondition completion_condition, WriteToken&& token, |
1067 | constraint_t< |
1068 | is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value |
1069 | > = 0, |
1070 | constraint_t< |
1071 | !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value |
1072 | > = 0) |
1073 | -> decltype( |
1074 | async_initiate<WriteToken, |
1075 | void (boost::system::error_code, std::size_t)>( |
1076 | declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(), |
1077 | token, static_cast<DynamicBuffer_v1&&>(buffers), |
1078 | static_cast<CompletionCondition&&>(completion_condition))); |
1079 | |
1080 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
1081 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
1082 | |
1083 | /// Start an asynchronous operation to write all of the supplied data to a |
1084 | /// stream. |
1085 | /** |
1086 | * This function is used to asynchronously write a certain number of bytes of |
1087 | * data to a stream. It is an initiating function for an @ref |
1088 | * asynchronous_operation, and always returns immediately. The asynchronous |
1089 | * operation will continue until one of the following conditions is true: |
1090 | * |
1091 | * @li All of the data in the supplied basic_streambuf has been written. |
1092 | * |
1093 | * @li An error occurred. |
1094 | * |
1095 | * This operation is implemented in terms of zero or more calls to the stream's |
1096 | * async_write_some function, and is known as a <em>composed operation</em>. The |
1097 | * program must ensure that the stream performs no other write operations (such |
1098 | * as async_write, the stream's async_write_some function, or any other composed |
1099 | * operations that perform writes) until this operation completes. |
1100 | * |
1101 | * @param s The stream to which the data is to be written. The type must support |
1102 | * the AsyncWriteStream concept. |
1103 | * |
1104 | * @param b A basic_streambuf object from which data will be written. Ownership |
1105 | * of the streambuf is retained by the caller, which must guarantee that it |
1106 | * remains valid until the completion handler is called. |
1107 | * |
1108 | * @param token The @ref completion_token that will be used to produce a |
1109 | * completion handler, which will be called when the write completes. |
1110 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
1111 | * @ref yield_context, or a function object with the correct completion |
1112 | * signature. The function signature of the completion handler must be: |
1113 | * @code void handler( |
1114 | * // Result of operation. |
1115 | * const boost::system::error_code& error, |
1116 | * |
1117 | * // Number of bytes written from the buffers. If an error |
1118 | * // occurred, this will be less than the sum of the buffer sizes. |
1119 | * std::size_t bytes_transferred |
1120 | * ); @endcode |
1121 | * Regardless of whether the asynchronous operation completes immediately or |
1122 | * not, the completion handler will not be invoked from within this function. |
1123 | * On immediate completion, invocation of the handler will be performed in a |
1124 | * manner equivalent to using boost::asio::post(). |
1125 | * |
1126 | * @par Completion Signature |
1127 | * @code void(boost::system::error_code, std::size_t) @endcode |
1128 | * |
1129 | * @par Per-Operation Cancellation |
1130 | * This asynchronous operation supports cancellation for the following |
1131 | * boost::asio::cancellation_type values: |
1132 | * |
1133 | * @li @c cancellation_type::terminal |
1134 | * |
1135 | * @li @c cancellation_type::partial |
1136 | * |
1137 | * if they are also supported by the @c AsyncWriteStream type's |
1138 | * @c async_write_some operation. |
1139 | */ |
1140 | template <typename AsyncWriteStream, typename Allocator, |
1141 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
1142 | std::size_t)) WriteToken |
1143 | = default_completion_token_t<typename AsyncWriteStream::executor_type>> |
1144 | auto async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b, |
1145 | WriteToken&& token |
1146 | = default_completion_token_t<typename AsyncWriteStream::executor_type>()) |
1147 | -> decltype( |
1148 | async_initiate<WriteToken, |
1149 | void (boost::system::error_code, std::size_t)>( |
1150 | declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(), |
1151 | token, basic_streambuf_ref<Allocator>(b), transfer_all())); |
1152 | |
1153 | /// Start an asynchronous operation to write a certain amount of data to a |
1154 | /// stream. |
1155 | /** |
1156 | * This function is used to asynchronously write a certain number of bytes of |
1157 | * data to a stream. It is an initiating function for an @ref |
1158 | * asynchronous_operation, and always returns immediately. The asynchronous |
1159 | * operation will continue until one of the following conditions is true: |
1160 | * |
1161 | * @li All of the data in the supplied basic_streambuf has been written. |
1162 | * |
1163 | * @li The completion_condition function object returns 0. |
1164 | * |
1165 | * This operation is implemented in terms of zero or more calls to the stream's |
1166 | * async_write_some function, and is known as a <em>composed operation</em>. The |
1167 | * program must ensure that the stream performs no other write operations (such |
1168 | * as async_write, the stream's async_write_some function, or any other composed |
1169 | * operations that perform writes) until this operation completes. |
1170 | * |
1171 | * @param s The stream to which the data is to be written. The type must support |
1172 | * the AsyncWriteStream concept. |
1173 | * |
1174 | * @param b A basic_streambuf object from which data will be written. Ownership |
1175 | * of the streambuf is retained by the caller, which must guarantee that it |
1176 | * remains valid until the completion handler is called. |
1177 | * |
1178 | * @param completion_condition The function object to be called to determine |
1179 | * whether the write operation is complete. The signature of the function object |
1180 | * must be: |
1181 | * @code std::size_t completion_condition( |
1182 | * // Result of latest async_write_some operation. |
1183 | * const boost::system::error_code& error, |
1184 | * |
1185 | * // Number of bytes transferred so far. |
1186 | * std::size_t bytes_transferred |
1187 | * ); @endcode |
1188 | * A return value of 0 indicates that the write operation is complete. A |
1189 | * non-zero return value indicates the maximum number of bytes to be written on |
1190 | * the next call to the stream's async_write_some function. |
1191 | * |
1192 | * @param token The @ref completion_token that will be used to produce a |
1193 | * completion handler, which will be called when the write completes. |
1194 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
1195 | * @ref yield_context, or a function object with the correct completion |
1196 | * signature. The function signature of the completion handler must be: |
1197 | * @code void handler( |
1198 | * // Result of operation. |
1199 | * const boost::system::error_code& error, |
1200 | * |
1201 | * // Number of bytes written from the buffers. If an error |
1202 | * // occurred, this will be less than the sum of the buffer sizes. |
1203 | * std::size_t bytes_transferred |
1204 | * ); @endcode |
1205 | * Regardless of whether the asynchronous operation completes immediately or |
1206 | * not, the completion handler will not be invoked from within this function. |
1207 | * On immediate completion, invocation of the handler will be performed in a |
1208 | * manner equivalent to using boost::asio::post(). |
1209 | * |
1210 | * @par Completion Signature |
1211 | * @code void(boost::system::error_code, std::size_t) @endcode |
1212 | * |
1213 | * @par Per-Operation Cancellation |
1214 | * This asynchronous operation supports cancellation for the following |
1215 | * boost::asio::cancellation_type values: |
1216 | * |
1217 | * @li @c cancellation_type::terminal |
1218 | * |
1219 | * @li @c cancellation_type::partial |
1220 | * |
1221 | * if they are also supported by the @c AsyncWriteStream type's |
1222 | * @c async_write_some operation. |
1223 | */ |
1224 | template <typename AsyncWriteStream, |
1225 | typename Allocator, typename CompletionCondition, |
1226 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
1227 | std::size_t)) WriteToken> |
1228 | auto async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b, |
1229 | CompletionCondition completion_condition, WriteToken&& token) |
1230 | -> decltype( |
1231 | async_initiate<WriteToken, |
1232 | void (boost::system::error_code, std::size_t)>( |
1233 | declval<detail::initiate_async_write_dynbuf_v1<AsyncWriteStream>>(), |
1234 | token, basic_streambuf_ref<Allocator>(b), |
1235 | static_cast<CompletionCondition&&>(completion_condition))); |
1236 | |
1237 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) |
1238 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
1239 | #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1) |
1240 | |
1241 | /// Start an asynchronous operation to write all of the supplied data to a |
1242 | /// stream. |
1243 | /** |
1244 | * This function is used to asynchronously write a certain number of bytes of |
1245 | * data to a stream. It is an initiating function for an @ref |
1246 | * asynchronous_operation, and always returns immediately. The asynchronous |
1247 | * operation will continue until one of the following conditions is true: |
1248 | * |
1249 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
1250 | * |
1251 | * @li An error occurred. |
1252 | * |
1253 | * This operation is implemented in terms of zero or more calls to the stream's |
1254 | * async_write_some function, and is known as a <em>composed operation</em>. The |
1255 | * program must ensure that the stream performs no other write operations (such |
1256 | * as async_write, the stream's async_write_some function, or any other composed |
1257 | * operations that perform writes) until this operation completes. |
1258 | * |
1259 | * @param s The stream to which the data is to be written. The type must support |
1260 | * the AsyncWriteStream concept. |
1261 | * |
1262 | * @param buffers The dynamic buffer sequence from which data will be written. |
1263 | * Although the buffers object may be copied as necessary, ownership of the |
1264 | * underlying memory blocks is retained by the caller, which must guarantee |
1265 | * that they remain valid until the completion handler is called. Successfully |
1266 | * written data is automatically consumed from the buffers. |
1267 | * |
1268 | * @param token The @ref completion_token that will be used to produce a |
1269 | * completion handler, which will be called when the write completes. |
1270 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
1271 | * @ref yield_context, or a function object with the correct completion |
1272 | * signature. The function signature of the completion handler must be: |
1273 | * @code void handler( |
1274 | * // Result of operation. |
1275 | * const boost::system::error_code& error, |
1276 | * |
1277 | * // Number of bytes written from the buffers. If an error |
1278 | * // occurred, this will be less than the sum of the buffer sizes. |
1279 | * std::size_t bytes_transferred |
1280 | * ); @endcode |
1281 | * Regardless of whether the asynchronous operation completes immediately or |
1282 | * not, the completion handler will not be invoked from within this function. |
1283 | * On immediate completion, invocation of the handler will be performed in a |
1284 | * manner equivalent to using boost::asio::post(). |
1285 | * |
1286 | * @par Completion Signature |
1287 | * @code void(boost::system::error_code, std::size_t) @endcode |
1288 | * |
1289 | * @par Per-Operation Cancellation |
1290 | * This asynchronous operation supports cancellation for the following |
1291 | * boost::asio::cancellation_type values: |
1292 | * |
1293 | * @li @c cancellation_type::terminal |
1294 | * |
1295 | * @li @c cancellation_type::partial |
1296 | * |
1297 | * if they are also supported by the @c AsyncWriteStream type's |
1298 | * @c async_write_some operation. |
1299 | */ |
1300 | template <typename AsyncWriteStream, typename DynamicBuffer_v2, |
1301 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
1302 | std::size_t)) WriteToken |
1303 | = default_completion_token_t<typename AsyncWriteStream::executor_type>> |
1304 | auto async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, |
1305 | WriteToken&& token |
1306 | = default_completion_token_t<typename AsyncWriteStream::executor_type>(), |
1307 | constraint_t< |
1308 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
1309 | > = 0) |
1310 | -> decltype( |
1311 | async_initiate<WriteToken, |
1312 | void (boost::system::error_code, std::size_t)>( |
1313 | declval<detail::initiate_async_write_dynbuf_v2<AsyncWriteStream>>(), |
1314 | token, static_cast<DynamicBuffer_v2&&>(buffers), |
1315 | transfer_all())); |
1316 | |
1317 | /// Start an asynchronous operation to write a certain amount of data to a |
1318 | /// stream. |
1319 | /** |
1320 | * This function is used to asynchronously write a certain number of bytes of |
1321 | * data to a stream. It is an initiating function for an @ref |
1322 | * asynchronous_operation, and always returns immediately. The asynchronous |
1323 | * operation will continue until one of the following conditions is true: |
1324 | * |
1325 | * @li All of the data in the supplied dynamic buffer sequence has been written. |
1326 | * |
1327 | * @li The completion_condition function object returns 0. |
1328 | * |
1329 | * This operation is implemented in terms of zero or more calls to the stream's |
1330 | * async_write_some function, and is known as a <em>composed operation</em>. The |
1331 | * program must ensure that the stream performs no other write operations (such |
1332 | * as async_write, the stream's async_write_some function, or any other composed |
1333 | * operations that perform writes) until this operation completes. |
1334 | * |
1335 | * @param s The stream to which the data is to be written. The type must support |
1336 | * the AsyncWriteStream concept. |
1337 | * |
1338 | * @param buffers The dynamic buffer sequence from which data will be written. |
1339 | * Although the buffers object may be copied as necessary, ownership of the |
1340 | * underlying memory blocks is retained by the caller, which must guarantee |
1341 | * that they remain valid until the completion handler is called. Successfully |
1342 | * written data is automatically consumed from the buffers. |
1343 | * |
1344 | * @param completion_condition The function object to be called to determine |
1345 | * whether the write operation is complete. The signature of the function object |
1346 | * must be: |
1347 | * @code std::size_t completion_condition( |
1348 | * // Result of latest async_write_some operation. |
1349 | * const boost::system::error_code& error, |
1350 | * |
1351 | * // Number of bytes transferred so far. |
1352 | * std::size_t bytes_transferred |
1353 | * ); @endcode |
1354 | * A return value of 0 indicates that the write operation is complete. A |
1355 | * non-zero return value indicates the maximum number of bytes to be written on |
1356 | * the next call to the stream's async_write_some function. |
1357 | * |
1358 | * @param token The @ref completion_token that will be used to produce a |
1359 | * completion handler, which will be called when the write completes. |
1360 | * Potential completion tokens include @ref use_future, @ref use_awaitable, |
1361 | * @ref yield_context, or a function object with the correct completion |
1362 | * signature. The function signature of the completion handler must be: |
1363 | * @code void handler( |
1364 | * // Result of operation. |
1365 | * const boost::system::error_code& error, |
1366 | * |
1367 | * // Number of bytes written from the buffers. If an error |
1368 | * // occurred, this will be less than the sum of the buffer sizes. |
1369 | * std::size_t bytes_transferred |
1370 | * ); @endcode |
1371 | * Regardless of whether the asynchronous operation completes immediately or |
1372 | * not, the completion handler will not be invoked from within this function. |
1373 | * On immediate completion, invocation of the handler will be performed in a |
1374 | * manner equivalent to using boost::asio::post(). |
1375 | * |
1376 | * @par Completion Signature |
1377 | * @code void(boost::system::error_code, std::size_t) @endcode |
1378 | * |
1379 | * @par Per-Operation Cancellation |
1380 | * This asynchronous operation supports cancellation for the following |
1381 | * boost::asio::cancellation_type values: |
1382 | * |
1383 | * @li @c cancellation_type::terminal |
1384 | * |
1385 | * @li @c cancellation_type::partial |
1386 | * |
1387 | * if they are also supported by the @c AsyncWriteStream type's |
1388 | * @c async_write_some operation. |
1389 | */ |
1390 | template <typename AsyncWriteStream, |
1391 | typename DynamicBuffer_v2, typename CompletionCondition, |
1392 | BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, |
1393 | std::size_t)) WriteToken> |
1394 | auto async_write(AsyncWriteStream& s, DynamicBuffer_v2 buffers, |
1395 | CompletionCondition completion_condition, |
1396 | WriteToken&& token, |
1397 | constraint_t< |
1398 | is_dynamic_buffer_v2<DynamicBuffer_v2>::value |
1399 | > = 0) |
1400 | -> decltype( |
1401 | async_initiate<WriteToken, |
1402 | void (boost::system::error_code, std::size_t)>( |
1403 | declval<detail::initiate_async_write_dynbuf_v2<AsyncWriteStream>>(), |
1404 | token, static_cast<DynamicBuffer_v2&&>(buffers), |
1405 | static_cast<CompletionCondition&&>(completion_condition))); |
1406 | |
1407 | /*@}*/ |
1408 | |
1409 | } // namespace asio |
1410 | } // namespace boost |
1411 | |
1412 | #include <boost/asio/detail/pop_options.hpp> |
1413 | |
1414 | #include <boost/asio/impl/write.hpp> |
1415 | |
1416 | #endif // BOOST_ASIO_WRITE_HPP |
1417 | |