]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // write.hpp | |
3 | // ~~~~~~~~~ | |
4 | // | |
b32b8144 | 5 | // Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
7c673cae FG |
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> | |
b32b8144 | 21 | #include <boost/asio/buffer.hpp> |
7c673cae FG |
22 | #include <boost/asio/error.hpp> |
23 | ||
b32b8144 FG |
24 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
25 | # include <boost/asio/basic_streambuf_fwd.hpp> | |
26 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) | |
27 | ||
7c673cae FG |
28 | #include <boost/asio/detail/push_options.hpp> |
29 | ||
30 | namespace boost { | |
31 | namespace asio { | |
32 | ||
33 | /** | |
34 | * @defgroup write boost::asio::write | |
35 | * | |
36 | * @brief Write a certain amount of data to a stream before returning. | |
37 | */ | |
38 | /*@{*/ | |
39 | ||
40 | /// Write all of the supplied data to a stream before returning. | |
41 | /** | |
42 | * This function is used to write a certain number of bytes of data to a stream. | |
43 | * The call will block until one of the following conditions is true: | |
44 | * | |
45 | * @li All of the data in the supplied buffers has been written. That is, the | |
46 | * bytes transferred is equal to the sum of the buffer sizes. | |
47 | * | |
48 | * @li An error occurred. | |
49 | * | |
50 | * This operation is implemented in terms of zero or more calls to the stream's | |
51 | * write_some function. | |
52 | * | |
53 | * @param s The stream to which the data is to be written. The type must support | |
54 | * the SyncWriteStream concept. | |
55 | * | |
56 | * @param buffers One or more buffers containing the data to be written. The sum | |
57 | * of the buffer sizes indicates the maximum number of bytes to write to the | |
58 | * stream. | |
59 | * | |
60 | * @returns The number of bytes transferred. | |
61 | * | |
62 | * @throws boost::system::system_error Thrown on failure. | |
63 | * | |
64 | * @par Example | |
65 | * To write a single data buffer use the @ref buffer function as follows: | |
66 | * @code boost::asio::write(s, boost::asio::buffer(data, size)); @endcode | |
67 | * See the @ref buffer documentation for information on writing multiple | |
68 | * buffers in one go, and how to use it with arrays, boost::array or | |
69 | * std::vector. | |
70 | * | |
71 | * @note This overload is equivalent to calling: | |
72 | * @code boost::asio::write( | |
73 | * s, buffers, | |
74 | * boost::asio::transfer_all()); @endcode | |
75 | */ | |
76 | template <typename SyncWriteStream, typename ConstBufferSequence> | |
b32b8144 FG |
77 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, |
78 | typename enable_if< | |
79 | is_const_buffer_sequence<ConstBufferSequence>::value | |
80 | >::type* = 0); | |
7c673cae FG |
81 | |
82 | /// Write all of the supplied data to a stream before returning. | |
83 | /** | |
84 | * This function is used to write a certain number of bytes of data to a stream. | |
85 | * The call will block until one of the following conditions is true: | |
86 | * | |
87 | * @li All of the data in the supplied buffers has been written. That is, the | |
88 | * bytes transferred is equal to the sum of the buffer sizes. | |
89 | * | |
90 | * @li An error occurred. | |
91 | * | |
92 | * This operation is implemented in terms of zero or more calls to the stream's | |
93 | * write_some function. | |
94 | * | |
95 | * @param s The stream to which the data is to be written. The type must support | |
96 | * the SyncWriteStream concept. | |
97 | * | |
98 | * @param buffers One or more buffers containing the data to be written. The sum | |
99 | * of the buffer sizes indicates the maximum number of bytes to write to the | |
100 | * stream. | |
101 | * | |
102 | * @param ec Set to indicate what error occurred, if any. | |
103 | * | |
104 | * @returns The number of bytes transferred. | |
105 | * | |
106 | * @par Example | |
107 | * To write a single data buffer use the @ref buffer function as follows: | |
108 | * @code boost::asio::write(s, boost::asio::buffer(data, size), ec); @endcode | |
109 | * See the @ref buffer documentation for information on writing multiple | |
110 | * buffers in one go, and how to use it with arrays, boost::array or | |
111 | * std::vector. | |
112 | * | |
113 | * @note This overload is equivalent to calling: | |
114 | * @code boost::asio::write( | |
115 | * s, buffers, | |
116 | * boost::asio::transfer_all(), ec); @endcode | |
117 | */ | |
118 | template <typename SyncWriteStream, typename ConstBufferSequence> | |
119 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, | |
b32b8144 FG |
120 | boost::system::error_code& ec, |
121 | typename enable_if< | |
122 | is_const_buffer_sequence<ConstBufferSequence>::value | |
123 | >::type* = 0); | |
7c673cae FG |
124 | |
125 | /// Write a certain amount of data to a stream before returning. | |
126 | /** | |
127 | * This function is used to write a certain number of bytes of data to a stream. | |
128 | * The call will block until one of the following conditions is true: | |
129 | * | |
130 | * @li All of the data in the supplied buffers has been written. That is, the | |
131 | * bytes transferred is equal to the sum of the buffer sizes. | |
132 | * | |
133 | * @li The completion_condition function object returns 0. | |
134 | * | |
135 | * This operation is implemented in terms of zero or more calls to the stream's | |
136 | * write_some function. | |
137 | * | |
138 | * @param s The stream to which the data is to be written. The type must support | |
139 | * the SyncWriteStream concept. | |
140 | * | |
141 | * @param buffers One or more buffers containing the data to be written. The sum | |
142 | * of the buffer sizes indicates the maximum number of bytes to write to the | |
143 | * stream. | |
144 | * | |
145 | * @param completion_condition The function object to be called to determine | |
146 | * whether the write operation is complete. The signature of the function object | |
147 | * must be: | |
148 | * @code std::size_t completion_condition( | |
149 | * // Result of latest write_some operation. | |
150 | * const boost::system::error_code& error, | |
151 | * | |
152 | * // Number of bytes transferred so far. | |
153 | * std::size_t bytes_transferred | |
154 | * ); @endcode | |
155 | * A return value of 0 indicates that the write operation is complete. A | |
156 | * non-zero return value indicates the maximum number of bytes to be written on | |
157 | * the next call to the stream's write_some function. | |
158 | * | |
159 | * @returns The number of bytes transferred. | |
160 | * | |
161 | * @throws boost::system::system_error Thrown on failure. | |
162 | * | |
163 | * @par Example | |
164 | * To write a single data buffer use the @ref buffer function as follows: | |
165 | * @code boost::asio::write(s, boost::asio::buffer(data, size), | |
166 | * boost::asio::transfer_at_least(32)); @endcode | |
167 | * See the @ref buffer documentation for information on writing multiple | |
168 | * buffers in one go, and how to use it with arrays, boost::array or | |
169 | * std::vector. | |
170 | */ | |
171 | template <typename SyncWriteStream, typename ConstBufferSequence, | |
172 | typename CompletionCondition> | |
173 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, | |
b32b8144 FG |
174 | CompletionCondition completion_condition, |
175 | typename enable_if< | |
176 | is_const_buffer_sequence<ConstBufferSequence>::value | |
177 | >::type* = 0); | |
7c673cae FG |
178 | |
179 | /// Write a certain amount of data to a stream before returning. | |
180 | /** | |
181 | * This function is used to write a certain number of bytes of data to a stream. | |
182 | * The call will block until one of the following conditions is true: | |
183 | * | |
184 | * @li All of the data in the supplied buffers has been written. That is, the | |
185 | * bytes transferred is equal to the sum of the buffer sizes. | |
186 | * | |
187 | * @li The completion_condition function object returns 0. | |
188 | * | |
189 | * This operation is implemented in terms of zero or more calls to the stream's | |
190 | * write_some function. | |
191 | * | |
192 | * @param s The stream to which the data is to be written. The type must support | |
193 | * the SyncWriteStream concept. | |
194 | * | |
195 | * @param buffers One or more buffers containing the data to be written. The sum | |
196 | * of the buffer sizes indicates the maximum number of bytes to write to the | |
197 | * stream. | |
198 | * | |
199 | * @param completion_condition The function object to be called to determine | |
200 | * whether the write operation is complete. The signature of the function object | |
201 | * must be: | |
202 | * @code std::size_t completion_condition( | |
203 | * // Result of latest write_some operation. | |
204 | * const boost::system::error_code& error, | |
205 | * | |
206 | * // Number of bytes transferred so far. | |
207 | * std::size_t bytes_transferred | |
208 | * ); @endcode | |
209 | * A return value of 0 indicates that the write operation is complete. A | |
210 | * non-zero return value indicates the maximum number of bytes to be written on | |
211 | * the next call to the stream's write_some function. | |
212 | * | |
213 | * @param ec Set to indicate what error occurred, if any. | |
214 | * | |
215 | * @returns The number of bytes written. If an error occurs, returns the total | |
216 | * number of bytes successfully transferred prior to the error. | |
217 | */ | |
218 | template <typename SyncWriteStream, typename ConstBufferSequence, | |
219 | typename CompletionCondition> | |
220 | std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers, | |
b32b8144 FG |
221 | CompletionCondition completion_condition, boost::system::error_code& ec, |
222 | typename enable_if< | |
223 | is_const_buffer_sequence<ConstBufferSequence>::value | |
224 | >::type* = 0); | |
225 | ||
226 | /// Write all of the supplied data to a stream before returning. | |
227 | /** | |
228 | * This function is used to write a certain number of bytes of data to a stream. | |
229 | * The call will block until one of the following conditions is true: | |
230 | * | |
231 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
232 | * | |
233 | * @li An error occurred. | |
234 | * | |
235 | * This operation is implemented in terms of zero or more calls to the stream's | |
236 | * write_some function. | |
237 | * | |
238 | * @param s The stream to which the data is to be written. The type must support | |
239 | * the SyncWriteStream concept. | |
240 | * | |
241 | * @param buffers The dynamic buffer sequence from which data will be written. | |
242 | * Successfully written data is automatically consumed from the buffers. | |
243 | * | |
244 | * @returns The number of bytes transferred. | |
245 | * | |
246 | * @throws boost::system::system_error Thrown on failure. | |
247 | * | |
248 | * @note This overload is equivalent to calling: | |
249 | * @code boost::asio::write( | |
250 | * s, buffers, | |
251 | * boost::asio::transfer_all()); @endcode | |
252 | */ | |
253 | template <typename SyncWriteStream, typename DynamicBuffer> | |
254 | std::size_t write(SyncWriteStream& s, | |
255 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
256 | typename enable_if< | |
257 | is_dynamic_buffer<DynamicBuffer>::value | |
258 | >::type* = 0); | |
259 | ||
260 | /// Write all of the supplied data to a stream before returning. | |
261 | /** | |
262 | * This function is used to write a certain number of bytes of data to a stream. | |
263 | * The call will block until one of the following conditions is true: | |
264 | * | |
265 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
266 | * | |
267 | * @li An error occurred. | |
268 | * | |
269 | * This operation is implemented in terms of zero or more calls to the stream's | |
270 | * write_some function. | |
271 | * | |
272 | * @param s The stream to which the data is to be written. The type must support | |
273 | * the SyncWriteStream concept. | |
274 | * | |
275 | * @param buffers The dynamic buffer sequence from which data will be written. | |
276 | * Successfully written data is automatically consumed from the buffers. | |
277 | * | |
278 | * @param ec Set to indicate what error occurred, if any. | |
279 | * | |
280 | * @returns The number of bytes transferred. | |
281 | * | |
282 | * @note This overload is equivalent to calling: | |
283 | * @code boost::asio::write( | |
284 | * s, buffers, | |
285 | * boost::asio::transfer_all(), ec); @endcode | |
286 | */ | |
287 | template <typename SyncWriteStream, typename DynamicBuffer> | |
288 | std::size_t write(SyncWriteStream& s, | |
289 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
290 | boost::system::error_code& ec, | |
291 | typename enable_if< | |
292 | is_dynamic_buffer<DynamicBuffer>::value | |
293 | >::type* = 0); | |
294 | ||
295 | /// Write a certain amount of data to a stream before returning. | |
296 | /** | |
297 | * This function is used to write a certain number of bytes of data to a stream. | |
298 | * The call will block until one of the following conditions is true: | |
299 | * | |
300 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
301 | * | |
302 | * @li The completion_condition function object returns 0. | |
303 | * | |
304 | * This operation is implemented in terms of zero or more calls to the stream's | |
305 | * write_some function. | |
306 | * | |
307 | * @param s The stream to which the data is to be written. The type must support | |
308 | * the SyncWriteStream concept. | |
309 | * | |
310 | * @param buffers The dynamic buffer sequence from which data will be written. | |
311 | * Successfully written data is automatically consumed from the buffers. | |
312 | * | |
313 | * @param completion_condition The function object to be called to determine | |
314 | * whether the write operation is complete. The signature of the function object | |
315 | * must be: | |
316 | * @code std::size_t completion_condition( | |
317 | * // Result of latest write_some operation. | |
318 | * const boost::system::error_code& error, | |
319 | * | |
320 | * // Number of bytes transferred so far. | |
321 | * std::size_t bytes_transferred | |
322 | * ); @endcode | |
323 | * A return value of 0 indicates that the write operation is complete. A | |
324 | * non-zero return value indicates the maximum number of bytes to be written on | |
325 | * the next call to the stream's write_some function. | |
326 | * | |
327 | * @returns The number of bytes transferred. | |
328 | * | |
329 | * @throws boost::system::system_error Thrown on failure. | |
330 | */ | |
331 | template <typename SyncWriteStream, typename DynamicBuffer, | |
332 | typename CompletionCondition> | |
333 | std::size_t write(SyncWriteStream& s, | |
334 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
335 | CompletionCondition completion_condition, | |
336 | typename enable_if< | |
337 | is_dynamic_buffer<DynamicBuffer>::value | |
338 | >::type* = 0); | |
339 | ||
340 | /// Write a certain amount of data to a stream before returning. | |
341 | /** | |
342 | * This function is used to write a certain number of bytes of data to a stream. | |
343 | * The call will block until one of the following conditions is true: | |
344 | * | |
345 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
346 | * | |
347 | * @li The completion_condition function object returns 0. | |
348 | * | |
349 | * This operation is implemented in terms of zero or more calls to the stream's | |
350 | * write_some function. | |
351 | * | |
352 | * @param s The stream to which the data is to be written. The type must support | |
353 | * the SyncWriteStream concept. | |
354 | * | |
355 | * @param buffers The dynamic buffer sequence from which data will be written. | |
356 | * Successfully written data is automatically consumed from the buffers. | |
357 | * | |
358 | * @param completion_condition The function object to be called to determine | |
359 | * whether the write operation is complete. The signature of the function object | |
360 | * must be: | |
361 | * @code std::size_t completion_condition( | |
362 | * // Result of latest write_some operation. | |
363 | * const boost::system::error_code& error, | |
364 | * | |
365 | * // Number of bytes transferred so far. | |
366 | * std::size_t bytes_transferred | |
367 | * ); @endcode | |
368 | * A return value of 0 indicates that the write operation is complete. A | |
369 | * non-zero return value indicates the maximum number of bytes to be written on | |
370 | * the next call to the stream's write_some function. | |
371 | * | |
372 | * @param ec Set to indicate what error occurred, if any. | |
373 | * | |
374 | * @returns The number of bytes written. If an error occurs, returns the total | |
375 | * number of bytes successfully transferred prior to the error. | |
376 | */ | |
377 | template <typename SyncWriteStream, typename DynamicBuffer, | |
378 | typename CompletionCondition> | |
379 | std::size_t write(SyncWriteStream& s, | |
380 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
381 | CompletionCondition completion_condition, boost::system::error_code& ec, | |
382 | typename enable_if< | |
383 | is_dynamic_buffer<DynamicBuffer>::value | |
384 | >::type* = 0); | |
7c673cae | 385 | |
b32b8144 | 386 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
7c673cae FG |
387 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
388 | ||
389 | /// Write all of the supplied data to a stream before returning. | |
390 | /** | |
391 | * This function is used to write a certain number of bytes of data to a stream. | |
392 | * The call will block until one of the following conditions is true: | |
393 | * | |
394 | * @li All of the data in the supplied basic_streambuf has been written. | |
395 | * | |
396 | * @li An error occurred. | |
397 | * | |
398 | * This operation is implemented in terms of zero or more calls to the stream's | |
399 | * write_some function. | |
400 | * | |
401 | * @param s The stream to which the data is to be written. The type must support | |
402 | * the SyncWriteStream concept. | |
403 | * | |
404 | * @param b The basic_streambuf object from which data will be written. | |
405 | * | |
406 | * @returns The number of bytes transferred. | |
407 | * | |
408 | * @throws boost::system::system_error Thrown on failure. | |
409 | * | |
410 | * @note This overload is equivalent to calling: | |
411 | * @code boost::asio::write( | |
412 | * s, b, | |
413 | * boost::asio::transfer_all()); @endcode | |
414 | */ | |
415 | template <typename SyncWriteStream, typename Allocator> | |
416 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b); | |
417 | ||
418 | /// Write all of the supplied data to a stream before returning. | |
419 | /** | |
420 | * This function is used to write a certain number of bytes of data to a stream. | |
421 | * The call will block until one of the following conditions is true: | |
422 | * | |
423 | * @li All of the data in the supplied basic_streambuf has been written. | |
424 | * | |
425 | * @li An error occurred. | |
426 | * | |
427 | * This operation is implemented in terms of zero or more calls to the stream's | |
428 | * write_some function. | |
429 | * | |
430 | * @param s The stream to which the data is to be written. The type must support | |
431 | * the SyncWriteStream concept. | |
432 | * | |
433 | * @param b The basic_streambuf object from which data will be written. | |
434 | * | |
435 | * @param ec Set to indicate what error occurred, if any. | |
436 | * | |
437 | * @returns The number of bytes transferred. | |
438 | * | |
439 | * @note This overload is equivalent to calling: | |
440 | * @code boost::asio::write( | |
441 | * s, b, | |
442 | * boost::asio::transfer_all(), ec); @endcode | |
443 | */ | |
444 | template <typename SyncWriteStream, typename Allocator> | |
445 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, | |
446 | boost::system::error_code& ec); | |
447 | ||
448 | /// Write a certain amount of data to a stream before returning. | |
449 | /** | |
450 | * This function is used to write a certain number of bytes of data to a stream. | |
451 | * The call will block until one of the following conditions is true: | |
452 | * | |
453 | * @li All of the data in the supplied basic_streambuf has been written. | |
454 | * | |
455 | * @li The completion_condition function object returns 0. | |
456 | * | |
457 | * This operation is implemented in terms of zero or more calls to the stream's | |
458 | * write_some function. | |
459 | * | |
460 | * @param s The stream to which the data is to be written. The type must support | |
461 | * the SyncWriteStream concept. | |
462 | * | |
463 | * @param b The basic_streambuf object from which data will be written. | |
464 | * | |
465 | * @param completion_condition The function object to be called to determine | |
466 | * whether the write operation is complete. The signature of the function object | |
467 | * must be: | |
468 | * @code std::size_t completion_condition( | |
469 | * // Result of latest write_some operation. | |
470 | * const boost::system::error_code& error, | |
471 | * | |
472 | * // Number of bytes transferred so far. | |
473 | * std::size_t bytes_transferred | |
474 | * ); @endcode | |
475 | * A return value of 0 indicates that the write operation is complete. A | |
476 | * non-zero return value indicates the maximum number of bytes to be written on | |
477 | * the next call to the stream's write_some function. | |
478 | * | |
479 | * @returns The number of bytes transferred. | |
480 | * | |
481 | * @throws boost::system::system_error Thrown on failure. | |
482 | */ | |
483 | template <typename SyncWriteStream, typename Allocator, | |
484 | typename CompletionCondition> | |
485 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, | |
486 | CompletionCondition completion_condition); | |
487 | ||
488 | /// Write a certain amount of data to a stream before returning. | |
489 | /** | |
490 | * This function is used to write a certain number of bytes of data to a stream. | |
491 | * The call will block until one of the following conditions is true: | |
492 | * | |
493 | * @li All of the data in the supplied basic_streambuf has been written. | |
494 | * | |
495 | * @li The completion_condition function object returns 0. | |
496 | * | |
497 | * This operation is implemented in terms of zero or more calls to the stream's | |
498 | * write_some function. | |
499 | * | |
500 | * @param s The stream to which the data is to be written. The type must support | |
501 | * the SyncWriteStream concept. | |
502 | * | |
503 | * @param b The basic_streambuf object from which data will be written. | |
504 | * | |
505 | * @param completion_condition The function object to be called to determine | |
506 | * whether the write operation is complete. The signature of the function object | |
507 | * must be: | |
508 | * @code std::size_t completion_condition( | |
509 | * // Result of latest write_some operation. | |
510 | * const boost::system::error_code& error, | |
511 | * | |
512 | * // Number of bytes transferred so far. | |
513 | * std::size_t bytes_transferred | |
514 | * ); @endcode | |
515 | * A return value of 0 indicates that the write operation is complete. A | |
516 | * non-zero return value indicates the maximum number of bytes to be written on | |
517 | * the next call to the stream's write_some function. | |
518 | * | |
519 | * @param ec Set to indicate what error occurred, if any. | |
520 | * | |
521 | * @returns The number of bytes written. If an error occurs, returns the total | |
522 | * number of bytes successfully transferred prior to the error. | |
523 | */ | |
524 | template <typename SyncWriteStream, typename Allocator, | |
525 | typename CompletionCondition> | |
526 | std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b, | |
527 | CompletionCondition completion_condition, boost::system::error_code& ec); | |
528 | ||
529 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) | |
b32b8144 | 530 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
7c673cae FG |
531 | |
532 | /*@}*/ | |
533 | /** | |
534 | * @defgroup async_write boost::asio::async_write | |
535 | * | |
536 | * @brief Start an asynchronous operation to write a certain amount of data to a | |
537 | * stream. | |
538 | */ | |
539 | /*@{*/ | |
540 | ||
541 | /// Start an asynchronous operation to write all of the supplied data to a | |
542 | /// stream. | |
543 | /** | |
544 | * This function is used to asynchronously write a certain number of bytes of | |
545 | * data to a stream. The function call always returns immediately. The | |
546 | * asynchronous operation will continue until one of the following conditions | |
547 | * is true: | |
548 | * | |
549 | * @li All of the data in the supplied buffers has been written. That is, the | |
550 | * bytes transferred is equal to the sum of the buffer sizes. | |
551 | * | |
552 | * @li An error occurred. | |
553 | * | |
554 | * This operation is implemented in terms of zero or more calls to the stream's | |
555 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
556 | * program must ensure that the stream performs no other write operations (such | |
557 | * as async_write, the stream's async_write_some function, or any other composed | |
558 | * operations that perform writes) until this operation completes. | |
559 | * | |
560 | * @param s The stream to which the data is to be written. The type must support | |
561 | * the AsyncWriteStream concept. | |
562 | * | |
563 | * @param buffers One or more buffers containing the data to be written. | |
564 | * Although the buffers object may be copied as necessary, ownership of the | |
565 | * underlying memory blocks is retained by the caller, which must guarantee | |
566 | * that they remain valid until the handler is called. | |
567 | * | |
568 | * @param handler The handler to be called when the write operation completes. | |
569 | * Copies will be made of the handler as required. The function signature of | |
570 | * the handler must be: | |
571 | * @code void handler( | |
572 | * const boost::system::error_code& error, // Result of operation. | |
573 | * | |
574 | * std::size_t bytes_transferred // Number of bytes written from the | |
575 | * // buffers. If an error occurred, | |
576 | * // this will be less than the sum | |
577 | * // of the buffer sizes. | |
578 | * ); @endcode | |
579 | * Regardless of whether the asynchronous operation completes immediately or | |
580 | * not, the handler will not be invoked from within this function. Invocation of | |
581 | * the handler will be performed in a manner equivalent to using | |
b32b8144 | 582 | * boost::asio::io_context::post(). |
7c673cae FG |
583 | * |
584 | * @par Example | |
585 | * To write a single data buffer use the @ref buffer function as follows: | |
586 | * @code | |
587 | * boost::asio::async_write(s, boost::asio::buffer(data, size), handler); | |
588 | * @endcode | |
589 | * See the @ref buffer documentation for information on writing multiple | |
590 | * buffers in one go, and how to use it with arrays, boost::array or | |
591 | * std::vector. | |
592 | */ | |
593 | template <typename AsyncWriteStream, typename ConstBufferSequence, | |
594 | typename WriteHandler> | |
595 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
596 | void (boost::system::error_code, std::size_t)) | |
597 | async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, | |
b32b8144 FG |
598 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler, |
599 | typename enable_if< | |
600 | is_const_buffer_sequence<ConstBufferSequence>::value | |
601 | >::type* = 0); | |
7c673cae FG |
602 | |
603 | /// Start an asynchronous operation to write a certain amount of data to a | |
604 | /// stream. | |
605 | /** | |
606 | * This function is used to asynchronously write a certain number of bytes of | |
607 | * data to a stream. The function call always returns immediately. The | |
608 | * asynchronous operation will continue until one of the following conditions | |
609 | * is true: | |
610 | * | |
611 | * @li All of the data in the supplied buffers has been written. That is, the | |
612 | * bytes transferred is equal to the sum of the buffer sizes. | |
613 | * | |
614 | * @li The completion_condition function object returns 0. | |
615 | * | |
616 | * This operation is implemented in terms of zero or more calls to the stream's | |
617 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
618 | * program must ensure that the stream performs no other write operations (such | |
619 | * as async_write, the stream's async_write_some function, or any other composed | |
620 | * operations that perform writes) until this operation completes. | |
621 | * | |
622 | * @param s The stream to which the data is to be written. The type must support | |
623 | * the AsyncWriteStream concept. | |
624 | * | |
625 | * @param buffers One or more buffers containing the data to be written. | |
626 | * Although the buffers object may be copied as necessary, ownership of the | |
627 | * underlying memory blocks is retained by the caller, which must guarantee | |
628 | * that they remain valid until the handler is called. | |
629 | * | |
630 | * @param completion_condition The function object to be called to determine | |
631 | * whether the write operation is complete. The signature of the function object | |
632 | * must be: | |
633 | * @code std::size_t completion_condition( | |
634 | * // Result of latest async_write_some operation. | |
635 | * const boost::system::error_code& error, | |
636 | * | |
637 | * // Number of bytes transferred so far. | |
638 | * std::size_t bytes_transferred | |
639 | * ); @endcode | |
640 | * A return value of 0 indicates that the write operation is complete. A | |
641 | * non-zero return value indicates the maximum number of bytes to be written on | |
642 | * the next call to the stream's async_write_some function. | |
643 | * | |
644 | * @param handler The handler to be called when the write operation completes. | |
645 | * Copies will be made of the handler as required. The function signature of the | |
646 | * handler must be: | |
647 | * @code void handler( | |
648 | * const boost::system::error_code& error, // Result of operation. | |
649 | * | |
650 | * std::size_t bytes_transferred // Number of bytes written from the | |
651 | * // buffers. If an error occurred, | |
652 | * // this will be less than the sum | |
653 | * // of the buffer sizes. | |
654 | * ); @endcode | |
655 | * Regardless of whether the asynchronous operation completes immediately or | |
656 | * not, the handler will not be invoked from within this function. Invocation of | |
657 | * the handler will be performed in a manner equivalent to using | |
b32b8144 | 658 | * boost::asio::io_context::post(). |
7c673cae FG |
659 | * |
660 | * @par Example | |
661 | * To write a single data buffer use the @ref buffer function as follows: | |
662 | * @code boost::asio::async_write(s, | |
663 | * boost::asio::buffer(data, size), | |
664 | * boost::asio::transfer_at_least(32), | |
665 | * handler); @endcode | |
666 | * See the @ref buffer documentation for information on writing multiple | |
667 | * buffers in one go, and how to use it with arrays, boost::array or | |
668 | * std::vector. | |
669 | */ | |
670 | template <typename AsyncWriteStream, typename ConstBufferSequence, | |
671 | typename CompletionCondition, typename WriteHandler> | |
672 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
673 | void (boost::system::error_code, std::size_t)) | |
674 | async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers, | |
675 | CompletionCondition completion_condition, | |
b32b8144 FG |
676 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler, |
677 | typename enable_if< | |
678 | is_const_buffer_sequence<ConstBufferSequence>::value | |
679 | >::type* = 0); | |
680 | ||
681 | /// Start an asynchronous operation to write all of the supplied data to a | |
682 | /// stream. | |
683 | /** | |
684 | * This function is used to asynchronously write a certain number of bytes of | |
685 | * data to a stream. The function call always returns immediately. The | |
686 | * asynchronous operation will continue until one of the following conditions | |
687 | * is true: | |
688 | * | |
689 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
690 | * | |
691 | * @li An error occurred. | |
692 | * | |
693 | * This operation is implemented in terms of zero or more calls to the stream's | |
694 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
695 | * program must ensure that the stream performs no other write operations (such | |
696 | * as async_write, the stream's async_write_some function, or any other composed | |
697 | * operations that perform writes) until this operation completes. | |
698 | * | |
699 | * @param s The stream to which the data is to be written. The type must support | |
700 | * the AsyncWriteStream concept. | |
701 | * | |
702 | * @param buffers The dynamic buffer sequence from which data will be written. | |
703 | * Although the buffers object may be copied as necessary, ownership of the | |
704 | * underlying memory blocks is retained by the caller, which must guarantee | |
705 | * that they remain valid until the handler is called. Successfully written | |
706 | * data is automatically consumed from the buffers. | |
707 | * | |
708 | * @param handler The handler to be called when the write operation completes. | |
709 | * Copies will be made of the handler as required. The function signature of the | |
710 | * handler must be: | |
711 | * @code void handler( | |
712 | * const boost::system::error_code& error, // Result of operation. | |
713 | * | |
714 | * std::size_t bytes_transferred // Number of bytes written from the | |
715 | * // buffers. If an error occurred, | |
716 | * // this will be less than the sum | |
717 | * // of the buffer sizes. | |
718 | * ); @endcode | |
719 | * Regardless of whether the asynchronous operation completes immediately or | |
720 | * not, the handler will not be invoked from within this function. Invocation of | |
721 | * the handler will be performed in a manner equivalent to using | |
722 | * boost::asio::io_context::post(). | |
723 | */ | |
724 | template <typename AsyncWriteStream, | |
725 | typename DynamicBuffer, typename WriteHandler> | |
726 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
727 | void (boost::system::error_code, std::size_t)) | |
728 | async_write(AsyncWriteStream& s, | |
729 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
730 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler, | |
731 | typename enable_if< | |
732 | is_dynamic_buffer<DynamicBuffer>::value | |
733 | >::type* = 0); | |
734 | ||
735 | /// Start an asynchronous operation to write a certain amount of data to a | |
736 | /// stream. | |
737 | /** | |
738 | * This function is used to asynchronously write a certain number of bytes of | |
739 | * data to a stream. The function call always returns immediately. The | |
740 | * asynchronous operation will continue until one of the following conditions | |
741 | * is true: | |
742 | * | |
743 | * @li All of the data in the supplied dynamic buffer sequence has been written. | |
744 | * | |
745 | * @li The completion_condition function object returns 0. | |
746 | * | |
747 | * This operation is implemented in terms of zero or more calls to the stream's | |
748 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
749 | * program must ensure that the stream performs no other write operations (such | |
750 | * as async_write, the stream's async_write_some function, or any other composed | |
751 | * operations that perform writes) until this operation completes. | |
752 | * | |
753 | * @param s The stream to which the data is to be written. The type must support | |
754 | * the AsyncWriteStream concept. | |
755 | * | |
756 | * @param buffers The dynamic buffer sequence from which data will be written. | |
757 | * Although the buffers object may be copied as necessary, ownership of the | |
758 | * underlying memory blocks is retained by the caller, which must guarantee | |
759 | * that they remain valid until the handler is called. Successfully written | |
760 | * data is automatically consumed from the buffers. | |
761 | * | |
762 | * @param completion_condition The function object to be called to determine | |
763 | * whether the write operation is complete. The signature of the function object | |
764 | * must be: | |
765 | * @code std::size_t completion_condition( | |
766 | * // Result of latest async_write_some operation. | |
767 | * const boost::system::error_code& error, | |
768 | * | |
769 | * // Number of bytes transferred so far. | |
770 | * std::size_t bytes_transferred | |
771 | * ); @endcode | |
772 | * A return value of 0 indicates that the write operation is complete. A | |
773 | * non-zero return value indicates the maximum number of bytes to be written on | |
774 | * the next call to the stream's async_write_some function. | |
775 | * | |
776 | * @param handler The handler to be called when the write operation completes. | |
777 | * Copies will be made of the handler as required. The function signature of the | |
778 | * handler must be: | |
779 | * @code void handler( | |
780 | * const boost::system::error_code& error, // Result of operation. | |
781 | * | |
782 | * std::size_t bytes_transferred // Number of bytes written from the | |
783 | * // buffers. If an error occurred, | |
784 | * // this will be less than the sum | |
785 | * // of the buffer sizes. | |
786 | * ); @endcode | |
787 | * Regardless of whether the asynchronous operation completes immediately or | |
788 | * not, the handler will not be invoked from within this function. Invocation of | |
789 | * the handler will be performed in a manner equivalent to using | |
790 | * boost::asio::io_context::post(). | |
791 | */ | |
792 | template <typename AsyncWriteStream, typename DynamicBuffer, | |
793 | typename CompletionCondition, typename WriteHandler> | |
794 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
795 | void (boost::system::error_code, std::size_t)) | |
796 | async_write(AsyncWriteStream& s, | |
797 | BOOST_ASIO_MOVE_ARG(DynamicBuffer) buffers, | |
798 | CompletionCondition completion_condition, | |
799 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler, | |
800 | typename enable_if< | |
801 | is_dynamic_buffer<DynamicBuffer>::value | |
802 | >::type* = 0); | |
7c673cae | 803 | |
b32b8144 | 804 | #if !defined(BOOST_ASIO_NO_EXTENSIONS) |
7c673cae FG |
805 | #if !defined(BOOST_ASIO_NO_IOSTREAM) |
806 | ||
807 | /// Start an asynchronous operation to write all of the supplied 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. The function call always returns immediately. The | |
812 | * asynchronous operation will continue until one of the following conditions | |
813 | * is true: | |
814 | * | |
815 | * @li All of the data in the supplied basic_streambuf has been written. | |
816 | * | |
817 | * @li An error occurred. | |
818 | * | |
819 | * This operation is implemented in terms of zero or more calls to the stream's | |
820 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
821 | * program must ensure that the stream performs no other write operations (such | |
822 | * as async_write, the stream's async_write_some function, or any other composed | |
823 | * operations that perform writes) until this operation completes. | |
824 | * | |
825 | * @param s The stream to which the data is to be written. The type must support | |
826 | * the AsyncWriteStream concept. | |
827 | * | |
828 | * @param b A basic_streambuf object from which data will be written. Ownership | |
829 | * of the streambuf is retained by the caller, which must guarantee that it | |
830 | * remains valid until the handler is called. | |
831 | * | |
832 | * @param handler The handler to be called when the write operation completes. | |
833 | * Copies will be made of the handler as required. The function signature of the | |
834 | * handler must be: | |
835 | * @code void handler( | |
836 | * const boost::system::error_code& error, // Result of operation. | |
837 | * | |
838 | * std::size_t bytes_transferred // Number of bytes written from the | |
839 | * // buffers. If an error occurred, | |
840 | * // this will be less than the sum | |
841 | * // of the buffer sizes. | |
842 | * ); @endcode | |
843 | * Regardless of whether the asynchronous operation completes immediately or | |
844 | * not, the handler will not be invoked from within this function. Invocation of | |
845 | * the handler will be performed in a manner equivalent to using | |
b32b8144 | 846 | * boost::asio::io_context::post(). |
7c673cae FG |
847 | */ |
848 | template <typename AsyncWriteStream, typename Allocator, typename WriteHandler> | |
849 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
850 | void (boost::system::error_code, std::size_t)) | |
851 | async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b, | |
852 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler); | |
853 | ||
854 | /// Start an asynchronous operation to write a certain amount of data to a | |
855 | /// stream. | |
856 | /** | |
857 | * This function is used to asynchronously write a certain number of bytes of | |
858 | * data to a stream. The function call always returns immediately. The | |
859 | * asynchronous operation will continue until one of the following conditions | |
860 | * is true: | |
861 | * | |
862 | * @li All of the data in the supplied basic_streambuf has been written. | |
863 | * | |
864 | * @li The completion_condition function object returns 0. | |
865 | * | |
866 | * This operation is implemented in terms of zero or more calls to the stream's | |
867 | * async_write_some function, and is known as a <em>composed operation</em>. The | |
868 | * program must ensure that the stream performs no other write operations (such | |
869 | * as async_write, the stream's async_write_some function, or any other composed | |
870 | * operations that perform writes) until this operation completes. | |
871 | * | |
872 | * @param s The stream to which the data is to be written. The type must support | |
873 | * the AsyncWriteStream concept. | |
874 | * | |
875 | * @param b A basic_streambuf object from which data will be written. Ownership | |
876 | * of the streambuf is retained by the caller, which must guarantee that it | |
877 | * remains valid until the handler is called. | |
878 | * | |
879 | * @param completion_condition The function object to be called to determine | |
880 | * whether the write operation is complete. The signature of the function object | |
881 | * must be: | |
882 | * @code std::size_t completion_condition( | |
883 | * // Result of latest async_write_some operation. | |
884 | * const boost::system::error_code& error, | |
885 | * | |
886 | * // Number of bytes transferred so far. | |
887 | * std::size_t bytes_transferred | |
888 | * ); @endcode | |
889 | * A return value of 0 indicates that the write operation is complete. A | |
890 | * non-zero return value indicates the maximum number of bytes to be written on | |
891 | * the next call to the stream's async_write_some function. | |
892 | * | |
893 | * @param handler The handler to be called when the write operation completes. | |
894 | * Copies will be made of the handler as required. The function signature of the | |
895 | * handler must be: | |
896 | * @code void handler( | |
897 | * const boost::system::error_code& error, // Result of operation. | |
898 | * | |
899 | * std::size_t bytes_transferred // Number of bytes written from the | |
900 | * // buffers. If an error occurred, | |
901 | * // this will be less than the sum | |
902 | * // of the buffer sizes. | |
903 | * ); @endcode | |
904 | * Regardless of whether the asynchronous operation completes immediately or | |
905 | * not, the handler will not be invoked from within this function. Invocation of | |
906 | * the handler will be performed in a manner equivalent to using | |
b32b8144 | 907 | * boost::asio::io_context::post(). |
7c673cae FG |
908 | */ |
909 | template <typename AsyncWriteStream, typename Allocator, | |
910 | typename CompletionCondition, typename WriteHandler> | |
911 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
912 | void (boost::system::error_code, std::size_t)) | |
913 | async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b, | |
914 | CompletionCondition completion_condition, | |
915 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler); | |
916 | ||
917 | #endif // !defined(BOOST_ASIO_NO_IOSTREAM) | |
b32b8144 | 918 | #endif // !defined(BOOST_ASIO_NO_EXTENSIONS) |
7c673cae FG |
919 | |
920 | /*@}*/ | |
921 | ||
922 | } // namespace asio | |
923 | } // namespace boost | |
924 | ||
925 | #include <boost/asio/detail/pop_options.hpp> | |
926 | ||
927 | #include <boost/asio/impl/write.hpp> | |
928 | ||
929 | #endif // BOOST_ASIO_WRITE_HPP |