2 // basic_stream_socket.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2019 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 BOOST_ASIO_BASIC_STREAM_SOCKET_HPP
12 #define BOOST_ASIO_BASIC_STREAM_SOCKET_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
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/non_const_lvalue.hpp>
24 #include <boost/asio/detail/throw_error.hpp>
25 #include <boost/asio/error.hpp>
27 #include <boost/asio/detail/push_options.hpp>
32 #if !defined(BOOST_ASIO_BASIC_STREAM_SOCKET_FWD_DECL)
33 #define BOOST_ASIO_BASIC_STREAM_SOCKET_FWD_DECL
35 // Forward declaration with defaulted arguments.
36 template <typename Protocol, typename Executor = executor>
37 class basic_stream_socket;
39 #endif // !defined(BOOST_ASIO_BASIC_STREAM_SOCKET_FWD_DECL)
41 /// Provides stream-oriented socket functionality.
43 * The basic_stream_socket class template provides asynchronous and blocking
44 * stream-oriented socket functionality.
47 * @e Distinct @e objects: Safe.@n
48 * @e Shared @e objects: Unsafe.
51 * AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.
53 template <typename Protocol, typename Executor>
54 class basic_stream_socket
55 : public basic_socket<Protocol, Executor>
58 /// The type of the executor associated with the object.
59 typedef Executor executor_type;
61 /// Rebinds the socket type to another executor.
62 template <typename Executor1>
63 struct rebind_executor
65 /// The socket type when rebound to the specified executor.
66 typedef basic_stream_socket<Protocol, Executor1> other;
69 /// The native representation of a socket.
70 #if defined(GENERATING_DOCUMENTATION)
71 typedef implementation_defined native_handle_type;
73 typedef typename basic_socket<Protocol,
74 Executor>::native_handle_type native_handle_type;
77 /// The protocol type.
78 typedef Protocol protocol_type;
80 /// The endpoint type.
81 typedef typename Protocol::endpoint endpoint_type;
83 /// Construct a basic_stream_socket without opening it.
85 * This constructor creates a stream socket without opening it. The socket
86 * needs to be opened and then connected or accepted before data can be sent
89 * @param ex The I/O executor that the socket will use, by default, to
90 * dispatch handlers for any asynchronous operations performed on the socket.
92 explicit basic_stream_socket(const executor_type& ex)
93 : basic_socket<Protocol, Executor>(ex)
97 /// Construct a basic_stream_socket without opening it.
99 * This constructor creates a stream socket without opening it. The socket
100 * needs to be opened and then connected or accepted before data can be sent
103 * @param context An execution context which provides the I/O executor that
104 * the socket will use, by default, to dispatch handlers for any asynchronous
105 * operations performed on the socket.
107 template <typename ExecutionContext>
108 explicit basic_stream_socket(ExecutionContext& context,
110 is_convertible<ExecutionContext&, execution_context&>::value
112 : basic_socket<Protocol, Executor>(context)
116 /// Construct and open a basic_stream_socket.
118 * This constructor creates and opens a stream socket. The socket needs to be
119 * connected or accepted before data can be sent or received on it.
121 * @param ex The I/O executor that the socket will use, by default, to
122 * dispatch handlers for any asynchronous operations performed on the socket.
124 * @param protocol An object specifying protocol parameters to be used.
126 * @throws boost::system::system_error Thrown on failure.
128 basic_stream_socket(const executor_type& ex, const protocol_type& protocol)
129 : basic_socket<Protocol, Executor>(ex, protocol)
133 /// Construct and open a basic_stream_socket.
135 * This constructor creates and opens a stream socket. The socket needs to be
136 * connected or accepted before data can be sent or received on it.
138 * @param context An execution context which provides the I/O executor that
139 * the socket will use, by default, to dispatch handlers for any asynchronous
140 * operations performed on the socket.
142 * @param protocol An object specifying protocol parameters to be used.
144 * @throws boost::system::system_error Thrown on failure.
146 template <typename ExecutionContext>
147 basic_stream_socket(ExecutionContext& context, const protocol_type& protocol,
149 is_convertible<ExecutionContext&, execution_context&>::value
151 : basic_socket<Protocol, Executor>(context, protocol)
155 /// Construct a basic_stream_socket, opening it and binding it to the given
158 * This constructor creates a stream socket and automatically opens it bound
159 * to the specified endpoint on the local machine. The protocol used is the
160 * protocol associated with the given endpoint.
162 * @param ex The I/O executor that the socket will use, by default, to
163 * dispatch handlers for any asynchronous operations performed on the socket.
165 * @param endpoint An endpoint on the local machine to which the stream
166 * socket will be bound.
168 * @throws boost::system::system_error Thrown on failure.
170 basic_stream_socket(const executor_type& ex, const endpoint_type& endpoint)
171 : basic_socket<Protocol, Executor>(ex, endpoint)
175 /// Construct a basic_stream_socket, opening it and binding it to the given
178 * This constructor creates a stream socket and automatically opens it bound
179 * to the specified endpoint on the local machine. The protocol used is the
180 * protocol associated with the given endpoint.
182 * @param context An execution context which provides the I/O executor that
183 * the socket will use, by default, to dispatch handlers for any asynchronous
184 * operations performed on the socket.
186 * @param endpoint An endpoint on the local machine to which the stream
187 * socket will be bound.
189 * @throws boost::system::system_error Thrown on failure.
191 template <typename ExecutionContext>
192 basic_stream_socket(ExecutionContext& context, const endpoint_type& endpoint,
194 is_convertible<ExecutionContext&, execution_context&>::value
196 : basic_socket<Protocol, Executor>(context, endpoint)
200 /// Construct a basic_stream_socket on an existing native socket.
202 * This constructor creates a stream socket object to hold an existing native
205 * @param ex The I/O executor that the socket will use, by default, to
206 * dispatch handlers for any asynchronous operations performed on the socket.
208 * @param protocol An object specifying protocol parameters to be used.
210 * @param native_socket The new underlying socket implementation.
212 * @throws boost::system::system_error Thrown on failure.
214 basic_stream_socket(const executor_type& ex,
215 const protocol_type& protocol, const native_handle_type& native_socket)
216 : basic_socket<Protocol, Executor>(ex, protocol, native_socket)
220 /// Construct a basic_stream_socket on an existing native socket.
222 * This constructor creates a stream socket object to hold an existing native
225 * @param context An execution context which provides the I/O executor that
226 * the socket will use, by default, to dispatch handlers for any asynchronous
227 * operations performed on the socket.
229 * @param protocol An object specifying protocol parameters to be used.
231 * @param native_socket The new underlying socket implementation.
233 * @throws boost::system::system_error Thrown on failure.
235 template <typename ExecutionContext>
236 basic_stream_socket(ExecutionContext& context,
237 const protocol_type& protocol, const native_handle_type& native_socket,
239 is_convertible<ExecutionContext&, execution_context&>::value
241 : basic_socket<Protocol, Executor>(context, protocol, native_socket)
245 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
246 /// Move-construct a basic_stream_socket from another.
248 * This constructor moves a stream socket from one object to another.
250 * @param other The other basic_stream_socket object from which the move
253 * @note Following the move, the moved-from object is in the same state as if
254 * constructed using the @c basic_stream_socket(const executor_type&)
257 basic_stream_socket(basic_stream_socket&& other) BOOST_ASIO_NOEXCEPT
258 : basic_socket<Protocol, Executor>(std::move(other))
262 /// Move-assign a basic_stream_socket from another.
264 * This assignment operator moves a stream socket from one object to another.
266 * @param other The other basic_stream_socket object from which the move
269 * @note Following the move, the moved-from object is in the same state as if
270 * constructed using the @c basic_stream_socket(const executor_type&)
273 basic_stream_socket& operator=(basic_stream_socket&& other)
275 basic_socket<Protocol, Executor>::operator=(std::move(other));
279 /// Move-construct a basic_stream_socket from a socket of another protocol
282 * This constructor moves a stream socket from one object to another.
284 * @param other The other basic_stream_socket object from which the move
287 * @note Following the move, the moved-from object is in the same state as if
288 * constructed using the @c basic_stream_socket(const executor_type&)
291 template <typename Protocol1, typename Executor1>
292 basic_stream_socket(basic_stream_socket<Protocol1, Executor1>&& other,
294 is_convertible<Protocol1, Protocol>::value
295 && is_convertible<Executor1, Executor>::value
297 : basic_socket<Protocol, Executor>(std::move(other))
301 /// Move-assign a basic_stream_socket from a socket of another protocol type.
303 * This assignment operator moves a stream socket from one object to another.
305 * @param other The other basic_stream_socket object from which the move
308 * @note Following the move, the moved-from object is in the same state as if
309 * constructed using the @c basic_stream_socket(const executor_type&)
312 template <typename Protocol1, typename Executor1>
314 is_convertible<Protocol1, Protocol>::value
315 && is_convertible<Executor1, Executor>::value,
317 >::type operator=(basic_stream_socket<Protocol1, Executor1>&& other)
319 basic_socket<Protocol, Executor>::operator=(std::move(other));
322 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
324 /// Destroys the socket.
326 * This function destroys the socket, cancelling any outstanding asynchronous
327 * operations associated with the socket as if by calling @c cancel.
329 ~basic_stream_socket()
333 /// Send some data on the socket.
335 * This function is used to send data on the stream socket. The function
336 * call will block until one or more bytes of the data has been sent
337 * successfully, or an until error occurs.
339 * @param buffers One or more data buffers to be sent on the socket.
341 * @returns The number of bytes sent.
343 * @throws boost::system::system_error Thrown on failure.
345 * @note The send operation may not transmit all of the data to the peer.
346 * Consider using the @ref write function if you need to ensure that all data
347 * is written before the blocking operation completes.
350 * To send a single data buffer use the @ref buffer function as follows:
352 * socket.send(boost::asio::buffer(data, size));
354 * See the @ref buffer documentation for information on sending multiple
355 * buffers in one go, and how to use it with arrays, boost::array or
358 template <typename ConstBufferSequence>
359 std::size_t send(const ConstBufferSequence& buffers)
361 boost::system::error_code ec;
362 std::size_t s = this->impl_.get_service().send(
363 this->impl_.get_implementation(), buffers, 0, ec);
364 boost::asio::detail::throw_error(ec, "send");
368 /// Send some data on the socket.
370 * This function is used to send data on the stream socket. The function
371 * call will block until one or more bytes of the data has been sent
372 * successfully, or an until error occurs.
374 * @param buffers One or more data buffers to be sent on the socket.
376 * @param flags Flags specifying how the send call is to be made.
378 * @returns The number of bytes sent.
380 * @throws boost::system::system_error Thrown on failure.
382 * @note The send operation may not transmit all of the data to the peer.
383 * Consider using the @ref write function if you need to ensure that all data
384 * is written before the blocking operation completes.
387 * To send a single data buffer use the @ref buffer function as follows:
389 * socket.send(boost::asio::buffer(data, size), 0);
391 * See the @ref buffer documentation for information on sending multiple
392 * buffers in one go, and how to use it with arrays, boost::array or
395 template <typename ConstBufferSequence>
396 std::size_t send(const ConstBufferSequence& buffers,
397 socket_base::message_flags flags)
399 boost::system::error_code ec;
400 std::size_t s = this->impl_.get_service().send(
401 this->impl_.get_implementation(), buffers, flags, ec);
402 boost::asio::detail::throw_error(ec, "send");
406 /// Send some data on the socket.
408 * This function is used to send data on the stream socket. The function
409 * call will block until one or more bytes of the data has been sent
410 * successfully, or an until error occurs.
412 * @param buffers One or more data buffers to be sent on the socket.
414 * @param flags Flags specifying how the send call is to be made.
416 * @param ec Set to indicate what error occurred, if any.
418 * @returns The number of bytes sent. Returns 0 if an error occurred.
420 * @note The send operation may not transmit all of the data to the peer.
421 * Consider using the @ref write function if you need to ensure that all data
422 * is written before the blocking operation completes.
424 template <typename ConstBufferSequence>
425 std::size_t send(const ConstBufferSequence& buffers,
426 socket_base::message_flags flags, boost::system::error_code& ec)
428 return this->impl_.get_service().send(
429 this->impl_.get_implementation(), buffers, flags, ec);
432 /// Start an asynchronous send.
434 * This function is used to asynchronously send data on the stream socket.
435 * The function call always returns immediately.
437 * @param buffers One or more data buffers to be sent on the socket. Although
438 * the buffers object may be copied as necessary, ownership of the underlying
439 * memory blocks is retained by the caller, which must guarantee that they
440 * remain valid until the handler is called.
442 * @param handler The handler to be called when the send operation completes.
443 * Copies will be made of the handler as required. The function signature of
444 * the handler must be:
445 * @code void handler(
446 * const boost::system::error_code& error, // Result of operation.
447 * std::size_t bytes_transferred // Number of bytes sent.
449 * Regardless of whether the asynchronous operation completes immediately or
450 * not, the handler will not be invoked from within this function. On
451 * immediate completion, invocation of the handler will be performed in a
452 * manner equivalent to using boost::asio::post().
454 * @note The send operation may not transmit all of the data to the peer.
455 * Consider using the @ref async_write function if you need to ensure that all
456 * data is written before the asynchronous operation completes.
459 * To send a single data buffer use the @ref buffer function as follows:
461 * socket.async_send(boost::asio::buffer(data, size), handler);
463 * See the @ref buffer documentation for information on sending multiple
464 * buffers in one go, and how to use it with arrays, boost::array or
467 template <typename ConstBufferSequence,
468 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
469 std::size_t)) WriteHandler
470 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
471 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
472 void (boost::system::error_code, std::size_t))
473 async_send(const ConstBufferSequence& buffers,
474 BOOST_ASIO_MOVE_ARG(WriteHandler) handler
475 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
477 return async_initiate<WriteHandler,
478 void (boost::system::error_code, std::size_t)>(
479 initiate_async_send(this), handler,
480 buffers, socket_base::message_flags(0));
483 /// Start an asynchronous send.
485 * This function is used to asynchronously send data on the stream socket.
486 * The function call always returns immediately.
488 * @param buffers One or more data buffers to be sent on the socket. Although
489 * the buffers object may be copied as necessary, ownership of the underlying
490 * memory blocks is retained by the caller, which must guarantee that they
491 * remain valid until the handler is called.
493 * @param flags Flags specifying how the send call is to be made.
495 * @param handler The handler to be called when the send operation completes.
496 * Copies will be made of the handler as required. The function signature of
497 * the handler must be:
498 * @code void handler(
499 * const boost::system::error_code& error, // Result of operation.
500 * std::size_t bytes_transferred // Number of bytes sent.
502 * Regardless of whether the asynchronous operation completes immediately or
503 * not, the handler will not be invoked from within this function. On
504 * immediate completion, invocation of the handler will be performed in a
505 * manner equivalent to using boost::asio::post().
507 * @note The send operation may not transmit all of the data to the peer.
508 * Consider using the @ref async_write function if you need to ensure that all
509 * data is written before the asynchronous operation completes.
512 * To send a single data buffer use the @ref buffer function as follows:
514 * socket.async_send(boost::asio::buffer(data, size), 0, handler);
516 * See the @ref buffer documentation for information on sending multiple
517 * buffers in one go, and how to use it with arrays, boost::array or
520 template <typename ConstBufferSequence,
521 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
522 std::size_t)) WriteHandler
523 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
524 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
525 void (boost::system::error_code, std::size_t))
526 async_send(const ConstBufferSequence& buffers,
527 socket_base::message_flags flags,
528 BOOST_ASIO_MOVE_ARG(WriteHandler) handler
529 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
531 return async_initiate<WriteHandler,
532 void (boost::system::error_code, std::size_t)>(
533 initiate_async_send(this), handler, buffers, flags);
536 /// Receive some data on the socket.
538 * This function is used to receive data on the stream socket. The function
539 * call will block until one or more bytes of data has been received
540 * successfully, or until an error occurs.
542 * @param buffers One or more buffers into which the data will be received.
544 * @returns The number of bytes received.
546 * @throws boost::system::system_error Thrown on failure. An error code of
547 * boost::asio::error::eof indicates that the connection was closed by the
550 * @note The receive operation may not receive all of the requested number of
551 * bytes. Consider using the @ref read function if you need to ensure that the
552 * requested amount of data is read before the blocking operation completes.
555 * To receive into a single data buffer use the @ref buffer function as
558 * socket.receive(boost::asio::buffer(data, size));
560 * See the @ref buffer documentation for information on receiving into
561 * multiple buffers in one go, and how to use it with arrays, boost::array or
564 template <typename MutableBufferSequence>
565 std::size_t receive(const MutableBufferSequence& buffers)
567 boost::system::error_code ec;
568 std::size_t s = this->impl_.get_service().receive(
569 this->impl_.get_implementation(), buffers, 0, ec);
570 boost::asio::detail::throw_error(ec, "receive");
574 /// Receive some data on the socket.
576 * This function is used to receive data on the stream socket. The function
577 * call will block until one or more bytes of data has been received
578 * successfully, or until an error occurs.
580 * @param buffers One or more buffers into which the data will be received.
582 * @param flags Flags specifying how the receive call is to be made.
584 * @returns The number of bytes received.
586 * @throws boost::system::system_error Thrown on failure. An error code of
587 * boost::asio::error::eof indicates that the connection was closed by the
590 * @note The receive operation may not receive all of the requested number of
591 * bytes. Consider using the @ref read function if you need to ensure that the
592 * requested amount of data is read before the blocking operation completes.
595 * To receive into a single data buffer use the @ref buffer function as
598 * socket.receive(boost::asio::buffer(data, size), 0);
600 * See the @ref buffer documentation for information on receiving into
601 * multiple buffers in one go, and how to use it with arrays, boost::array or
604 template <typename MutableBufferSequence>
605 std::size_t receive(const MutableBufferSequence& buffers,
606 socket_base::message_flags flags)
608 boost::system::error_code ec;
609 std::size_t s = this->impl_.get_service().receive(
610 this->impl_.get_implementation(), buffers, flags, ec);
611 boost::asio::detail::throw_error(ec, "receive");
615 /// Receive some data on a connected socket.
617 * This function is used to receive data on the stream socket. The function
618 * call will block until one or more bytes of data has been received
619 * successfully, or until an error occurs.
621 * @param buffers One or more buffers into which the data will be received.
623 * @param flags Flags specifying how the receive call is to be made.
625 * @param ec Set to indicate what error occurred, if any.
627 * @returns The number of bytes received. Returns 0 if an error occurred.
629 * @note The receive operation may not receive all of the requested number of
630 * bytes. Consider using the @ref read function if you need to ensure that the
631 * requested amount of data is read before the blocking operation completes.
633 template <typename MutableBufferSequence>
634 std::size_t receive(const MutableBufferSequence& buffers,
635 socket_base::message_flags flags, boost::system::error_code& ec)
637 return this->impl_.get_service().receive(
638 this->impl_.get_implementation(), buffers, flags, ec);
641 /// Start an asynchronous receive.
643 * This function is used to asynchronously receive data from the stream
644 * socket. The function call always returns immediately.
646 * @param buffers One or more buffers into which the data will be received.
647 * Although the buffers object may be copied as necessary, ownership of the
648 * underlying memory blocks is retained by the caller, which must guarantee
649 * that they remain valid until the handler is called.
651 * @param handler The handler to be called when the receive operation
652 * completes. Copies will be made of the handler as required. The function
653 * signature of the handler must be:
654 * @code void handler(
655 * const boost::system::error_code& error, // Result of operation.
656 * std::size_t bytes_transferred // Number of bytes received.
658 * Regardless of whether the asynchronous operation completes immediately or
659 * not, the handler will not be invoked from within this function. On
660 * immediate completion, invocation of the handler will be performed in a
661 * manner equivalent to using boost::asio::post().
663 * @note The receive operation may not receive all of the requested number of
664 * bytes. Consider using the @ref async_read function if you need to ensure
665 * that the requested amount of data is received before the asynchronous
666 * operation completes.
669 * To receive into a single data buffer use the @ref buffer function as
672 * socket.async_receive(boost::asio::buffer(data, size), handler);
674 * See the @ref buffer documentation for information on receiving into
675 * multiple buffers in one go, and how to use it with arrays, boost::array or
678 template <typename MutableBufferSequence,
679 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
680 std::size_t)) ReadHandler
681 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
682 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
683 void (boost::system::error_code, std::size_t))
684 async_receive(const MutableBufferSequence& buffers,
685 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
686 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
688 return async_initiate<ReadHandler,
689 void (boost::system::error_code, std::size_t)>(
690 initiate_async_receive(this), handler,
691 buffers, socket_base::message_flags(0));
694 /// Start an asynchronous receive.
696 * This function is used to asynchronously receive data from the stream
697 * socket. The function call always returns immediately.
699 * @param buffers One or more buffers into which the data will be received.
700 * Although the buffers object may be copied as necessary, ownership of the
701 * underlying memory blocks is retained by the caller, which must guarantee
702 * that they remain valid until the handler is called.
704 * @param flags Flags specifying how the receive call is to be made.
706 * @param handler The handler to be called when the receive operation
707 * completes. Copies will be made of the handler as required. The function
708 * signature of the handler must be:
709 * @code void handler(
710 * const boost::system::error_code& error, // Result of operation.
711 * std::size_t bytes_transferred // Number of bytes received.
713 * Regardless of whether the asynchronous operation completes immediately or
714 * not, the handler will not be invoked from within this function. On
715 * immediate completion, invocation of the handler will be performed in a
716 * manner equivalent to using boost::asio::post().
718 * @note The receive operation may not receive all of the requested number of
719 * bytes. Consider using the @ref async_read function if you need to ensure
720 * that the requested amount of data is received before the asynchronous
721 * operation completes.
724 * To receive into a single data buffer use the @ref buffer function as
727 * socket.async_receive(boost::asio::buffer(data, size), 0, handler);
729 * See the @ref buffer documentation for information on receiving into
730 * multiple buffers in one go, and how to use it with arrays, boost::array or
733 template <typename MutableBufferSequence,
734 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
735 std::size_t)) ReadHandler
736 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
737 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
738 void (boost::system::error_code, std::size_t))
739 async_receive(const MutableBufferSequence& buffers,
740 socket_base::message_flags flags,
741 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
742 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
744 return async_initiate<ReadHandler,
745 void (boost::system::error_code, std::size_t)>(
746 initiate_async_receive(this), handler, buffers, flags);
749 /// Write some data to the socket.
751 * This function is used to write data to the stream socket. The function call
752 * will block until one or more bytes of the data has been written
753 * successfully, or until an error occurs.
755 * @param buffers One or more data buffers to be written to the socket.
757 * @returns The number of bytes written.
759 * @throws boost::system::system_error Thrown on failure. An error code of
760 * boost::asio::error::eof indicates that the connection was closed by the
763 * @note The write_some operation may not transmit all of the data to the
764 * peer. Consider using the @ref write function if you need to ensure that
765 * all data is written before the blocking operation completes.
768 * To write a single data buffer use the @ref buffer function as follows:
770 * socket.write_some(boost::asio::buffer(data, size));
772 * See the @ref buffer documentation for information on writing multiple
773 * buffers in one go, and how to use it with arrays, boost::array or
776 template <typename ConstBufferSequence>
777 std::size_t write_some(const ConstBufferSequence& buffers)
779 boost::system::error_code ec;
780 std::size_t s = this->impl_.get_service().send(
781 this->impl_.get_implementation(), buffers, 0, ec);
782 boost::asio::detail::throw_error(ec, "write_some");
786 /// Write some data to the socket.
788 * This function is used to write data to the stream socket. The function call
789 * will block until one or more bytes of the data has been written
790 * successfully, or until an error occurs.
792 * @param buffers One or more data buffers to be written to the socket.
794 * @param ec Set to indicate what error occurred, if any.
796 * @returns The number of bytes written. Returns 0 if an error occurred.
798 * @note The write_some operation may not transmit all of the data to the
799 * peer. Consider using the @ref write function if you need to ensure that
800 * all data is written before the blocking operation completes.
802 template <typename ConstBufferSequence>
803 std::size_t write_some(const ConstBufferSequence& buffers,
804 boost::system::error_code& ec)
806 return this->impl_.get_service().send(
807 this->impl_.get_implementation(), buffers, 0, ec);
810 /// Start an asynchronous write.
812 * This function is used to asynchronously write data to the stream socket.
813 * The function call always returns immediately.
815 * @param buffers One or more data buffers to be written to the socket.
816 * Although the buffers object may be copied as necessary, ownership of the
817 * underlying memory blocks is retained by the caller, which must guarantee
818 * that they remain valid until the handler is called.
820 * @param handler The handler to be called when the write operation completes.
821 * Copies will be made of the handler as required. The function signature of
822 * the handler must be:
823 * @code void handler(
824 * const boost::system::error_code& error, // Result of operation.
825 * std::size_t bytes_transferred // Number of bytes written.
827 * Regardless of whether the asynchronous operation completes immediately or
828 * not, the handler will not be invoked from within this function. On
829 * immediate completion, invocation of the handler will be performed in a
830 * manner equivalent to using boost::asio::post().
832 * @note The write operation may not transmit all of the data to the peer.
833 * Consider using the @ref async_write function if you need to ensure that all
834 * data is written before the asynchronous operation completes.
837 * To write a single data buffer use the @ref buffer function as follows:
839 * socket.async_write_some(boost::asio::buffer(data, size), handler);
841 * See the @ref buffer documentation for information on writing multiple
842 * buffers in one go, and how to use it with arrays, boost::array or
845 template <typename ConstBufferSequence,
846 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
847 std::size_t)) WriteHandler
848 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
849 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
850 void (boost::system::error_code, std::size_t))
851 async_write_some(const ConstBufferSequence& buffers,
852 BOOST_ASIO_MOVE_ARG(WriteHandler) handler
853 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
855 return async_initiate<WriteHandler,
856 void (boost::system::error_code, std::size_t)>(
857 initiate_async_send(this), handler,
858 buffers, socket_base::message_flags(0));
861 /// Read some data from the socket.
863 * This function is used to read data from the stream socket. The function
864 * call will block until one or more bytes of data has been read successfully,
865 * or until an error occurs.
867 * @param buffers One or more buffers into which the data will be read.
869 * @returns The number of bytes read.
871 * @throws boost::system::system_error Thrown on failure. An error code of
872 * boost::asio::error::eof indicates that the connection was closed by the
875 * @note The read_some operation may not read all of the requested number of
876 * bytes. Consider using the @ref read function if you need to ensure that
877 * the requested amount of data is read before the blocking operation
881 * To read into a single data buffer use the @ref buffer function as follows:
883 * socket.read_some(boost::asio::buffer(data, size));
885 * See the @ref buffer documentation for information on reading into multiple
886 * buffers in one go, and how to use it with arrays, boost::array or
889 template <typename MutableBufferSequence>
890 std::size_t read_some(const MutableBufferSequence& buffers)
892 boost::system::error_code ec;
893 std::size_t s = this->impl_.get_service().receive(
894 this->impl_.get_implementation(), buffers, 0, ec);
895 boost::asio::detail::throw_error(ec, "read_some");
899 /// Read some data from the socket.
901 * This function is used to read data from the stream socket. The function
902 * call will block until one or more bytes of data has been read successfully,
903 * or until an error occurs.
905 * @param buffers One or more buffers into which the data will be read.
907 * @param ec Set to indicate what error occurred, if any.
909 * @returns The number of bytes read. Returns 0 if an error occurred.
911 * @note The read_some operation may not read all of the requested number of
912 * bytes. Consider using the @ref read function if you need to ensure that
913 * the requested amount of data is read before the blocking operation
916 template <typename MutableBufferSequence>
917 std::size_t read_some(const MutableBufferSequence& buffers,
918 boost::system::error_code& ec)
920 return this->impl_.get_service().receive(
921 this->impl_.get_implementation(), buffers, 0, ec);
924 /// Start an asynchronous read.
926 * This function is used to asynchronously read data from the stream socket.
927 * The function call always returns immediately.
929 * @param buffers One or more buffers into which the data will be read.
930 * Although the buffers object may be copied as necessary, ownership of the
931 * underlying memory blocks is retained by the caller, which must guarantee
932 * that they remain valid until the handler is called.
934 * @param handler The handler to be called when the read operation completes.
935 * Copies will be made of the handler as required. The function signature of
936 * the handler must be:
937 * @code void handler(
938 * const boost::system::error_code& error, // Result of operation.
939 * std::size_t bytes_transferred // Number of bytes read.
941 * Regardless of whether the asynchronous operation completes immediately or
942 * not, the handler will not be invoked from within this function. On
943 * immediate completion, invocation of the handler will be performed in a
944 * manner equivalent to using boost::asio::post().
946 * @note The read operation may not read all of the requested number of bytes.
947 * Consider using the @ref async_read function if you need to ensure that the
948 * requested amount of data is read before the asynchronous operation
952 * To read into a single data buffer use the @ref buffer function as follows:
954 * socket.async_read_some(boost::asio::buffer(data, size), handler);
956 * See the @ref buffer documentation for information on reading into multiple
957 * buffers in one go, and how to use it with arrays, boost::array or
960 template <typename MutableBufferSequence,
961 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
962 std::size_t)) ReadHandler
963 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
964 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
965 void (boost::system::error_code, std::size_t))
966 async_read_some(const MutableBufferSequence& buffers,
967 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
968 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
970 return async_initiate<ReadHandler,
971 void (boost::system::error_code, std::size_t)>(
972 initiate_async_receive(this), handler,
973 buffers, socket_base::message_flags(0));
977 class initiate_async_send
980 typedef Executor executor_type;
982 explicit initiate_async_send(basic_stream_socket* self)
987 executor_type get_executor() const BOOST_ASIO_NOEXCEPT
989 return self_->get_executor();
992 template <typename WriteHandler, typename ConstBufferSequence>
993 void operator()(BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
994 const ConstBufferSequence& buffers,
995 socket_base::message_flags flags) const
997 // If you get an error on the following line it means that your handler
998 // does not meet the documented type requirements for a WriteHandler.
999 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
1001 detail::non_const_lvalue<WriteHandler> handler2(handler);
1002 self_->impl_.get_service().async_send(
1003 self_->impl_.get_implementation(), buffers, flags,
1004 handler2.value, self_->impl_.get_implementation_executor());
1008 basic_stream_socket* self_;
1011 class initiate_async_receive
1014 typedef Executor executor_type;
1016 explicit initiate_async_receive(basic_stream_socket* self)
1021 executor_type get_executor() const BOOST_ASIO_NOEXCEPT
1023 return self_->get_executor();
1026 template <typename ReadHandler, typename MutableBufferSequence>
1027 void operator()(BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
1028 const MutableBufferSequence& buffers,
1029 socket_base::message_flags flags) const
1031 // If you get an error on the following line it means that your handler
1032 // does not meet the documented type requirements for a ReadHandler.
1033 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
1035 detail::non_const_lvalue<ReadHandler> handler2(handler);
1036 self_->impl_.get_service().async_receive(
1037 self_->impl_.get_implementation(), buffers, flags,
1038 handler2.value, self_->impl_.get_implementation_executor());
1042 basic_stream_socket* self_;
1047 } // namespace boost
1049 #include <boost/asio/detail/pop_options.hpp>
1051 #endif // BOOST_ASIO_BASIC_STREAM_SOCKET_HPP