write.hpp revision 0ee85db398be8ea33d67cc42f99a1468cd6c8180 
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 ASIO_WRITE_HPP
12#define ASIO_WRITE_HPP
13
14
15#include "asio/detail/config.hpp"
16#include <cstddef>
17#include "asio/async_result.hpp"
18#include "asio/basic_streambuf_fwd.hpp"
19#include "asio/error.hpp"
20
21#include "asio/detail/push_options.hpp"
22
23namespace asio {
24
25/**
26 * @defgroup write asio::write
27 *
28 * @brief Write a certain amount of data to a stream before returning.
29 */
30/*@{*/
31
32/// Write all of the supplied data to a stream before returning.
33/**
34 * This function is used to write a certain number of bytes of data to a stream.
35 * The call will block until one of the following conditions is true:
36 *
37 * @li All of the data in the supplied buffers has been written. That is, the
38 * bytes transferred is equal to the sum of the buffer sizes.
39 *
40 * @li An error occurred.
41 *
42 * This operation is implemented in terms of zero or more calls to the stream's
43 * write_some function.
44 *
45 * @param s The stream to which the data is to be written. The type must support
46 * the SyncWriteStream concept.
47 *
48 * @param buffers One or more buffers containing the data to be written. The sum
49 * of the buffer sizes indicates the maximum number of bytes to write to the
50 * stream.
51 *
52 * @returns The number of bytes transferred.
53 *
54 * @throws asio::system_error Thrown on failure.
55 *
56 * @par Example
57 * To write a single data buffer use the @ref buffer function as follows:
58 * @code asio::write(s, asio::buffer(data, size)); @endcode
59 * See the @ref buffer documentation for information on writing multiple
60 * buffers in one go, and how to use it with arrays, boost::array or
61 * std::vector.
62 *
63 * @note This overload is equivalent to calling:
64 * @code asio::write(
65 *     s, buffers,
66 *     asio::transfer_all()); @endcode
67 */
68template <typename SyncWriteStream, typename ConstBufferSequence>
69std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers);
70
71/// Write all of the supplied data to a stream before returning.
72/**
73 * This function is used to write a certain number of bytes of data to a stream.
74 * The call will block until one of the following conditions is true:
75 *
76 * @li All of the data in the supplied buffers has been written. That is, the
77 * bytes transferred is equal to the sum of the buffer sizes.
78 *
79 * @li An error occurred.
80 *
81 * This operation is implemented in terms of zero or more calls to the stream's
82 * write_some function.
83 *
84 * @param s The stream to which the data is to be written. The type must support
85 * the SyncWriteStream concept.
86 *
87 * @param buffers One or more buffers containing the data to be written. The sum
88 * of the buffer sizes indicates the maximum number of bytes to write to the
89 * stream.
90 *
91 * @param ec Set to indicate what error occurred, if any.
92 *
93 * @returns The number of bytes transferred.
94 *
95 * @par Example
96 * To write a single data buffer use the @ref buffer function as follows:
97 * @code asio::write(s, asio::buffer(data, size), ec); @endcode
98 * See the @ref buffer documentation for information on writing multiple
99 * buffers in one go, and how to use it with arrays, boost::array or
100 * std::vector.
101 *
102 * @note This overload is equivalent to calling:
103 * @code asio::write(
104 *     s, buffers,
105 *     asio::transfer_all(), ec); @endcode
106 */
107template <typename SyncWriteStream, typename ConstBufferSequence>
108std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
109    asio::error_code& ec);
110
111/// Write a certain amount of data to a stream before returning.
112/**
113 * This function is used to write a certain number of bytes of data to a stream.
114 * The call will block until one of the following conditions is true:
115 *
116 * @li All of the data in the supplied buffers has been written. That is, the
117 * bytes transferred is equal to the sum of the buffer sizes.
118 *
119 * @li The completion_condition function object returns 0.
120 *
121 * This operation is implemented in terms of zero or more calls to the stream's
122 * write_some function.
123 *
124 * @param s The stream to which the data is to be written. The type must support
125 * the SyncWriteStream concept.
126 *
127 * @param buffers One or more buffers containing the data to be written. The sum
128 * of the buffer sizes indicates the maximum number of bytes to write to the
129 * stream.
130 *
131 * @param completion_condition The function object to be called to determine
132 * whether the write operation is complete. The signature of the function object
133 * must be:
134 * @code std::size_t completion_condition(
135 *   // Result of latest write_some operation.
136 *   const asio::error_code& error,
137 *
138 *   // Number of bytes transferred so far.
139 *   std::size_t bytes_transferred
140 * ); @endcode
141 * A return value of 0 indicates that the write operation is complete. A
142 * non-zero return value indicates the maximum number of bytes to be written on
143 * the next call to the stream's write_some function.
144 *
145 * @returns The number of bytes transferred.
146 *
147 * @throws asio::system_error Thrown on failure.
148 *
149 * @par Example
150 * To write a single data buffer use the @ref buffer function as follows:
151 * @code asio::write(s, asio::buffer(data, size),
152 *     asio::transfer_at_least(32)); @endcode
153 * See the @ref buffer documentation for information on writing multiple
154 * buffers in one go, and how to use it with arrays, boost::array or
155 * std::vector.
156 */
157template <typename SyncWriteStream, typename ConstBufferSequence,
158    typename CompletionCondition>
159std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
160    CompletionCondition completion_condition);
161
162/// Write a certain amount of data to a stream before returning.
163/**
164 * This function is used to write a certain number of bytes of data to a stream.
165 * The call will block until one of the following conditions is true:
166 *
167 * @li All of the data in the supplied buffers has been written. That is, the
168 * bytes transferred is equal to the sum of the buffer sizes.
169 *
170 * @li The completion_condition function object returns 0.
171 *
172 * This operation is implemented in terms of zero or more calls to the stream's
173 * write_some function.
174 *
175 * @param s The stream to which the data is to be written. The type must support
176 * the SyncWriteStream concept.
177 *
178 * @param buffers One or more buffers containing the data to be written. The sum
179 * of the buffer sizes indicates the maximum number of bytes to write to the
180 * stream.
181 *
182 * @param completion_condition The function object to be called to determine
183 * whether the write operation is complete. The signature of the function object
184 * must be:
185 * @code std::size_t completion_condition(
186 *   // Result of latest write_some operation.
187 *   const asio::error_code& error,
188 *
189 *   // Number of bytes transferred so far.
190 *   std::size_t bytes_transferred
191 * ); @endcode
192 * A return value of 0 indicates that the write operation is complete. A
193 * non-zero return value indicates the maximum number of bytes to be written on
194 * the next call to the stream's write_some function.
195 *
196 * @param ec Set to indicate what error occurred, if any.
197 *
198 * @returns The number of bytes written. If an error occurs, returns the total
199 * number of bytes successfully transferred prior to the error.
200 */
201template <typename SyncWriteStream, typename ConstBufferSequence,
202    typename CompletionCondition>
203std::size_t write(SyncWriteStream& s, const ConstBufferSequence& buffers,
204    CompletionCondition completion_condition, asio::error_code& ec);
205
206
207/*@}*/
208/**
209 * @defgroup async_write asio::async_write
210 *
211 * @brief Start an asynchronous operation to write a certain amount of data to a
212 * stream.
213 */
214/*@{*/
215
216/// Start an asynchronous operation to write all of the supplied data to a
217/// stream.
218/**
219 * This function is used to asynchronously write a certain number of bytes of
220 * data to a stream. The function call always returns immediately. The
221 * asynchronous operation will continue until one of the following conditions
222 * is true:
223 *
224 * @li All of the data in the supplied buffers has been written. That is, the
225 * bytes transferred is equal to the sum of the buffer sizes.
226 *
227 * @li An error occurred.
228 *
229 * This operation is implemented in terms of zero or more calls to the stream's
230 * async_write_some function, and is known as a <em>composed operation</em>. The
231 * program must ensure that the stream performs no other write operations (such
232 * as async_write, the stream's async_write_some function, or any other composed
233 * operations that perform writes) until this operation completes.
234 *
235 * @param s The stream to which the data is to be written. The type must support
236 * the AsyncWriteStream concept.
237 *
238 * @param buffers One or more buffers containing the data to be written.
239 * Although the buffers object may be copied as necessary, ownership of the
240 * underlying memory blocks is retained by the caller, which must guarantee
241 * that they remain valid until the handler is called.
242 *
243 * @param handler The handler to be called when the write operation completes.
244 * Copies will be made of the handler as required. The function signature of
245 * the handler must be:
246 * @code void handler(
247 *   const asio::error_code& error, // Result of operation.
248 *
249 *   std::size_t bytes_transferred           // Number of bytes written from the
250 *                                           // buffers. If an error occurred,
251 *                                           // this will be less than the sum
252 *                                           // of the buffer sizes.
253 * ); @endcode
254 * Regardless of whether the asynchronous operation completes immediately or
255 * not, the handler will not be invoked from within this function. Invocation of
256 * the handler will be performed in a manner equivalent to using
257 * asio::io_service::post().
258 *
259 * @par Example
260 * To write a single data buffer use the @ref buffer function as follows:
261 * @code
262 * asio::async_write(s, asio::buffer(data, size), handler);
263 * @endcode
264 * See the @ref buffer documentation for information on writing multiple
265 * buffers in one go, and how to use it with arrays, boost::array or
266 * std::vector.
267 */
268template <typename AsyncWriteStream, typename ConstBufferSequence,
269    typename WriteHandler>
270ASIO_INITFN_RESULT_TYPE(WriteHandler,
271    void (asio::error_code, std::size_t))
272async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
273    ASIO_MOVE_ARG(WriteHandler) handler);
274
275/// Start an asynchronous operation to write a certain amount of data to a
276/// stream.
277/**
278 * This function is used to asynchronously write a certain number of bytes of
279 * data to a stream. The function call always returns immediately. The
280 * asynchronous operation will continue until one of the following conditions
281 * is true:
282 *
283 * @li All of the data in the supplied buffers has been written. That is, the
284 * bytes transferred is equal to the sum of the buffer sizes.
285 *
286 * @li The completion_condition function object returns 0.
287 *
288 * This operation is implemented in terms of zero or more calls to the stream's
289 * async_write_some function, and is known as a <em>composed operation</em>. The
290 * program must ensure that the stream performs no other write operations (such
291 * as async_write, the stream's async_write_some function, or any other composed
292 * operations that perform writes) until this operation completes.
293 *
294 * @param s The stream to which the data is to be written. The type must support
295 * the AsyncWriteStream concept.
296 *
297 * @param buffers One or more buffers containing the data to be written.
298 * Although the buffers object may be copied as necessary, ownership of the
299 * underlying memory blocks is retained by the caller, which must guarantee
300 * that they remain valid until the handler is called.
301 *
302 * @param completion_condition The function object to be called to determine
303 * whether the write operation is complete. The signature of the function object
304 * must be:
305 * @code std::size_t completion_condition(
306 *   // Result of latest async_write_some operation.
307 *   const asio::error_code& error,
308 *
309 *   // Number of bytes transferred so far.
310 *   std::size_t bytes_transferred
311 * ); @endcode
312 * A return value of 0 indicates that the write operation is complete. A
313 * non-zero return value indicates the maximum number of bytes to be written on
314 * the next call to the stream's async_write_some function.
315 *
316 * @param handler The handler to be called when the write operation completes.
317 * Copies will be made of the handler as required. The function signature of the
318 * handler must be:
319 * @code void handler(
320 *   const asio::error_code& error, // Result of operation.
321 *
322 *   std::size_t bytes_transferred           // Number of bytes written from the
323 *                                           // buffers. If an error occurred,
324 *                                           // this will be less than the sum
325 *                                           // of the buffer sizes.
326 * ); @endcode
327 * Regardless of whether the asynchronous operation completes immediately or
328 * not, the handler will not be invoked from within this function. Invocation of
329 * the handler will be performed in a manner equivalent to using
330 * asio::io_service::post().
331 *
332 * @par Example
333 * To write a single data buffer use the @ref buffer function as follows:
334 * @code asio::async_write(s,
335 *     asio::buffer(data, size),
336 *     asio::transfer_at_least(32),
337 *     handler); @endcode
338 * See the @ref buffer documentation for information on writing multiple
339 * buffers in one go, and how to use it with arrays, boost::array or
340 * std::vector.
341 */
342template <typename AsyncWriteStream, typename ConstBufferSequence,
343    typename CompletionCondition, typename WriteHandler>
344ASIO_INITFN_RESULT_TYPE(WriteHandler,
345    void (asio::error_code, std::size_t))
346async_write(AsyncWriteStream& s, const ConstBufferSequence& buffers,
347    CompletionCondition completion_condition,
348    ASIO_MOVE_ARG(WriteHandler) handler);
349
350
351/*@}*/
352
353} // namespace asio
354
355#include "asio/detail/pop_options.hpp"
356
357#include "asio/impl/write.hpp"
358
359#endif // ASIO_WRITE_HPP
360