2 // basic_datagram_socket.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2016 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_DATAGRAM_SOCKET_HPP
12 #define BOOST_ASIO_BASIC_DATAGRAM_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/basic_socket.hpp>
21 #include <boost/asio/datagram_socket_service.hpp>
22 #include <boost/asio/detail/handler_type_requirements.hpp>
23 #include <boost/asio/detail/throw_error.hpp>
24 #include <boost/asio/detail/type_traits.hpp>
25 #include <boost/asio/error.hpp>
27 #include <boost/asio/detail/push_options.hpp>
32 /// Provides datagram-oriented socket functionality.
34 * The basic_datagram_socket class template provides asynchronous and blocking
35 * datagram-oriented socket functionality.
38 * @e Distinct @e objects: Safe.@n
39 * @e Shared @e objects: Unsafe.
41 template <typename Protocol,
42 typename DatagramSocketService = datagram_socket_service<Protocol> >
43 class basic_datagram_socket
44 : public basic_socket<Protocol, DatagramSocketService>
47 /// (Deprecated: Use native_handle_type.) The native representation of a
49 typedef typename DatagramSocketService::native_handle_type native_type;
51 /// The native representation of a socket.
52 typedef typename DatagramSocketService::native_handle_type native_handle_type;
54 /// The protocol type.
55 typedef Protocol protocol_type;
57 /// The endpoint type.
58 typedef typename Protocol::endpoint endpoint_type;
60 /// Construct a basic_datagram_socket without opening it.
62 * This constructor creates a datagram socket without opening it. The open()
63 * function must be called before data can be sent or received on the socket.
65 * @param io_service The io_service object that the datagram socket will use
66 * to dispatch handlers for any asynchronous operations performed on the
69 explicit basic_datagram_socket(boost::asio::io_service& io_service)
70 : basic_socket<Protocol, DatagramSocketService>(io_service)
74 /// Construct and open a basic_datagram_socket.
76 * This constructor creates and opens a datagram socket.
78 * @param io_service The io_service object that the datagram socket will use
79 * to dispatch handlers for any asynchronous operations performed on the
82 * @param protocol An object specifying protocol parameters to be used.
84 * @throws boost::system::system_error Thrown on failure.
86 basic_datagram_socket(boost::asio::io_service& io_service,
87 const protocol_type& protocol)
88 : basic_socket<Protocol, DatagramSocketService>(io_service, protocol)
92 /// Construct a basic_datagram_socket, opening it and binding it to the given
95 * This constructor creates a datagram socket and automatically opens it bound
96 * to the specified endpoint on the local machine. The protocol used is the
97 * protocol associated with the given endpoint.
99 * @param io_service The io_service object that the datagram socket will use
100 * to dispatch handlers for any asynchronous operations performed on the
103 * @param endpoint An endpoint on the local machine to which the datagram
104 * socket will be bound.
106 * @throws boost::system::system_error Thrown on failure.
108 basic_datagram_socket(boost::asio::io_service& io_service,
109 const endpoint_type& endpoint)
110 : basic_socket<Protocol, DatagramSocketService>(io_service, endpoint)
114 /// Construct a basic_datagram_socket on an existing native socket.
116 * This constructor creates a datagram socket object to hold an existing
119 * @param io_service The io_service object that the datagram socket will use
120 * to dispatch handlers for any asynchronous operations performed on the
123 * @param protocol An object specifying protocol parameters to be used.
125 * @param native_socket The new underlying socket implementation.
127 * @throws boost::system::system_error Thrown on failure.
129 basic_datagram_socket(boost::asio::io_service& io_service,
130 const protocol_type& protocol, const native_handle_type& native_socket)
131 : basic_socket<Protocol, DatagramSocketService>(
132 io_service, protocol, native_socket)
136 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
137 /// Move-construct a basic_datagram_socket from another.
139 * This constructor moves a datagram socket from one object to another.
141 * @param other The other basic_datagram_socket object from which the move
144 * @note Following the move, the moved-from object is in the same state as if
145 * constructed using the @c basic_datagram_socket(io_service&) constructor.
147 basic_datagram_socket(basic_datagram_socket&& other)
148 : basic_socket<Protocol, DatagramSocketService>(
149 BOOST_ASIO_MOVE_CAST(basic_datagram_socket)(other))
153 /// Move-assign a basic_datagram_socket from another.
155 * This assignment operator moves a datagram socket from one object to
158 * @param other The other basic_datagram_socket object from which the move
161 * @note Following the move, the moved-from object is in the same state as if
162 * constructed using the @c basic_datagram_socket(io_service&) constructor.
164 basic_datagram_socket& operator=(basic_datagram_socket&& other)
166 basic_socket<Protocol, DatagramSocketService>::operator=(
167 BOOST_ASIO_MOVE_CAST(basic_datagram_socket)(other));
171 /// Move-construct a basic_datagram_socket from a socket of another protocol
174 * This constructor moves a datagram socket from one object to another.
176 * @param other The other basic_datagram_socket object from which the move
179 * @note Following the move, the moved-from object is in the same state as if
180 * constructed using the @c basic_datagram_socket(io_service&) constructor.
182 template <typename Protocol1, typename DatagramSocketService1>
183 basic_datagram_socket(
184 basic_datagram_socket<Protocol1, DatagramSocketService1>&& other,
185 typename enable_if<is_convertible<Protocol1, Protocol>::value>::type* = 0)
186 : basic_socket<Protocol, DatagramSocketService>(
187 BOOST_ASIO_MOVE_CAST2(basic_datagram_socket<
188 Protocol1, DatagramSocketService1>)(other))
192 /// Move-assign a basic_datagram_socket from a socket of another protocol
195 * This assignment operator moves a datagram socket from one object to
198 * @param other The other basic_datagram_socket object from which the move
201 * @note Following the move, the moved-from object is in the same state as if
202 * constructed using the @c basic_datagram_socket(io_service&) constructor.
204 template <typename Protocol1, typename DatagramSocketService1>
205 typename enable_if<is_convertible<Protocol1, Protocol>::value,
206 basic_datagram_socket>::type& operator=(
207 basic_datagram_socket<Protocol1, DatagramSocketService1>&& other)
209 basic_socket<Protocol, DatagramSocketService>::operator=(
210 BOOST_ASIO_MOVE_CAST2(basic_datagram_socket<
211 Protocol1, DatagramSocketService1>)(other));
214 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
216 /// Send some data on a connected socket.
218 * This function is used to send data on the datagram socket. The function
219 * call will block until the data has been sent successfully or an error
222 * @param buffers One ore more data buffers to be sent on the socket.
224 * @returns The number of bytes sent.
226 * @throws boost::system::system_error Thrown on failure.
228 * @note The send operation can only be used with a connected socket. Use
229 * the send_to function to send data on an unconnected datagram socket.
232 * To send a single data buffer use the @ref buffer function as follows:
233 * @code socket.send(boost::asio::buffer(data, size)); @endcode
234 * See the @ref buffer documentation for information on sending multiple
235 * buffers in one go, and how to use it with arrays, boost::array or
238 template <typename ConstBufferSequence>
239 std::size_t send(const ConstBufferSequence& buffers)
241 boost::system::error_code ec;
242 std::size_t s = this->get_service().send(
243 this->get_implementation(), buffers, 0, ec);
244 boost::asio::detail::throw_error(ec, "send");
248 /// Send some data on a connected socket.
250 * This function is used to send data on the datagram socket. The function
251 * call will block until the data has been sent successfully or an error
254 * @param buffers One ore more data buffers to be sent on the socket.
256 * @param flags Flags specifying how the send call is to be made.
258 * @returns The number of bytes sent.
260 * @throws boost::system::system_error Thrown on failure.
262 * @note The send operation can only be used with a connected socket. Use
263 * the send_to function to send data on an unconnected datagram socket.
265 template <typename ConstBufferSequence>
266 std::size_t send(const ConstBufferSequence& buffers,
267 socket_base::message_flags flags)
269 boost::system::error_code ec;
270 std::size_t s = this->get_service().send(
271 this->get_implementation(), buffers, flags, ec);
272 boost::asio::detail::throw_error(ec, "send");
276 /// Send some data on a connected socket.
278 * This function is used to send data on the datagram socket. The function
279 * call will block until the data has been sent successfully or an error
282 * @param buffers One or more data buffers to be sent on the socket.
284 * @param flags Flags specifying how the send call is to be made.
286 * @param ec Set to indicate what error occurred, if any.
288 * @returns The number of bytes sent.
290 * @note The send operation can only be used with a connected socket. Use
291 * the send_to function to send data on an unconnected datagram socket.
293 template <typename ConstBufferSequence>
294 std::size_t send(const ConstBufferSequence& buffers,
295 socket_base::message_flags flags, boost::system::error_code& ec)
297 return this->get_service().send(
298 this->get_implementation(), buffers, flags, ec);
301 /// Start an asynchronous send on a connected socket.
303 * This function is used to asynchronously send data on the datagram socket.
304 * The function call always returns immediately.
306 * @param buffers One or more data buffers to be sent on the socket. Although
307 * the buffers object may be copied as necessary, ownership of the underlying
308 * memory blocks is retained by the caller, which must guarantee that they
309 * remain valid until the handler is called.
311 * @param handler The handler to be called when the send operation completes.
312 * Copies will be made of the handler as required. The function signature of
313 * the handler must be:
314 * @code void handler(
315 * const boost::system::error_code& error, // Result of operation.
316 * std::size_t bytes_transferred // Number of bytes sent.
318 * Regardless of whether the asynchronous operation completes immediately or
319 * not, the handler will not be invoked from within this function. Invocation
320 * of the handler will be performed in a manner equivalent to using
321 * boost::asio::io_service::post().
323 * @note The async_send operation can only be used with a connected socket.
324 * Use the async_send_to function to send data on an unconnected datagram
328 * To send a single data buffer use the @ref buffer function as follows:
330 * socket.async_send(boost::asio::buffer(data, size), handler);
332 * See the @ref buffer documentation for information on sending multiple
333 * buffers in one go, and how to use it with arrays, boost::array or
336 template <typename ConstBufferSequence, typename WriteHandler>
337 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
338 void (boost::system::error_code, std::size_t))
339 async_send(const ConstBufferSequence& buffers,
340 BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
342 // If you get an error on the following line it means that your handler does
343 // not meet the documented type requirements for a WriteHandler.
344 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
346 return this->get_service().async_send(this->get_implementation(),
347 buffers, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
350 /// Start an asynchronous send on a connected socket.
352 * This function is used to asynchronously send data on the datagram socket.
353 * The function call always returns immediately.
355 * @param buffers One or more data buffers to be sent on the socket. Although
356 * the buffers object may be copied as necessary, ownership of the underlying
357 * memory blocks is retained by the caller, which must guarantee that they
358 * remain valid until the handler is called.
360 * @param flags Flags specifying how the send call is to be made.
362 * @param handler The handler to be called when the send operation completes.
363 * Copies will be made of the handler as required. The function signature of
364 * the handler must be:
365 * @code void handler(
366 * const boost::system::error_code& error, // Result of operation.
367 * std::size_t bytes_transferred // Number of bytes sent.
369 * Regardless of whether the asynchronous operation completes immediately or
370 * not, the handler will not be invoked from within this function. Invocation
371 * of the handler will be performed in a manner equivalent to using
372 * boost::asio::io_service::post().
374 * @note The async_send operation can only be used with a connected socket.
375 * Use the async_send_to function to send data on an unconnected datagram
378 template <typename ConstBufferSequence, typename WriteHandler>
379 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
380 void (boost::system::error_code, std::size_t))
381 async_send(const ConstBufferSequence& buffers,
382 socket_base::message_flags flags,
383 BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
385 // If you get an error on the following line it means that your handler does
386 // not meet the documented type requirements for a WriteHandler.
387 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
389 return this->get_service().async_send(this->get_implementation(),
390 buffers, flags, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
393 /// Send a datagram to the specified endpoint.
395 * This function is used to send a datagram to the specified remote endpoint.
396 * The function call will block until the data has been sent successfully or
399 * @param buffers One or more data buffers to be sent to the remote endpoint.
401 * @param destination The remote endpoint to which the data will be sent.
403 * @returns The number of bytes sent.
405 * @throws boost::system::system_error Thrown on failure.
408 * To send a single data buffer use the @ref buffer function as follows:
410 * boost::asio::ip::udp::endpoint destination(
411 * boost::asio::ip::address::from_string("1.2.3.4"), 12345);
412 * socket.send_to(boost::asio::buffer(data, size), destination);
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
418 template <typename ConstBufferSequence>
419 std::size_t send_to(const ConstBufferSequence& buffers,
420 const endpoint_type& destination)
422 boost::system::error_code ec;
423 std::size_t s = this->get_service().send_to(
424 this->get_implementation(), buffers, destination, 0, ec);
425 boost::asio::detail::throw_error(ec, "send_to");
429 /// Send a datagram to the specified endpoint.
431 * This function is used to send a datagram to the specified remote endpoint.
432 * The function call will block until the data has been sent successfully or
435 * @param buffers One or more data buffers to be sent to the remote endpoint.
437 * @param destination The remote endpoint to which the data will be sent.
439 * @param flags Flags specifying how the send call is to be made.
441 * @returns The number of bytes sent.
443 * @throws boost::system::system_error Thrown on failure.
445 template <typename ConstBufferSequence>
446 std::size_t send_to(const ConstBufferSequence& buffers,
447 const endpoint_type& destination, socket_base::message_flags flags)
449 boost::system::error_code ec;
450 std::size_t s = this->get_service().send_to(
451 this->get_implementation(), buffers, destination, flags, ec);
452 boost::asio::detail::throw_error(ec, "send_to");
456 /// Send a datagram to the specified endpoint.
458 * This function is used to send a datagram to the specified remote endpoint.
459 * The function call will block until the data has been sent successfully or
462 * @param buffers One or more data buffers to be sent to the remote endpoint.
464 * @param destination The remote endpoint to which the data will be sent.
466 * @param flags Flags specifying how the send call is to be made.
468 * @param ec Set to indicate what error occurred, if any.
470 * @returns The number of bytes sent.
472 template <typename ConstBufferSequence>
473 std::size_t send_to(const ConstBufferSequence& buffers,
474 const endpoint_type& destination, socket_base::message_flags flags,
475 boost::system::error_code& ec)
477 return this->get_service().send_to(this->get_implementation(),
478 buffers, destination, flags, ec);
481 /// Start an asynchronous send.
483 * This function is used to asynchronously send a datagram to the specified
484 * remote endpoint. The function call always returns immediately.
486 * @param buffers One or more data buffers to be sent to the remote endpoint.
487 * Although the buffers object may be copied as necessary, ownership of the
488 * underlying memory blocks is retained by the caller, which must guarantee
489 * that they remain valid until the handler is called.
491 * @param destination The remote endpoint to which the data will be sent.
492 * Copies will be made of the endpoint as required.
494 * @param handler The handler to be called when the send operation completes.
495 * Copies will be made of the handler as required. The function signature of
496 * the handler must be:
497 * @code void handler(
498 * const boost::system::error_code& error, // Result of operation.
499 * std::size_t bytes_transferred // Number of bytes sent.
501 * Regardless of whether the asynchronous operation completes immediately or
502 * not, the handler will not be invoked from within this function. Invocation
503 * of the handler will be performed in a manner equivalent to using
504 * boost::asio::io_service::post().
507 * To send a single data buffer use the @ref buffer function as follows:
509 * boost::asio::ip::udp::endpoint destination(
510 * boost::asio::ip::address::from_string("1.2.3.4"), 12345);
511 * socket.async_send_to(
512 * boost::asio::buffer(data, size), destination, handler);
514 * See the @ref buffer documentation for information on sending multiple
515 * buffers in one go, and how to use it with arrays, boost::array or
518 template <typename ConstBufferSequence, typename WriteHandler>
519 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
520 void (boost::system::error_code, std::size_t))
521 async_send_to(const ConstBufferSequence& buffers,
522 const endpoint_type& destination,
523 BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
525 // If you get an error on the following line it means that your handler does
526 // not meet the documented type requirements for a WriteHandler.
527 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
529 return this->get_service().async_send_to(
530 this->get_implementation(), buffers, destination, 0,
531 BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
534 /// Start an asynchronous send.
536 * This function is used to asynchronously send a datagram to the specified
537 * remote endpoint. The function call always returns immediately.
539 * @param buffers One or more data buffers to be sent to the remote endpoint.
540 * Although the buffers object may be copied as necessary, ownership of the
541 * underlying memory blocks is retained by the caller, which must guarantee
542 * that they remain valid until the handler is called.
544 * @param flags Flags specifying how the send call is to be made.
546 * @param destination The remote endpoint to which the data will be sent.
547 * Copies will be made of the endpoint as required.
549 * @param handler The handler to be called when the send operation completes.
550 * Copies will be made of the handler as required. The function signature of
551 * the handler must be:
552 * @code void handler(
553 * const boost::system::error_code& error, // Result of operation.
554 * std::size_t bytes_transferred // Number of bytes sent.
556 * Regardless of whether the asynchronous operation completes immediately or
557 * not, the handler will not be invoked from within this function. Invocation
558 * of the handler will be performed in a manner equivalent to using
559 * boost::asio::io_service::post().
561 template <typename ConstBufferSequence, typename WriteHandler>
562 BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
563 void (boost::system::error_code, std::size_t))
564 async_send_to(const ConstBufferSequence& buffers,
565 const endpoint_type& destination, socket_base::message_flags flags,
566 BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
568 // If you get an error on the following line it means that your handler does
569 // not meet the documented type requirements for a WriteHandler.
570 BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
572 return this->get_service().async_send_to(
573 this->get_implementation(), buffers, destination, flags,
574 BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
577 /// Receive some data on a connected socket.
579 * This function is used to receive data on the datagram socket. The function
580 * call will block until data has been received successfully or an error
583 * @param buffers One or more buffers into which the data will be received.
585 * @returns The number of bytes received.
587 * @throws boost::system::system_error Thrown on failure.
589 * @note The receive operation can only be used with a connected socket. Use
590 * the receive_from function to receive data on an unconnected datagram
594 * To receive into a single data buffer use the @ref buffer function as
596 * @code socket.receive(boost::asio::buffer(data, size)); @endcode
597 * See the @ref buffer documentation for information on receiving into
598 * multiple buffers in one go, and how to use it with arrays, boost::array or
601 template <typename MutableBufferSequence>
602 std::size_t receive(const MutableBufferSequence& buffers)
604 boost::system::error_code ec;
605 std::size_t s = this->get_service().receive(
606 this->get_implementation(), buffers, 0, ec);
607 boost::asio::detail::throw_error(ec, "receive");
611 /// Receive some data on a connected socket.
613 * This function is used to receive data on the datagram socket. The function
614 * call will block until data has been received successfully or an error
617 * @param buffers One or more buffers into which the data will be received.
619 * @param flags Flags specifying how the receive call is to be made.
621 * @returns The number of bytes received.
623 * @throws boost::system::system_error Thrown on failure.
625 * @note The receive operation can only be used with a connected socket. Use
626 * the receive_from function to receive data on an unconnected datagram
629 template <typename MutableBufferSequence>
630 std::size_t receive(const MutableBufferSequence& buffers,
631 socket_base::message_flags flags)
633 boost::system::error_code ec;
634 std::size_t s = this->get_service().receive(
635 this->get_implementation(), buffers, flags, ec);
636 boost::asio::detail::throw_error(ec, "receive");
640 /// Receive some data on a connected socket.
642 * This function is used to receive data on the datagram socket. The function
643 * call will block until data has been received successfully or an error
646 * @param buffers One or more buffers into which the data will be received.
648 * @param flags Flags specifying how the receive call is to be made.
650 * @param ec Set to indicate what error occurred, if any.
652 * @returns The number of bytes received.
654 * @note The receive operation can only be used with a connected socket. Use
655 * the receive_from function to receive data on an unconnected datagram
658 template <typename MutableBufferSequence>
659 std::size_t receive(const MutableBufferSequence& buffers,
660 socket_base::message_flags flags, boost::system::error_code& ec)
662 return this->get_service().receive(
663 this->get_implementation(), buffers, flags, ec);
666 /// Start an asynchronous receive on a connected socket.
668 * This function is used to asynchronously receive data from the datagram
669 * socket. The function call always returns immediately.
671 * @param buffers One or more buffers into which the data will be received.
672 * Although the buffers object may be copied as necessary, ownership of the
673 * underlying memory blocks is retained by the caller, which must guarantee
674 * that they remain valid until the handler is called.
676 * @param handler The handler to be called when the receive operation
677 * completes. Copies will be made of the handler as required. The function
678 * signature of the handler must be:
679 * @code void handler(
680 * const boost::system::error_code& error, // Result of operation.
681 * std::size_t bytes_transferred // Number of bytes received.
683 * Regardless of whether the asynchronous operation completes immediately or
684 * not, the handler will not be invoked from within this function. Invocation
685 * of the handler will be performed in a manner equivalent to using
686 * boost::asio::io_service::post().
688 * @note The async_receive operation can only be used with a connected socket.
689 * Use the async_receive_from function to receive data on an unconnected
693 * To receive into a single data buffer use the @ref buffer function as
696 * socket.async_receive(boost::asio::buffer(data, size), handler);
698 * See the @ref buffer documentation for information on receiving into
699 * multiple buffers in one go, and how to use it with arrays, boost::array or
702 template <typename MutableBufferSequence, typename ReadHandler>
703 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
704 void (boost::system::error_code, std::size_t))
705 async_receive(const MutableBufferSequence& buffers,
706 BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
708 // If you get an error on the following line it means that your handler does
709 // not meet the documented type requirements for a ReadHandler.
710 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
712 return this->get_service().async_receive(this->get_implementation(),
713 buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
716 /// Start an asynchronous receive on a connected socket.
718 * This function is used to asynchronously receive data from the datagram
719 * socket. The function call always returns immediately.
721 * @param buffers One or more buffers into which the data will be received.
722 * Although the buffers object may be copied as necessary, ownership of the
723 * underlying memory blocks is retained by the caller, which must guarantee
724 * that they remain valid until the handler is called.
726 * @param flags Flags specifying how the receive call is to be made.
728 * @param handler The handler to be called when the receive operation
729 * completes. Copies will be made of the handler as required. The function
730 * signature of the handler must be:
731 * @code void handler(
732 * const boost::system::error_code& error, // Result of operation.
733 * std::size_t bytes_transferred // Number of bytes received.
735 * Regardless of whether the asynchronous operation completes immediately or
736 * not, the handler will not be invoked from within this function. Invocation
737 * of the handler will be performed in a manner equivalent to using
738 * boost::asio::io_service::post().
740 * @note The async_receive operation can only be used with a connected socket.
741 * Use the async_receive_from function to receive data on an unconnected
744 template <typename MutableBufferSequence, typename ReadHandler>
745 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
746 void (boost::system::error_code, std::size_t))
747 async_receive(const MutableBufferSequence& buffers,
748 socket_base::message_flags flags,
749 BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
751 // If you get an error on the following line it means that your handler does
752 // not meet the documented type requirements for a ReadHandler.
753 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
755 return this->get_service().async_receive(this->get_implementation(),
756 buffers, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
759 /// Receive a datagram with the endpoint of the sender.
761 * This function is used to receive a datagram. The function call will block
762 * until data has been received successfully or an error occurs.
764 * @param buffers One or more buffers into which the data will be received.
766 * @param sender_endpoint An endpoint object that receives the endpoint of
767 * the remote sender of the datagram.
769 * @returns The number of bytes received.
771 * @throws boost::system::system_error Thrown on failure.
774 * To receive into a single data buffer use the @ref buffer function as
777 * boost::asio::ip::udp::endpoint sender_endpoint;
778 * socket.receive_from(
779 * boost::asio::buffer(data, size), sender_endpoint);
781 * See the @ref buffer documentation for information on receiving into
782 * multiple buffers in one go, and how to use it with arrays, boost::array or
785 template <typename MutableBufferSequence>
786 std::size_t receive_from(const MutableBufferSequence& buffers,
787 endpoint_type& sender_endpoint)
789 boost::system::error_code ec;
790 std::size_t s = this->get_service().receive_from(
791 this->get_implementation(), buffers, sender_endpoint, 0, ec);
792 boost::asio::detail::throw_error(ec, "receive_from");
796 /// Receive a datagram with the endpoint of the sender.
798 * This function is used to receive a datagram. The function call will block
799 * until data has been received successfully or an error occurs.
801 * @param buffers One or more buffers into which the data will be received.
803 * @param sender_endpoint An endpoint object that receives the endpoint of
804 * the remote sender of the datagram.
806 * @param flags Flags specifying how the receive call is to be made.
808 * @returns The number of bytes received.
810 * @throws boost::system::system_error Thrown on failure.
812 template <typename MutableBufferSequence>
813 std::size_t receive_from(const MutableBufferSequence& buffers,
814 endpoint_type& sender_endpoint, socket_base::message_flags flags)
816 boost::system::error_code ec;
817 std::size_t s = this->get_service().receive_from(
818 this->get_implementation(), buffers, sender_endpoint, flags, ec);
819 boost::asio::detail::throw_error(ec, "receive_from");
823 /// Receive a datagram with the endpoint of the sender.
825 * This function is used to receive a datagram. The function call will block
826 * until data has been received successfully or an error occurs.
828 * @param buffers One or more buffers into which the data will be received.
830 * @param sender_endpoint An endpoint object that receives the endpoint of
831 * the remote sender of the datagram.
833 * @param flags Flags specifying how the receive call is to be made.
835 * @param ec Set to indicate what error occurred, if any.
837 * @returns The number of bytes received.
839 template <typename MutableBufferSequence>
840 std::size_t receive_from(const MutableBufferSequence& buffers,
841 endpoint_type& sender_endpoint, socket_base::message_flags flags,
842 boost::system::error_code& ec)
844 return this->get_service().receive_from(this->get_implementation(),
845 buffers, sender_endpoint, flags, ec);
848 /// Start an asynchronous receive.
850 * This function is used to asynchronously receive a datagram. The function
851 * call always returns immediately.
853 * @param buffers One or more buffers into which the data will be received.
854 * Although the buffers object may be copied as necessary, ownership of the
855 * underlying memory blocks is retained by the caller, which must guarantee
856 * that they remain valid until the handler is called.
858 * @param sender_endpoint An endpoint object that receives the endpoint of
859 * the remote sender of the datagram. Ownership of the sender_endpoint object
860 * is retained by the caller, which must guarantee that it is valid until the
863 * @param handler The handler to be called when the receive operation
864 * completes. Copies will be made of the handler as required. The function
865 * signature of the handler must be:
866 * @code void handler(
867 * const boost::system::error_code& error, // Result of operation.
868 * std::size_t bytes_transferred // Number of bytes received.
870 * Regardless of whether the asynchronous operation completes immediately or
871 * not, the handler will not be invoked from within this function. Invocation
872 * of the handler will be performed in a manner equivalent to using
873 * boost::asio::io_service::post().
876 * To receive into a single data buffer use the @ref buffer function as
878 * @code socket.async_receive_from(
879 * boost::asio::buffer(data, size), sender_endpoint, handler); @endcode
880 * See the @ref buffer documentation for information on receiving into
881 * multiple buffers in one go, and how to use it with arrays, boost::array or
884 template <typename MutableBufferSequence, typename ReadHandler>
885 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
886 void (boost::system::error_code, std::size_t))
887 async_receive_from(const MutableBufferSequence& buffers,
888 endpoint_type& sender_endpoint,
889 BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
891 // If you get an error on the following line it means that your handler does
892 // not meet the documented type requirements for a ReadHandler.
893 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
895 return this->get_service().async_receive_from(
896 this->get_implementation(), buffers, sender_endpoint, 0,
897 BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
900 /// Start an asynchronous receive.
902 * This function is used to asynchronously receive a datagram. The function
903 * call always returns immediately.
905 * @param buffers One or more buffers into which the data will be received.
906 * Although the buffers object may be copied as necessary, ownership of the
907 * underlying memory blocks is retained by the caller, which must guarantee
908 * that they remain valid until the handler is called.
910 * @param sender_endpoint An endpoint object that receives the endpoint of
911 * the remote sender of the datagram. Ownership of the sender_endpoint object
912 * is retained by the caller, which must guarantee that it is valid until the
915 * @param flags Flags specifying how the receive call is to be made.
917 * @param handler The handler to be called when the receive operation
918 * completes. Copies will be made of the handler as required. The function
919 * signature of the handler must be:
920 * @code void handler(
921 * const boost::system::error_code& error, // Result of operation.
922 * std::size_t bytes_transferred // Number of bytes received.
924 * Regardless of whether the asynchronous operation completes immediately or
925 * not, the handler will not be invoked from within this function. Invocation
926 * of the handler will be performed in a manner equivalent to using
927 * boost::asio::io_service::post().
929 template <typename MutableBufferSequence, typename ReadHandler>
930 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
931 void (boost::system::error_code, std::size_t))
932 async_receive_from(const MutableBufferSequence& buffers,
933 endpoint_type& sender_endpoint, socket_base::message_flags flags,
934 BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
936 // If you get an error on the following line it means that your handler does
937 // not meet the documented type requirements for a ReadHandler.
938 BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
940 return this->get_service().async_receive_from(
941 this->get_implementation(), buffers, sender_endpoint, flags,
942 BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
949 #include <boost/asio/detail/pop_options.hpp>
951 #endif // BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP