/src/contrib/boost/asio/write.hpp

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