5
// Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11
#ifndef ASIO_WRITE_HPP
12
#define ASIO_WRITE_HPP
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18
#include "asio/detail/push_options.hpp"
20
#include "asio/detail/push_options.hpp"
22
#include <boost/config.hpp>
23
#include "asio/detail/pop_options.hpp"
25
#include "asio/basic_streambuf.hpp"
26
#include "asio/error.hpp"
31
* @defgroup write asio::write
33
* @brief Write a certain amount of data to a stream before returning.
37
/// Write all of the supplied data to a stream before returning.
39
* This function is used to write a certain number of bytes of data to a stream.
40
* The call will block until one of the following conditions is true:
42
* @li All of the data in the supplied buffers has been written. That is, the
43
* bytes transferred is equal to the sum of the buffer sizes.
45
* @li An error occurred.
47
* This operation is implemented in terms of one or more calls to the stream's
48
* write_some function.
50
* @param s The stream to which the data is to be written. The type must support
51
* the SyncWriteStream concept.
53
* @param buffers One or more buffers containing the data to be written. The sum
54
* of the buffer sizes indicates the maximum number of bytes to write to the
57
* @returns The number of bytes transferred.
59
* @throws asio::system_error Thrown on failure.
62
* To write a single data buffer use the @ref buffer function as follows:
63
* @code asio::write(s, asio::buffer(data, size)); @endcode
64
* See the @ref buffer documentation for information on writing multiple
65
* buffers in one go, and how to use it with arrays, boost::array or
68
* @note This overload is equivalent to calling:
71
* asio::transfer_all()); @endcode
73
template <typename SyncWriteStream, typename ConstBufferSequence>
74
std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers);
76
/// Write a certain amount of data to a stream before returning.
78
* This function is used to write a certain number of bytes of data to a stream.
79
* The call will block until one of the following conditions is true:
81
* @li All of the data in the supplied buffers has been written. That is, the
82
* bytes transferred is equal to the sum of the buffer sizes.
84
* @li The completion_condition function object returns true.
86
* This operation is implemented in terms of one or more calls to the stream's
87
* write_some function.
89
* @param s The stream to which the data is to be written. The type must support
90
* the SyncWriteStream concept.
92
* @param buffers One or more buffers containing the data to be written. The sum
93
* of the buffer sizes indicates the maximum number of bytes to write to the
96
* @param completion_condition The function object to be called to determine
97
* whether the write operation is complete. The signature of the function object
99
* @code bool completion_condition(
100
* const asio::error_code& error, // Result of latest write_some
103
* std::size_t bytes_transferred // Number of bytes transferred
106
* A return value of true indicates that the write operation is complete. False
107
* indicates that further calls to the stream's write_some function are
110
* @returns The number of bytes transferred.
112
* @throws asio::system_error Thrown on failure.
115
* To write a single data buffer use the @ref buffer function as follows:
116
* @code asio::write(s, asio::buffer(data, size),
117
* asio::transfer_at_least(32)); @endcode
118
* See the @ref buffer documentation for information on writing multiple
119
* buffers in one go, and how to use it with arrays, boost::array or
122
template <typename SyncWriteStream, typename ConstBufferSequence,
123
typename CompletionCondition>
124
std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
125
CompletionCondition completion_condition);
127
/// Write a certain amount of data to a stream before returning.
129
* This function is used to write a certain number of bytes of data to a stream.
130
* The call will block until one of the following conditions is true:
132
* @li All of the data in the supplied buffers has been written. That is, the
133
* bytes transferred is equal to the sum of the buffer sizes.
135
* @li The completion_condition function object returns true.
137
* This operation is implemented in terms of one or more calls to the stream's
138
* write_some function.
140
* @param s The stream to which the data is to be written. The type must support
141
* the SyncWriteStream concept.
143
* @param buffers One or more buffers containing the data to be written. The sum
144
* of the buffer sizes indicates the maximum number of bytes to write to the
147
* @param completion_condition The function object to be called to determine
148
* whether the write operation is complete. The signature of the function object
150
* @code bool completion_condition(
151
* const asio::error_code& error, // Result of latest write_some
154
* std::size_t bytes_transferred // Number of bytes transferred
157
* A return value of true indicates that the write operation is complete. False
158
* indicates that further calls to the stream's write_some function are
161
* @param ec Set to indicate what error occurred, if any.
163
* @returns The number of bytes written. If an error occurs, returns the total
164
* number of bytes successfully transferred prior to the error.
166
template <typename SyncWriteStream, typename ConstBufferSequence,
167
typename CompletionCondition>
168
std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
169
CompletionCondition completion_condition, asio::error_code& ec);
171
/// Write all of the supplied data to a stream before returning.
173
* This function is used to write a certain number of bytes of data to a stream.
174
* The call will block until one of the following conditions is true:
176
* @li All of the data in the supplied basic_streambuf has been written.
178
* @li An error occurred.
180
* This operation is implemented in terms of one or more calls to the stream's
181
* write_some function.
183
* @param s The stream to which the data is to be written. The type must support
184
* the SyncWriteStream concept.
186
* @param b The basic_streambuf object from which data will be written.
188
* @returns The number of bytes transferred.
190
* @throws asio::system_error Thrown on failure.
192
* @note This overload is equivalent to calling:
195
* asio::transfer_all()); @endcode
197
template <typename SyncWriteStream, typename Allocator>
198
std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b);
200
/// Write a certain amount of data to a stream before returning.
202
* This function is used to write a certain number of bytes of data to a stream.
203
* The call will block until one of the following conditions is true:
205
* @li All of the data in the supplied basic_streambuf has been written.
207
* @li The completion_condition function object returns true.
209
* This operation is implemented in terms of one or more calls to the stream's
210
* write_some function.
212
* @param s The stream to which the data is to be written. The type must support
213
* the SyncWriteStream concept.
215
* @param b The basic_streambuf object from which data will be written.
217
* @param completion_condition The function object to be called to determine
218
* whether the write operation is complete. The signature of the function object
220
* @code bool completion_condition(
221
* const asio::error_code& error, // Result of latest write_some
224
* std::size_t bytes_transferred // Number of bytes transferred
227
* A return value of true indicates that the write operation is complete. False
228
* indicates that further calls to the stream's write_some function are
231
* @returns The number of bytes transferred.
233
* @throws asio::system_error Thrown on failure.
235
template <typename SyncWriteStream, typename Allocator,
236
typename CompletionCondition>
237
std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
238
CompletionCondition completion_condition);
240
/// Write a certain amount of data to a stream before returning.
242
* This function is used to write a certain number of bytes of data to a stream.
243
* The call will block until one of the following conditions is true:
245
* @li All of the data in the supplied basic_streambuf has been written.
247
* @li The completion_condition function object returns true.
249
* This operation is implemented in terms of one or more calls to the stream's
250
* write_some function.
252
* @param s The stream to which the data is to be written. The type must support
253
* the SyncWriteStream concept.
255
* @param b The basic_streambuf object from which data will be written.
257
* @param completion_condition The function object to be called to determine
258
* whether the write operation is complete. The signature of the function object
260
* @code bool completion_condition(
261
* const asio::error_code& error, // Result of latest write_some
264
* std::size_t bytes_transferred // Number of bytes transferred
267
* A return value of true indicates that the write operation is complete. False
268
* indicates that further calls to the stream's write_some function are
271
* @param ec Set to indicate what error occurred, if any.
273
* @returns The number of bytes written. If an error occurs, returns the total
274
* number of bytes successfully transferred prior to the error.
276
template <typename SyncWriteStream, typename Allocator,
277
typename CompletionCondition>
278
std::size_t write(SyncWriteStream& s, basic_streambuf<Allocator>& b,
279
CompletionCondition completion_condition, asio::error_code& ec);
283
* @defgroup async_write asio::async_write
285
* @brief Start an asynchronous operation to write a certain amount of data to a
290
/// Start an asynchronous operation to write all of the supplied data to a
293
* This function is used to asynchronously write a certain number of bytes of
294
* data to a stream. The function call always returns immediately. The
295
* asynchronous operation will continue until one of the following conditions
298
* @li All of the data in the supplied buffers has been written. That is, the
299
* bytes transferred is equal to the sum of the buffer sizes.
301
* @li An error occurred.
303
* This operation is implemented in terms of one or more calls to the stream's
304
* async_write_some function.
306
* @param s The stream to which the data is to be written. The type must support
307
* the AsyncWriteStream concept.
309
* @param buffers One or more buffers containing the data to be written.
310
* Although the buffers object may be copied as necessary, ownership of the
311
* underlying memory blocks is retained by the caller, which must guarantee
312
* that they remain valid until the handler is called.
314
* @param handler The handler to be called when the write operation completes.
315
* Copies will be made of the handler as required. The function signature of
316
* the handler must be:
317
* @code void handler(
318
* const asio::error_code& error, // Result of operation.
320
* std::size_t bytes_transferred // Number of bytes written from the
321
* // buffers. If an error occurred,
322
* // this will be less than the sum
323
* // of the buffer sizes.
325
* Regardless of whether the asynchronous operation completes immediately or
326
* not, the handler will not be invoked from within this function. Invocation of
327
* the handler will be performed in a manner equivalent to using
328
* asio::io_service::post().
331
* To write a single data buffer use the @ref buffer function as follows:
333
* asio::async_write(s, asio::buffer(data, size), handler);
335
* See the @ref buffer documentation for information on writing multiple
336
* buffers in one go, and how to use it with arrays, boost::array or
339
template <typename AsyncWriteStream, typename ConstBufferSequence,
340
typename WriteHandler>
341
void async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
342
WriteHandler handler);
344
/// Start an asynchronous operation to write a certain amount of data to a
347
* This function is used to asynchronously write a certain number of bytes of
348
* data to a stream. The function call always returns immediately. The
349
* asynchronous operation will continue until one of the following conditions
352
* @li All of the data in the supplied buffers has been written. That is, the
353
* bytes transferred is equal to the sum of the buffer sizes.
355
* @li The completion_condition function object returns true.
357
* This operation is implemented in terms of one or more calls to the stream's
358
* async_write_some function.
360
* @param s The stream to which the data is to be written. The type must support
361
* the AsyncWriteStream concept.
363
* @param buffers One or more buffers containing the data to be written.
364
* Although the buffers object may be copied as necessary, ownership of the
365
* underlying memory blocks is retained by the caller, which must guarantee
366
* that they remain valid until the handler is called.
368
* @param completion_condition The function object to be called to determine
369
* whether the write operation is complete. The signature of the function object
371
* @code bool completion_condition(
372
* const asio::error_code& error, // Result of latest write_some
375
* std::size_t bytes_transferred // Number of bytes transferred
378
* A return value of true indicates that the write operation is complete. False
379
* indicates that further calls to the stream's async_write_some function are
382
* @param handler The handler to be called when the write operation completes.
383
* Copies will be made of the handler as required. The function signature of the
385
* @code void handler(
386
* const asio::error_code& error, // Result of operation.
388
* std::size_t bytes_transferred // Number of bytes written from the
389
* // buffers. If an error occurred,
390
* // this will be less than the sum
391
* // of the buffer sizes.
393
* Regardless of whether the asynchronous operation completes immediately or
394
* not, the handler will not be invoked from within this function. Invocation of
395
* the handler will be performed in a manner equivalent to using
396
* asio::io_service::post().
399
* To write a single data buffer use the @ref buffer function as follows:
400
* @code asio::async_write(s,
401
* asio::buffer(data, size),
402
* asio::transfer_at_least(32),
404
* See the @ref buffer documentation for information on writing multiple
405
* buffers in one go, and how to use it with arrays, boost::array or
408
template <typename AsyncWriteStream, typename ConstBufferSequence,
409
typename CompletionCondition, typename WriteHandler>
410
void async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
411
CompletionCondition completion_condition, WriteHandler handler);
413
/// Start an asynchronous operation to write all of the supplied data to a
416
* This function is used to asynchronously write a certain number of bytes of
417
* data to a stream. The function call always returns immediately. The
418
* asynchronous operation will continue until one of the following conditions
421
* @li All of the data in the supplied basic_streambuf has been written.
423
* @li An error occurred.
425
* This operation is implemented in terms of one or more calls to the stream's
426
* async_write_some function.
428
* @param s The stream to which the data is to be written. The type must support
429
* the AsyncWriteStream concept.
431
* @param b A basic_streambuf object from which data will be written. Ownership
432
* of the streambuf is retained by the caller, which must guarantee that it
433
* remains valid until the handler is called.
435
* @param handler The handler to be called when the write operation completes.
436
* Copies will be made of the handler as required. The function signature of the
438
* @code void handler(
439
* const asio::error_code& error, // Result of operation.
441
* std::size_t bytes_transferred // Number of bytes written from the
442
* // buffers. If an error occurred,
443
* // this will be less than the sum
444
* // of the buffer sizes.
446
* Regardless of whether the asynchronous operation completes immediately or
447
* not, the handler will not be invoked from within this function. Invocation of
448
* the handler will be performed in a manner equivalent to using
449
* asio::io_service::post().
451
template <typename AsyncWriteStream, typename Allocator, typename WriteHandler>
452
void async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
453
WriteHandler handler);
455
/// Start an asynchronous operation to write a certain amount of data to a
458
* This function is used to asynchronously write a certain number of bytes of
459
* data to a stream. The function call always returns immediately. The
460
* asynchronous operation will continue until one of the following conditions
463
* @li All of the data in the supplied basic_streambuf has been written.
465
* @li The completion_condition function object returns true.
467
* This operation is implemented in terms of one or more calls to the stream's
468
* async_write_some function.
470
* @param s The stream to which the data is to be written. The type must support
471
* the AsyncWriteStream concept.
473
* @param b A basic_streambuf object from which data will be written. Ownership
474
* of the streambuf is retained by the caller, which must guarantee that it
475
* remains valid until the handler is called.
477
* @param completion_condition The function object to be called to determine
478
* whether the write operation is complete. The signature of the function object
480
* @code bool completion_condition(
481
* const asio::error_code& error, // Result of latest write_some
484
* std::size_t bytes_transferred // Number of bytes transferred
487
* A return value of true indicates that the write operation is complete. False
488
* indicates that further calls to the stream's async_write_some function are
491
* @param handler The handler to be called when the write operation completes.
492
* Copies will be made of the handler as required. The function signature of the
494
* @code void handler(
495
* const asio::error_code& error, // Result of operation.
497
* std::size_t bytes_transferred // Number of bytes written from the
498
* // buffers. If an error occurred,
499
* // this will be less than the sum
500
* // of the buffer sizes.
502
* Regardless of whether the asynchronous operation completes immediately or
503
* not, the handler will not be invoked from within this function. Invocation of
504
* the handler will be performed in a manner equivalent to using
505
* asio::io_service::post().
507
template <typename AsyncWriteStream, typename Allocator,
508
typename CompletionCondition, typename WriteHandler>
509
void async_write(AsyncWriteStream& s, basic_streambuf<Allocator>& b,
510
CompletionCondition completion_condition, WriteHandler handler);
516
#include "asio/impl/write.ipp"
518
#include "asio/detail/pop_options.hpp"
520
#endif // ASIO_WRITE_HPP