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