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 
23 namespace 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  */
68 template <typename SyncWriteStream, typename ConstBufferSequence>
69 std::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  */
107 template <typename SyncWriteStream, typename ConstBufferSequence>
108 std::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  */
157 template <typename SyncWriteStream, typename ConstBufferSequence,
158     typename CompletionCondition>
159 std::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  */
201 template <typename SyncWriteStream, typename ConstBufferSequence,
202     typename CompletionCondition>
203 std::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  */
268 template <typename AsyncWriteStream, typename ConstBufferSequence,
269     typename WriteHandler>
270 ASIO_INITFN_RESULT_TYPE(WriteHandler,
271     void (asio::error_code, std::size_t))
272 async_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  */
342 template <typename AsyncWriteStream, typename ConstBufferSequence,
343     typename CompletionCondition, typename WriteHandler>
344 ASIO_INITFN_RESULT_TYPE(WriteHandler,
345     void (asio::error_code, std::size_t))
346 async_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