]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // basic_stream_socket.hpp | |
3 | // ~~~~~~~~~~~~~~~~~~~~~~~ | |
4 | // | |
b32b8144 | 5 | // Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
7c673cae FG |
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_BASIC_STREAM_SOCKET_HPP | |
12 | #define BOOST_ASIO_BASIC_STREAM_SOCKET_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/config.hpp> | |
19 | #include <cstddef> | |
20 | #include <boost/asio/async_result.hpp> | |
21 | #include <boost/asio/basic_socket.hpp> | |
22 | #include <boost/asio/detail/handler_type_requirements.hpp> | |
23 | #include <boost/asio/detail/throw_error.hpp> | |
24 | #include <boost/asio/error.hpp> | |
b32b8144 FG |
25 | |
26 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
27 | # include <boost/asio/stream_socket_service.hpp> | |
28 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
29 | |
30 | #include <boost/asio/detail/push_options.hpp> | |
31 | ||
32 | namespace boost { | |
33 | namespace asio { | |
34 | ||
35 | /// Provides stream-oriented socket functionality. | |
36 | /** | |
37 | * The basic_stream_socket class template provides asynchronous and blocking | |
38 | * stream-oriented socket functionality. | |
39 | * | |
40 | * @par Thread Safety | |
41 | * @e Distinct @e objects: Safe.@n | |
42 | * @e Shared @e objects: Unsafe. | |
43 | * | |
44 | * @par Concepts: | |
45 | * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream. | |
46 | */ | |
b32b8144 FG |
47 | template <typename Protocol |
48 | BOOST_ASIO_SVC_TPARAM_DEF1(= stream_socket_service<Protocol>)> | |
7c673cae | 49 | class basic_stream_socket |
b32b8144 | 50 | : public basic_socket<Protocol BOOST_ASIO_SVC_TARG> |
7c673cae FG |
51 | { |
52 | public: | |
7c673cae | 53 | /// The native representation of a socket. |
b32b8144 FG |
54 | #if defined(GENERATING_DOCUMENTATION) |
55 | typedef implementation_defined native_handle_type; | |
56 | #else | |
57 | typedef typename basic_socket< | |
58 | Protocol BOOST_ASIO_SVC_TARG>::native_handle_type native_handle_type; | |
59 | #endif | |
7c673cae FG |
60 | |
61 | /// The protocol type. | |
62 | typedef Protocol protocol_type; | |
63 | ||
64 | /// The endpoint type. | |
65 | typedef typename Protocol::endpoint endpoint_type; | |
66 | ||
67 | /// Construct a basic_stream_socket without opening it. | |
68 | /** | |
69 | * This constructor creates a stream socket without opening it. The socket | |
70 | * needs to be opened and then connected or accepted before data can be sent | |
71 | * or received on it. | |
72 | * | |
b32b8144 | 73 | * @param io_context The io_context object that the stream socket will use to |
7c673cae FG |
74 | * dispatch handlers for any asynchronous operations performed on the socket. |
75 | */ | |
b32b8144 FG |
76 | explicit basic_stream_socket(boost::asio::io_context& io_context) |
77 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context) | |
7c673cae FG |
78 | { |
79 | } | |
80 | ||
81 | /// Construct and open a basic_stream_socket. | |
82 | /** | |
83 | * This constructor creates and opens a stream socket. The socket needs to be | |
84 | * connected or accepted before data can be sent or received on it. | |
85 | * | |
b32b8144 | 86 | * @param io_context The io_context object that the stream socket will use to |
7c673cae FG |
87 | * dispatch handlers for any asynchronous operations performed on the socket. |
88 | * | |
89 | * @param protocol An object specifying protocol parameters to be used. | |
90 | * | |
91 | * @throws boost::system::system_error Thrown on failure. | |
92 | */ | |
b32b8144 | 93 | basic_stream_socket(boost::asio::io_context& io_context, |
7c673cae | 94 | const protocol_type& protocol) |
b32b8144 | 95 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context, protocol) |
7c673cae FG |
96 | { |
97 | } | |
98 | ||
99 | /// Construct a basic_stream_socket, opening it and binding it to the given | |
100 | /// local endpoint. | |
101 | /** | |
102 | * This constructor creates a stream socket and automatically opens it bound | |
103 | * to the specified endpoint on the local machine. The protocol used is the | |
104 | * protocol associated with the given endpoint. | |
105 | * | |
b32b8144 | 106 | * @param io_context The io_context object that the stream socket will use to |
7c673cae FG |
107 | * dispatch handlers for any asynchronous operations performed on the socket. |
108 | * | |
109 | * @param endpoint An endpoint on the local machine to which the stream | |
110 | * socket will be bound. | |
111 | * | |
112 | * @throws boost::system::system_error Thrown on failure. | |
113 | */ | |
b32b8144 | 114 | basic_stream_socket(boost::asio::io_context& io_context, |
7c673cae | 115 | const endpoint_type& endpoint) |
b32b8144 | 116 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context, endpoint) |
7c673cae FG |
117 | { |
118 | } | |
119 | ||
120 | /// Construct a basic_stream_socket on an existing native socket. | |
121 | /** | |
122 | * This constructor creates a stream socket object to hold an existing native | |
123 | * socket. | |
124 | * | |
b32b8144 | 125 | * @param io_context The io_context object that the stream socket will use to |
7c673cae FG |
126 | * dispatch handlers for any asynchronous operations performed on the socket. |
127 | * | |
128 | * @param protocol An object specifying protocol parameters to be used. | |
129 | * | |
130 | * @param native_socket The new underlying socket implementation. | |
131 | * | |
132 | * @throws boost::system::system_error Thrown on failure. | |
133 | */ | |
b32b8144 | 134 | basic_stream_socket(boost::asio::io_context& io_context, |
7c673cae | 135 | const protocol_type& protocol, const native_handle_type& native_socket) |
b32b8144 FG |
136 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>( |
137 | io_context, protocol, native_socket) | |
7c673cae FG |
138 | { |
139 | } | |
140 | ||
141 | #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) | |
142 | /// Move-construct a basic_stream_socket from another. | |
143 | /** | |
144 | * This constructor moves a stream socket from one object to another. | |
145 | * | |
146 | * @param other The other basic_stream_socket object from which the move | |
147 | * will occur. | |
148 | * | |
149 | * @note Following the move, the moved-from object is in the same state as if | |
b32b8144 | 150 | * constructed using the @c basic_stream_socket(io_context&) constructor. |
7c673cae FG |
151 | */ |
152 | basic_stream_socket(basic_stream_socket&& other) | |
b32b8144 | 153 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(std::move(other)) |
7c673cae FG |
154 | { |
155 | } | |
156 | ||
157 | /// Move-assign a basic_stream_socket from another. | |
158 | /** | |
159 | * This assignment operator moves a stream socket from one object to another. | |
160 | * | |
161 | * @param other The other basic_stream_socket object from which the move | |
162 | * will occur. | |
163 | * | |
164 | * @note Following the move, the moved-from object is in the same state as if | |
b32b8144 | 165 | * constructed using the @c basic_stream_socket(io_context&) constructor. |
7c673cae FG |
166 | */ |
167 | basic_stream_socket& operator=(basic_stream_socket&& other) | |
168 | { | |
b32b8144 | 169 | basic_socket<Protocol BOOST_ASIO_SVC_TARG>::operator=(std::move(other)); |
7c673cae FG |
170 | return *this; |
171 | } | |
172 | ||
173 | /// Move-construct a basic_stream_socket from a socket of another protocol | |
174 | /// type. | |
175 | /** | |
176 | * This constructor moves a stream socket from one object to another. | |
177 | * | |
178 | * @param other The other basic_stream_socket object from which the move | |
179 | * will occur. | |
180 | * | |
181 | * @note Following the move, the moved-from object is in the same state as if | |
b32b8144 | 182 | * constructed using the @c basic_stream_socket(io_context&) constructor. |
7c673cae | 183 | */ |
b32b8144 | 184 | template <typename Protocol1 BOOST_ASIO_SVC_TPARAM1> |
7c673cae | 185 | basic_stream_socket( |
b32b8144 | 186 | basic_stream_socket<Protocol1 BOOST_ASIO_SVC_TARG1>&& other, |
7c673cae | 187 | typename enable_if<is_convertible<Protocol1, Protocol>::value>::type* = 0) |
b32b8144 | 188 | : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(std::move(other)) |
7c673cae FG |
189 | { |
190 | } | |
191 | ||
192 | /// Move-assign a basic_stream_socket from a socket of another protocol type. | |
193 | /** | |
194 | * This assignment operator moves a stream socket from one object to another. | |
195 | * | |
196 | * @param other The other basic_stream_socket object from which the move | |
197 | * will occur. | |
198 | * | |
199 | * @note Following the move, the moved-from object is in the same state as if | |
b32b8144 | 200 | * constructed using the @c basic_stream_socket(io_context&) constructor. |
7c673cae | 201 | */ |
b32b8144 | 202 | template <typename Protocol1 BOOST_ASIO_SVC_TPARAM1> |
7c673cae FG |
203 | typename enable_if<is_convertible<Protocol1, Protocol>::value, |
204 | basic_stream_socket>::type& operator=( | |
b32b8144 | 205 | basic_stream_socket<Protocol1 BOOST_ASIO_SVC_TARG1>&& other) |
7c673cae | 206 | { |
b32b8144 | 207 | basic_socket<Protocol BOOST_ASIO_SVC_TARG>::operator=(std::move(other)); |
7c673cae FG |
208 | return *this; |
209 | } | |
210 | #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) | |
211 | ||
b32b8144 FG |
212 | /// Destroys the socket. |
213 | /** | |
214 | * This function destroys the socket, cancelling any outstanding asynchronous | |
215 | * operations associated with the socket as if by calling @c cancel. | |
216 | */ | |
217 | ~basic_stream_socket() | |
218 | { | |
219 | } | |
220 | ||
7c673cae FG |
221 | /// Send some data on the socket. |
222 | /** | |
223 | * This function is used to send data on the stream socket. The function | |
224 | * call will block until one or more bytes of the data has been sent | |
225 | * successfully, or an until error occurs. | |
226 | * | |
227 | * @param buffers One or more data buffers to be sent on the socket. | |
228 | * | |
229 | * @returns The number of bytes sent. | |
230 | * | |
231 | * @throws boost::system::system_error Thrown on failure. | |
232 | * | |
233 | * @note The send operation may not transmit all of the data to the peer. | |
234 | * Consider using the @ref write function if you need to ensure that all data | |
235 | * is written before the blocking operation completes. | |
236 | * | |
237 | * @par Example | |
238 | * To send a single data buffer use the @ref buffer function as follows: | |
239 | * @code | |
240 | * socket.send(boost::asio::buffer(data, size)); | |
241 | * @endcode | |
242 | * See the @ref buffer documentation for information on sending multiple | |
243 | * buffers in one go, and how to use it with arrays, boost::array or | |
244 | * std::vector. | |
245 | */ | |
246 | template <typename ConstBufferSequence> | |
247 | std::size_t send(const ConstBufferSequence& buffers) | |
248 | { | |
249 | boost::system::error_code ec; | |
250 | std::size_t s = this->get_service().send( | |
251 | this->get_implementation(), buffers, 0, ec); | |
252 | boost::asio::detail::throw_error(ec, "send"); | |
253 | return s; | |
254 | } | |
255 | ||
256 | /// Send some data on the socket. | |
257 | /** | |
258 | * This function is used to send data on the stream socket. The function | |
259 | * call will block until one or more bytes of the data has been sent | |
260 | * successfully, or an until error occurs. | |
261 | * | |
262 | * @param buffers One or more data buffers to be sent on the socket. | |
263 | * | |
264 | * @param flags Flags specifying how the send call is to be made. | |
265 | * | |
266 | * @returns The number of bytes sent. | |
267 | * | |
268 | * @throws boost::system::system_error Thrown on failure. | |
269 | * | |
270 | * @note The send operation may not transmit all of the data to the peer. | |
271 | * Consider using the @ref write function if you need to ensure that all data | |
272 | * is written before the blocking operation completes. | |
273 | * | |
274 | * @par Example | |
275 | * To send a single data buffer use the @ref buffer function as follows: | |
276 | * @code | |
277 | * socket.send(boost::asio::buffer(data, size), 0); | |
278 | * @endcode | |
279 | * See the @ref buffer documentation for information on sending multiple | |
280 | * buffers in one go, and how to use it with arrays, boost::array or | |
281 | * std::vector. | |
282 | */ | |
283 | template <typename ConstBufferSequence> | |
284 | std::size_t send(const ConstBufferSequence& buffers, | |
285 | socket_base::message_flags flags) | |
286 | { | |
287 | boost::system::error_code ec; | |
288 | std::size_t s = this->get_service().send( | |
289 | this->get_implementation(), buffers, flags, ec); | |
290 | boost::asio::detail::throw_error(ec, "send"); | |
291 | return s; | |
292 | } | |
293 | ||
294 | /// Send some data on the socket. | |
295 | /** | |
296 | * This function is used to send data on the stream socket. The function | |
297 | * call will block until one or more bytes of the data has been sent | |
298 | * successfully, or an until error occurs. | |
299 | * | |
300 | * @param buffers One or more data buffers to be sent on the socket. | |
301 | * | |
302 | * @param flags Flags specifying how the send call is to be made. | |
303 | * | |
304 | * @param ec Set to indicate what error occurred, if any. | |
305 | * | |
306 | * @returns The number of bytes sent. Returns 0 if an error occurred. | |
307 | * | |
308 | * @note The send operation may not transmit all of the data to the peer. | |
309 | * Consider using the @ref write function if you need to ensure that all data | |
310 | * is written before the blocking operation completes. | |
311 | */ | |
312 | template <typename ConstBufferSequence> | |
313 | std::size_t send(const ConstBufferSequence& buffers, | |
314 | socket_base::message_flags flags, boost::system::error_code& ec) | |
315 | { | |
316 | return this->get_service().send( | |
317 | this->get_implementation(), buffers, flags, ec); | |
318 | } | |
319 | ||
320 | /// Start an asynchronous send. | |
321 | /** | |
322 | * This function is used to asynchronously send data on the stream socket. | |
323 | * The function call always returns immediately. | |
324 | * | |
325 | * @param buffers One or more data buffers to be sent on the socket. Although | |
326 | * the buffers object may be copied as necessary, ownership of the underlying | |
327 | * memory blocks is retained by the caller, which must guarantee that they | |
328 | * remain valid until the handler is called. | |
329 | * | |
330 | * @param handler The handler to be called when the send operation completes. | |
331 | * Copies will be made of the handler as required. The function signature of | |
332 | * the handler must be: | |
333 | * @code void handler( | |
334 | * const boost::system::error_code& error, // Result of operation. | |
335 | * std::size_t bytes_transferred // Number of bytes sent. | |
336 | * ); @endcode | |
337 | * Regardless of whether the asynchronous operation completes immediately or | |
338 | * not, the handler will not be invoked from within this function. Invocation | |
339 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 340 | * boost::asio::io_context::post(). |
7c673cae FG |
341 | * |
342 | * @note The send operation may not transmit all of the data to the peer. | |
343 | * Consider using the @ref async_write function if you need to ensure that all | |
344 | * data is written before the asynchronous operation completes. | |
345 | * | |
346 | * @par Example | |
347 | * To send a single data buffer use the @ref buffer function as follows: | |
348 | * @code | |
349 | * socket.async_send(boost::asio::buffer(data, size), handler); | |
350 | * @endcode | |
351 | * See the @ref buffer documentation for information on sending multiple | |
352 | * buffers in one go, and how to use it with arrays, boost::array or | |
353 | * std::vector. | |
354 | */ | |
355 | template <typename ConstBufferSequence, typename WriteHandler> | |
356 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
357 | void (boost::system::error_code, std::size_t)) | |
358 | async_send(const ConstBufferSequence& buffers, | |
359 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler) | |
360 | { | |
361 | // If you get an error on the following line it means that your handler does | |
362 | // not meet the documented type requirements for a WriteHandler. | |
363 | BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check; | |
364 | ||
b32b8144 | 365 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
366 | return this->get_service().async_send( |
367 | this->get_implementation(), buffers, 0, | |
368 | BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); | |
b32b8144 FG |
369 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
370 | async_completion<WriteHandler, | |
371 | void (boost::system::error_code, std::size_t)> init(handler); | |
372 | ||
373 | this->get_service().async_send( | |
374 | this->get_implementation(), buffers, 0, | |
375 | init.completion_handler); | |
376 | ||
377 | return init.result.get(); | |
378 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
379 | } |
380 | ||
381 | /// Start an asynchronous send. | |
382 | /** | |
383 | * This function is used to asynchronously send data on the stream socket. | |
384 | * The function call always returns immediately. | |
385 | * | |
386 | * @param buffers One or more data buffers to be sent on the socket. Although | |
387 | * the buffers object may be copied as necessary, ownership of the underlying | |
388 | * memory blocks is retained by the caller, which must guarantee that they | |
389 | * remain valid until the handler is called. | |
390 | * | |
391 | * @param flags Flags specifying how the send call is to be made. | |
392 | * | |
393 | * @param handler The handler to be called when the send operation completes. | |
394 | * Copies will be made of the handler as required. The function signature of | |
395 | * the handler must be: | |
396 | * @code void handler( | |
397 | * const boost::system::error_code& error, // Result of operation. | |
398 | * std::size_t bytes_transferred // Number of bytes sent. | |
399 | * ); @endcode | |
400 | * Regardless of whether the asynchronous operation completes immediately or | |
401 | * not, the handler will not be invoked from within this function. Invocation | |
402 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 403 | * boost::asio::io_context::post(). |
7c673cae FG |
404 | * |
405 | * @note The send operation may not transmit all of the data to the peer. | |
406 | * Consider using the @ref async_write function if you need to ensure that all | |
407 | * data is written before the asynchronous operation completes. | |
408 | * | |
409 | * @par Example | |
410 | * To send a single data buffer use the @ref buffer function as follows: | |
411 | * @code | |
412 | * socket.async_send(boost::asio::buffer(data, size), 0, handler); | |
413 | * @endcode | |
414 | * See the @ref buffer documentation for information on sending multiple | |
415 | * buffers in one go, and how to use it with arrays, boost::array or | |
416 | * std::vector. | |
417 | */ | |
418 | template <typename ConstBufferSequence, typename WriteHandler> | |
419 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
420 | void (boost::system::error_code, std::size_t)) | |
421 | async_send(const ConstBufferSequence& buffers, | |
422 | socket_base::message_flags flags, | |
423 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler) | |
424 | { | |
425 | // If you get an error on the following line it means that your handler does | |
426 | // not meet the documented type requirements for a WriteHandler. | |
427 | BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check; | |
428 | ||
b32b8144 | 429 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
430 | return this->get_service().async_send( |
431 | this->get_implementation(), buffers, flags, | |
432 | BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); | |
b32b8144 FG |
433 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
434 | async_completion<WriteHandler, | |
435 | void (boost::system::error_code, std::size_t)> init(handler); | |
436 | ||
437 | this->get_service().async_send( | |
438 | this->get_implementation(), buffers, flags, | |
439 | init.completion_handler); | |
440 | ||
441 | return init.result.get(); | |
442 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
443 | } |
444 | ||
445 | /// Receive some data on the socket. | |
446 | /** | |
447 | * This function is used to receive data on the stream socket. The function | |
448 | * call will block until one or more bytes of data has been received | |
449 | * successfully, or until an error occurs. | |
450 | * | |
451 | * @param buffers One or more buffers into which the data will be received. | |
452 | * | |
453 | * @returns The number of bytes received. | |
454 | * | |
455 | * @throws boost::system::system_error Thrown on failure. An error code of | |
456 | * boost::asio::error::eof indicates that the connection was closed by the | |
457 | * peer. | |
458 | * | |
459 | * @note The receive operation may not receive all of the requested number of | |
460 | * bytes. Consider using the @ref read function if you need to ensure that the | |
461 | * requested amount of data is read before the blocking operation completes. | |
462 | * | |
463 | * @par Example | |
464 | * To receive into a single data buffer use the @ref buffer function as | |
465 | * follows: | |
466 | * @code | |
467 | * socket.receive(boost::asio::buffer(data, size)); | |
468 | * @endcode | |
469 | * See the @ref buffer documentation for information on receiving into | |
470 | * multiple buffers in one go, and how to use it with arrays, boost::array or | |
471 | * std::vector. | |
472 | */ | |
473 | template <typename MutableBufferSequence> | |
474 | std::size_t receive(const MutableBufferSequence& buffers) | |
475 | { | |
476 | boost::system::error_code ec; | |
477 | std::size_t s = this->get_service().receive( | |
478 | this->get_implementation(), buffers, 0, ec); | |
479 | boost::asio::detail::throw_error(ec, "receive"); | |
480 | return s; | |
481 | } | |
482 | ||
483 | /// Receive some data on the socket. | |
484 | /** | |
485 | * This function is used to receive data on the stream socket. The function | |
486 | * call will block until one or more bytes of data has been received | |
487 | * successfully, or until an error occurs. | |
488 | * | |
489 | * @param buffers One or more buffers into which the data will be received. | |
490 | * | |
491 | * @param flags Flags specifying how the receive call is to be made. | |
492 | * | |
493 | * @returns The number of bytes received. | |
494 | * | |
495 | * @throws boost::system::system_error Thrown on failure. An error code of | |
496 | * boost::asio::error::eof indicates that the connection was closed by the | |
497 | * peer. | |
498 | * | |
499 | * @note The receive operation may not receive all of the requested number of | |
500 | * bytes. Consider using the @ref read function if you need to ensure that the | |
501 | * requested amount of data is read before the blocking operation completes. | |
502 | * | |
503 | * @par Example | |
504 | * To receive into a single data buffer use the @ref buffer function as | |
505 | * follows: | |
506 | * @code | |
507 | * socket.receive(boost::asio::buffer(data, size), 0); | |
508 | * @endcode | |
509 | * See the @ref buffer documentation for information on receiving into | |
510 | * multiple buffers in one go, and how to use it with arrays, boost::array or | |
511 | * std::vector. | |
512 | */ | |
513 | template <typename MutableBufferSequence> | |
514 | std::size_t receive(const MutableBufferSequence& buffers, | |
515 | socket_base::message_flags flags) | |
516 | { | |
517 | boost::system::error_code ec; | |
518 | std::size_t s = this->get_service().receive( | |
519 | this->get_implementation(), buffers, flags, ec); | |
520 | boost::asio::detail::throw_error(ec, "receive"); | |
521 | return s; | |
522 | } | |
523 | ||
524 | /// Receive some data on a connected socket. | |
525 | /** | |
526 | * This function is used to receive data on the stream socket. The function | |
527 | * call will block until one or more bytes of data has been received | |
528 | * successfully, or until an error occurs. | |
529 | * | |
530 | * @param buffers One or more buffers into which the data will be received. | |
531 | * | |
532 | * @param flags Flags specifying how the receive call is to be made. | |
533 | * | |
534 | * @param ec Set to indicate what error occurred, if any. | |
535 | * | |
536 | * @returns The number of bytes received. Returns 0 if an error occurred. | |
537 | * | |
538 | * @note The receive operation may not receive all of the requested number of | |
539 | * bytes. Consider using the @ref read function if you need to ensure that the | |
540 | * requested amount of data is read before the blocking operation completes. | |
541 | */ | |
542 | template <typename MutableBufferSequence> | |
543 | std::size_t receive(const MutableBufferSequence& buffers, | |
544 | socket_base::message_flags flags, boost::system::error_code& ec) | |
545 | { | |
546 | return this->get_service().receive( | |
547 | this->get_implementation(), buffers, flags, ec); | |
548 | } | |
549 | ||
550 | /// Start an asynchronous receive. | |
551 | /** | |
552 | * This function is used to asynchronously receive data from the stream | |
553 | * socket. The function call always returns immediately. | |
554 | * | |
555 | * @param buffers One or more buffers into which the data will be received. | |
556 | * Although the buffers object may be copied as necessary, ownership of the | |
557 | * underlying memory blocks is retained by the caller, which must guarantee | |
558 | * that they remain valid until the handler is called. | |
559 | * | |
560 | * @param handler The handler to be called when the receive operation | |
561 | * completes. Copies will be made of the handler as required. The function | |
562 | * signature of the handler must be: | |
563 | * @code void handler( | |
564 | * const boost::system::error_code& error, // Result of operation. | |
565 | * std::size_t bytes_transferred // Number of bytes received. | |
566 | * ); @endcode | |
567 | * Regardless of whether the asynchronous operation completes immediately or | |
568 | * not, the handler will not be invoked from within this function. Invocation | |
569 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 570 | * boost::asio::io_context::post(). |
7c673cae FG |
571 | * |
572 | * @note The receive operation may not receive all of the requested number of | |
573 | * bytes. Consider using the @ref async_read function if you need to ensure | |
574 | * that the requested amount of data is received before the asynchronous | |
575 | * operation completes. | |
576 | * | |
577 | * @par Example | |
578 | * To receive into a single data buffer use the @ref buffer function as | |
579 | * follows: | |
580 | * @code | |
581 | * socket.async_receive(boost::asio::buffer(data, size), handler); | |
582 | * @endcode | |
583 | * See the @ref buffer documentation for information on receiving into | |
584 | * multiple buffers in one go, and how to use it with arrays, boost::array or | |
585 | * std::vector. | |
586 | */ | |
587 | template <typename MutableBufferSequence, typename ReadHandler> | |
588 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, | |
589 | void (boost::system::error_code, std::size_t)) | |
590 | async_receive(const MutableBufferSequence& buffers, | |
591 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler) | |
592 | { | |
593 | // If you get an error on the following line it means that your handler does | |
594 | // not meet the documented type requirements for a ReadHandler. | |
595 | BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check; | |
596 | ||
b32b8144 | 597 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
598 | return this->get_service().async_receive(this->get_implementation(), |
599 | buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); | |
b32b8144 FG |
600 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
601 | async_completion<ReadHandler, | |
602 | void (boost::system::error_code, std::size_t)> init(handler); | |
603 | ||
604 | this->get_service().async_receive(this->get_implementation(), | |
605 | buffers, 0, init.completion_handler); | |
606 | ||
607 | return init.result.get(); | |
608 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
609 | } |
610 | ||
611 | /// Start an asynchronous receive. | |
612 | /** | |
613 | * This function is used to asynchronously receive data from the stream | |
614 | * socket. The function call always returns immediately. | |
615 | * | |
616 | * @param buffers One or more buffers into which the data will be received. | |
617 | * Although the buffers object may be copied as necessary, ownership of the | |
618 | * underlying memory blocks is retained by the caller, which must guarantee | |
619 | * that they remain valid until the handler is called. | |
620 | * | |
621 | * @param flags Flags specifying how the receive call is to be made. | |
622 | * | |
623 | * @param handler The handler to be called when the receive operation | |
624 | * completes. Copies will be made of the handler as required. The function | |
625 | * signature of the handler must be: | |
626 | * @code void handler( | |
627 | * const boost::system::error_code& error, // Result of operation. | |
628 | * std::size_t bytes_transferred // Number of bytes received. | |
629 | * ); @endcode | |
630 | * Regardless of whether the asynchronous operation completes immediately or | |
631 | * not, the handler will not be invoked from within this function. Invocation | |
632 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 633 | * boost::asio::io_context::post(). |
7c673cae FG |
634 | * |
635 | * @note The receive operation may not receive all of the requested number of | |
636 | * bytes. Consider using the @ref async_read function if you need to ensure | |
637 | * that the requested amount of data is received before the asynchronous | |
638 | * operation completes. | |
639 | * | |
640 | * @par Example | |
641 | * To receive into a single data buffer use the @ref buffer function as | |
642 | * follows: | |
643 | * @code | |
644 | * socket.async_receive(boost::asio::buffer(data, size), 0, handler); | |
645 | * @endcode | |
646 | * See the @ref buffer documentation for information on receiving into | |
647 | * multiple buffers in one go, and how to use it with arrays, boost::array or | |
648 | * std::vector. | |
649 | */ | |
650 | template <typename MutableBufferSequence, typename ReadHandler> | |
651 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, | |
652 | void (boost::system::error_code, std::size_t)) | |
653 | async_receive(const MutableBufferSequence& buffers, | |
654 | socket_base::message_flags flags, | |
655 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler) | |
656 | { | |
657 | // If you get an error on the following line it means that your handler does | |
658 | // not meet the documented type requirements for a ReadHandler. | |
659 | BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check; | |
660 | ||
b32b8144 | 661 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
662 | return this->get_service().async_receive(this->get_implementation(), |
663 | buffers, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); | |
b32b8144 FG |
664 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
665 | async_completion<ReadHandler, | |
666 | void (boost::system::error_code, std::size_t)> init(handler); | |
667 | ||
668 | this->get_service().async_receive(this->get_implementation(), | |
669 | buffers, flags, init.completion_handler); | |
670 | ||
671 | return init.result.get(); | |
672 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
673 | } |
674 | ||
675 | /// Write some data to the socket. | |
676 | /** | |
677 | * This function is used to write data to the stream socket. The function call | |
678 | * will block until one or more bytes of the data has been written | |
679 | * successfully, or until an error occurs. | |
680 | * | |
681 | * @param buffers One or more data buffers to be written to the socket. | |
682 | * | |
683 | * @returns The number of bytes written. | |
684 | * | |
685 | * @throws boost::system::system_error Thrown on failure. An error code of | |
686 | * boost::asio::error::eof indicates that the connection was closed by the | |
687 | * peer. | |
688 | * | |
689 | * @note The write_some operation may not transmit all of the data to the | |
690 | * peer. Consider using the @ref write function if you need to ensure that | |
691 | * all data is written before the blocking operation completes. | |
692 | * | |
693 | * @par Example | |
694 | * To write a single data buffer use the @ref buffer function as follows: | |
695 | * @code | |
696 | * socket.write_some(boost::asio::buffer(data, size)); | |
697 | * @endcode | |
698 | * See the @ref buffer documentation for information on writing multiple | |
699 | * buffers in one go, and how to use it with arrays, boost::array or | |
700 | * std::vector. | |
701 | */ | |
702 | template <typename ConstBufferSequence> | |
703 | std::size_t write_some(const ConstBufferSequence& buffers) | |
704 | { | |
705 | boost::system::error_code ec; | |
706 | std::size_t s = this->get_service().send( | |
707 | this->get_implementation(), buffers, 0, ec); | |
708 | boost::asio::detail::throw_error(ec, "write_some"); | |
709 | return s; | |
710 | } | |
711 | ||
712 | /// Write some data to the socket. | |
713 | /** | |
714 | * This function is used to write data to the stream socket. The function call | |
715 | * will block until one or more bytes of the data has been written | |
716 | * successfully, or until an error occurs. | |
717 | * | |
718 | * @param buffers One or more data buffers to be written to the socket. | |
719 | * | |
720 | * @param ec Set to indicate what error occurred, if any. | |
721 | * | |
722 | * @returns The number of bytes written. Returns 0 if an error occurred. | |
723 | * | |
724 | * @note The write_some operation may not transmit all of the data to the | |
725 | * peer. Consider using the @ref write function if you need to ensure that | |
726 | * all data is written before the blocking operation completes. | |
727 | */ | |
728 | template <typename ConstBufferSequence> | |
729 | std::size_t write_some(const ConstBufferSequence& buffers, | |
730 | boost::system::error_code& ec) | |
731 | { | |
732 | return this->get_service().send(this->get_implementation(), buffers, 0, ec); | |
733 | } | |
734 | ||
735 | /// Start an asynchronous write. | |
736 | /** | |
737 | * This function is used to asynchronously write data to the stream socket. | |
738 | * The function call always returns immediately. | |
739 | * | |
740 | * @param buffers One or more data buffers to be written to the socket. | |
741 | * Although the buffers object may be copied as necessary, ownership of the | |
742 | * underlying memory blocks is retained by the caller, which must guarantee | |
743 | * that they remain valid until the handler is called. | |
744 | * | |
745 | * @param handler The handler to be called when the write operation completes. | |
746 | * Copies will be made of the handler as required. The function signature of | |
747 | * the handler must be: | |
748 | * @code void handler( | |
749 | * const boost::system::error_code& error, // Result of operation. | |
750 | * std::size_t bytes_transferred // Number of bytes written. | |
751 | * ); @endcode | |
752 | * Regardless of whether the asynchronous operation completes immediately or | |
753 | * not, the handler will not be invoked from within this function. Invocation | |
754 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 755 | * boost::asio::io_context::post(). |
7c673cae FG |
756 | * |
757 | * @note The write operation may not transmit all of the data to the peer. | |
758 | * Consider using the @ref async_write function if you need to ensure that all | |
759 | * data is written before the asynchronous operation completes. | |
760 | * | |
761 | * @par Example | |
762 | * To write a single data buffer use the @ref buffer function as follows: | |
763 | * @code | |
764 | * socket.async_write_some(boost::asio::buffer(data, size), handler); | |
765 | * @endcode | |
766 | * See the @ref buffer documentation for information on writing multiple | |
767 | * buffers in one go, and how to use it with arrays, boost::array or | |
768 | * std::vector. | |
769 | */ | |
770 | template <typename ConstBufferSequence, typename WriteHandler> | |
771 | BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler, | |
772 | void (boost::system::error_code, std::size_t)) | |
773 | async_write_some(const ConstBufferSequence& buffers, | |
774 | BOOST_ASIO_MOVE_ARG(WriteHandler) handler) | |
775 | { | |
776 | // If you get an error on the following line it means that your handler does | |
777 | // not meet the documented type requirements for a WriteHandler. | |
778 | BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check; | |
779 | ||
b32b8144 | 780 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
781 | return this->get_service().async_send(this->get_implementation(), |
782 | buffers, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler)); | |
b32b8144 FG |
783 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
784 | async_completion<WriteHandler, | |
785 | void (boost::system::error_code, std::size_t)> init(handler); | |
786 | ||
787 | this->get_service().async_send(this->get_implementation(), | |
788 | buffers, 0, init.completion_handler); | |
789 | ||
790 | return init.result.get(); | |
791 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
792 | } |
793 | ||
794 | /// Read some data from the socket. | |
795 | /** | |
796 | * This function is used to read data from the stream socket. The function | |
797 | * call will block until one or more bytes of data has been read successfully, | |
798 | * or until an error occurs. | |
799 | * | |
800 | * @param buffers One or more buffers into which the data will be read. | |
801 | * | |
802 | * @returns The number of bytes read. | |
803 | * | |
804 | * @throws boost::system::system_error Thrown on failure. An error code of | |
805 | * boost::asio::error::eof indicates that the connection was closed by the | |
806 | * peer. | |
807 | * | |
808 | * @note The read_some operation may not read all of the requested number of | |
809 | * bytes. Consider using the @ref read function if you need to ensure that | |
810 | * the requested amount of data is read before the blocking operation | |
811 | * completes. | |
812 | * | |
813 | * @par Example | |
814 | * To read into a single data buffer use the @ref buffer function as follows: | |
815 | * @code | |
816 | * socket.read_some(boost::asio::buffer(data, size)); | |
817 | * @endcode | |
818 | * See the @ref buffer documentation for information on reading into multiple | |
819 | * buffers in one go, and how to use it with arrays, boost::array or | |
820 | * std::vector. | |
821 | */ | |
822 | template <typename MutableBufferSequence> | |
823 | std::size_t read_some(const MutableBufferSequence& buffers) | |
824 | { | |
825 | boost::system::error_code ec; | |
826 | std::size_t s = this->get_service().receive( | |
827 | this->get_implementation(), buffers, 0, ec); | |
828 | boost::asio::detail::throw_error(ec, "read_some"); | |
829 | return s; | |
830 | } | |
831 | ||
832 | /// Read some data from the socket. | |
833 | /** | |
834 | * This function is used to read data from the stream socket. The function | |
835 | * call will block until one or more bytes of data has been read successfully, | |
836 | * or until an error occurs. | |
837 | * | |
838 | * @param buffers One or more buffers into which the data will be read. | |
839 | * | |
840 | * @param ec Set to indicate what error occurred, if any. | |
841 | * | |
842 | * @returns The number of bytes read. Returns 0 if an error occurred. | |
843 | * | |
844 | * @note The read_some operation may not read all of the requested number of | |
845 | * bytes. Consider using the @ref read function if you need to ensure that | |
846 | * the requested amount of data is read before the blocking operation | |
847 | * completes. | |
848 | */ | |
849 | template <typename MutableBufferSequence> | |
850 | std::size_t read_some(const MutableBufferSequence& buffers, | |
851 | boost::system::error_code& ec) | |
852 | { | |
853 | return this->get_service().receive( | |
854 | this->get_implementation(), buffers, 0, ec); | |
855 | } | |
856 | ||
857 | /// Start an asynchronous read. | |
858 | /** | |
859 | * This function is used to asynchronously read data from the stream socket. | |
860 | * The function call always returns immediately. | |
861 | * | |
862 | * @param buffers One or more buffers into which the data will be read. | |
863 | * Although the buffers object may be copied as necessary, ownership of the | |
864 | * underlying memory blocks is retained by the caller, which must guarantee | |
865 | * that they remain valid until the handler is called. | |
866 | * | |
867 | * @param handler The handler to be called when the read operation completes. | |
868 | * Copies will be made of the handler as required. The function signature of | |
869 | * the handler must be: | |
870 | * @code void handler( | |
871 | * const boost::system::error_code& error, // Result of operation. | |
872 | * std::size_t bytes_transferred // Number of bytes read. | |
873 | * ); @endcode | |
874 | * Regardless of whether the asynchronous operation completes immediately or | |
875 | * not, the handler will not be invoked from within this function. Invocation | |
876 | * of the handler will be performed in a manner equivalent to using | |
b32b8144 | 877 | * boost::asio::io_context::post(). |
7c673cae FG |
878 | * |
879 | * @note The read operation may not read all of the requested number of bytes. | |
880 | * Consider using the @ref async_read function if you need to ensure that the | |
881 | * requested amount of data is read before the asynchronous operation | |
882 | * completes. | |
883 | * | |
884 | * @par Example | |
885 | * To read into a single data buffer use the @ref buffer function as follows: | |
886 | * @code | |
887 | * socket.async_read_some(boost::asio::buffer(data, size), handler); | |
888 | * @endcode | |
889 | * See the @ref buffer documentation for information on reading into multiple | |
890 | * buffers in one go, and how to use it with arrays, boost::array or | |
891 | * std::vector. | |
892 | */ | |
893 | template <typename MutableBufferSequence, typename ReadHandler> | |
894 | BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, | |
895 | void (boost::system::error_code, std::size_t)) | |
896 | async_read_some(const MutableBufferSequence& buffers, | |
897 | BOOST_ASIO_MOVE_ARG(ReadHandler) handler) | |
898 | { | |
899 | // If you get an error on the following line it means that your handler does | |
900 | // not meet the documented type requirements for a ReadHandler. | |
901 | BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check; | |
902 | ||
b32b8144 | 903 | #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
7c673cae FG |
904 | return this->get_service().async_receive(this->get_implementation(), |
905 | buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler)); | |
b32b8144 FG |
906 | #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) |
907 | async_completion<ReadHandler, | |
908 | void (boost::system::error_code, std::size_t)> init(handler); | |
909 | ||
910 | this->get_service().async_receive(this->get_implementation(), | |
911 | buffers, 0, init.completion_handler); | |
912 | ||
913 | return init.result.get(); | |
914 | #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES) | |
7c673cae FG |
915 | } |
916 | }; | |
917 | ||
918 | } // namespace asio | |
919 | } // namespace boost | |
920 | ||
921 | #include <boost/asio/detail/pop_options.hpp> | |
922 | ||
923 | #endif // BOOST_ASIO_BASIC_STREAM_SOCKET_HPP |