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
