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