boost/asio/socket_base.hpp

0001 //
0002 // socket_base.hpp
0003 // ~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2023 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_SOCKET_BASE_HPP
0012 #define BOOST_ASIO_SOCKET_BASE_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019 #include <boost/asio/detail/io_control.hpp>
0020 #include <boost/asio/detail/socket_option.hpp>
0021 #include <boost/asio/detail/socket_types.hpp>
0022
0023 #include <boost/asio/detail/push_options.hpp>
0024
0025 namespace boost {
0026 namespace asio {
0027
0028 /// The socket_base class is used as a base for the basic_stream_socket and
0029 /// basic_datagram_socket class templates so that we have a common place to
0030 /// define the shutdown_type and enum.
0031 class socket_base
0032 {
0033 public:
0034   /// Different ways a socket may be shutdown.
0035   enum shutdown_type
0036   {
0037 #if defined(GENERATING_DOCUMENTATION)
0038     /// Shutdown the receive side of the socket.
0039     shutdown_receive = implementation_defined,
0040
0041     /// Shutdown the send side of the socket.
0042     shutdown_send = implementation_defined,
0043
0044     /// Shutdown both send and receive on the socket.
0045     shutdown_both = implementation_defined
0046 #else
0047     shutdown_receive = BOOST_ASIO_OS_DEF(SHUT_RD),
0048     shutdown_send = BOOST_ASIO_OS_DEF(SHUT_WR),
0049     shutdown_both = BOOST_ASIO_OS_DEF(SHUT_RDWR)
0050 #endif
0051   };
0052
0053   /// Bitmask type for flags that can be passed to send and receive operations.
0054   typedef int message_flags;
0055
0056 #if defined(GENERATING_DOCUMENTATION)
0057   /// Peek at incoming data without removing it from the input queue.
0058   static const int message_peek = implementation_defined;
0059
0060   /// Process out-of-band data.
0061   static const int message_out_of_band = implementation_defined;
0062
0063   /// Specify that the data should not be subject to routing.
0064   static const int message_do_not_route = implementation_defined;
0065
0066   /// Specifies that the data marks the end of a record.
0067   static const int message_end_of_record = implementation_defined;
0068 #else
0069   BOOST_ASIO_STATIC_CONSTANT(int,
0070       message_peek = BOOST_ASIO_OS_DEF(MSG_PEEK));
0071   BOOST_ASIO_STATIC_CONSTANT(int,
0072       message_out_of_band = BOOST_ASIO_OS_DEF(MSG_OOB));
0073   BOOST_ASIO_STATIC_CONSTANT(int,
0074       message_do_not_route = BOOST_ASIO_OS_DEF(MSG_DONTROUTE));
0075   BOOST_ASIO_STATIC_CONSTANT(int,
0076       message_end_of_record = BOOST_ASIO_OS_DEF(MSG_EOR));
0077 #endif
0078
0079   /// Wait types.
0080   /**
0081    * For use with basic_socket::wait() and basic_socket::async_wait().
0082    */
0083   enum wait_type
0084   {
0085     /// Wait for a socket to become ready to read.
0086     wait_read,
0087
0088     /// Wait for a socket to become ready to write.
0089     wait_write,
0090
0091     /// Wait for a socket to have error conditions pending.
0092     wait_error
0093   };
0094
0095   /// Socket option to permit sending of broadcast messages.
0096   /**
0097    * Implements the SOL_SOCKET/SO_BROADCAST socket option.
0098    *
0099    * @par Examples
0100    * Setting the option:
0101    * @code
0102    * boost::asio::ip::udp::socket socket(my_context);
0103    * ...
0104    * boost::asio::socket_base::broadcast option(true);
0105    * socket.set_option(option);
0106    * @endcode
0107    *
0108    * @par
0109    * Getting the current option value:
0110    * @code
0111    * boost::asio::ip::udp::socket socket(my_context);
0112    * ...
0113    * boost::asio::socket_base::broadcast option;
0114    * socket.get_option(option);
0115    * bool is_set = option.value();
0116    * @endcode
0117    *
0118    * @par Concepts:
0119    * Socket_Option, Boolean_Socket_Option.
0120    */
0121 #if defined(GENERATING_DOCUMENTATION)
0122   typedef implementation_defined broadcast;
0123 #else
0124   typedef boost::asio::detail::socket_option::boolean<
0125     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_BROADCAST)>
0126       broadcast;
0127 #endif
0128
0129   /// Socket option to enable socket-level debugging.
0130   /**
0131    * Implements the SOL_SOCKET/SO_DEBUG socket option.
0132    *
0133    * @par Examples
0134    * Setting the option:
0135    * @code
0136    * boost::asio::ip::tcp::socket socket(my_context);
0137    * ...
0138    * boost::asio::socket_base::debug option(true);
0139    * socket.set_option(option);
0140    * @endcode
0141    *
0142    * @par
0143    * Getting the current option value:
0144    * @code
0145    * boost::asio::ip::tcp::socket socket(my_context);
0146    * ...
0147    * boost::asio::socket_base::debug option;
0148    * socket.get_option(option);
0149    * bool is_set = option.value();
0150    * @endcode
0151    *
0152    * @par Concepts:
0153    * Socket_Option, Boolean_Socket_Option.
0154    */
0155 #if defined(GENERATING_DOCUMENTATION)
0156   typedef implementation_defined debug;
0157 #else
0158   typedef boost::asio::detail::socket_option::boolean<
0159     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_DEBUG)> debug;
0160 #endif
0161
0162   /// Socket option to prevent routing, use local interfaces only.
0163   /**
0164    * Implements the SOL_SOCKET/SO_DONTROUTE socket option.
0165    *
0166    * @par Examples
0167    * Setting the option:
0168    * @code
0169    * boost::asio::ip::udp::socket socket(my_context);
0170    * ...
0171    * boost::asio::socket_base::do_not_route option(true);
0172    * socket.set_option(option);
0173    * @endcode
0174    *
0175    * @par
0176    * Getting the current option value:
0177    * @code
0178    * boost::asio::ip::udp::socket socket(my_context);
0179    * ...
0180    * boost::asio::socket_base::do_not_route option;
0181    * socket.get_option(option);
0182    * bool is_set = option.value();
0183    * @endcode
0184    *
0185    * @par Concepts:
0186    * Socket_Option, Boolean_Socket_Option.
0187    */
0188 #if defined(GENERATING_DOCUMENTATION)
0189   typedef implementation_defined do_not_route;
0190 #else
0191   typedef boost::asio::detail::socket_option::boolean<
0192     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_DONTROUTE)>
0193       do_not_route;
0194 #endif
0195
0196   /// Socket option to send keep-alives.
0197   /**
0198    * Implements the SOL_SOCKET/SO_KEEPALIVE socket option.
0199    *
0200    * @par Examples
0201    * Setting the option:
0202    * @code
0203    * boost::asio::ip::tcp::socket socket(my_context);
0204    * ...
0205    * boost::asio::socket_base::keep_alive option(true);
0206    * socket.set_option(option);
0207    * @endcode
0208    *
0209    * @par
0210    * Getting the current option value:
0211    * @code
0212    * boost::asio::ip::tcp::socket socket(my_context);
0213    * ...
0214    * boost::asio::socket_base::keep_alive option;
0215    * socket.get_option(option);
0216    * bool is_set = option.value();
0217    * @endcode
0218    *
0219    * @par Concepts:
0220    * Socket_Option, Boolean_Socket_Option.
0221    */
0222 #if defined(GENERATING_DOCUMENTATION)
0223   typedef implementation_defined keep_alive;
0224 #else
0225   typedef boost::asio::detail::socket_option::boolean<
0226     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_KEEPALIVE)> keep_alive;
0227 #endif
0228
0229   /// Socket option for the send buffer size of a socket.
0230   /**
0231    * Implements the SOL_SOCKET/SO_SNDBUF socket option.
0232    *
0233    * @par Examples
0234    * Setting the option:
0235    * @code
0236    * boost::asio::ip::tcp::socket socket(my_context);
0237    * ...
0238    * boost::asio::socket_base::send_buffer_size option(8192);
0239    * socket.set_option(option);
0240    * @endcode
0241    *
0242    * @par
0243    * Getting the current option value:
0244    * @code
0245    * boost::asio::ip::tcp::socket socket(my_context);
0246    * ...
0247    * boost::asio::socket_base::send_buffer_size option;
0248    * socket.get_option(option);
0249    * int size = option.value();
0250    * @endcode
0251    *
0252    * @par Concepts:
0253    * Socket_Option, Integer_Socket_Option.
0254    */
0255 #if defined(GENERATING_DOCUMENTATION)
0256   typedef implementation_defined send_buffer_size;
0257 #else
0258   typedef boost::asio::detail::socket_option::integer<
0259     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_SNDBUF)>
0260       send_buffer_size;
0261 #endif
0262
0263   /// Socket option for the send low watermark.
0264   /**
0265    * Implements the SOL_SOCKET/SO_SNDLOWAT socket option.
0266    *
0267    * @par Examples
0268    * Setting the option:
0269    * @code
0270    * boost::asio::ip::tcp::socket socket(my_context);
0271    * ...
0272    * boost::asio::socket_base::send_low_watermark option(1024);
0273    * socket.set_option(option);
0274    * @endcode
0275    *
0276    * @par
0277    * Getting the current option value:
0278    * @code
0279    * boost::asio::ip::tcp::socket socket(my_context);
0280    * ...
0281    * boost::asio::socket_base::send_low_watermark option;
0282    * socket.get_option(option);
0283    * int size = option.value();
0284    * @endcode
0285    *
0286    * @par Concepts:
0287    * Socket_Option, Integer_Socket_Option.
0288    */
0289 #if defined(GENERATING_DOCUMENTATION)
0290   typedef implementation_defined send_low_watermark;
0291 #else
0292   typedef boost::asio::detail::socket_option::integer<
0293     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_SNDLOWAT)>
0294       send_low_watermark;
0295 #endif
0296
0297   /// Socket option for the receive buffer size of a socket.
0298   /**
0299    * Implements the SOL_SOCKET/SO_RCVBUF socket option.
0300    *
0301    * @par Examples
0302    * Setting the option:
0303    * @code
0304    * boost::asio::ip::tcp::socket socket(my_context);
0305    * ...
0306    * boost::asio::socket_base::receive_buffer_size option(8192);
0307    * socket.set_option(option);
0308    * @endcode
0309    *
0310    * @par
0311    * Getting the current option value:
0312    * @code
0313    * boost::asio::ip::tcp::socket socket(my_context);
0314    * ...
0315    * boost::asio::socket_base::receive_buffer_size option;
0316    * socket.get_option(option);
0317    * int size = option.value();
0318    * @endcode
0319    *
0320    * @par Concepts:
0321    * Socket_Option, Integer_Socket_Option.
0322    */
0323 #if defined(GENERATING_DOCUMENTATION)
0324   typedef implementation_defined receive_buffer_size;
0325 #else
0326   typedef boost::asio::detail::socket_option::integer<
0327     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_RCVBUF)>
0328       receive_buffer_size;
0329 #endif
0330
0331   /// Socket option for the receive low watermark.
0332   /**
0333    * Implements the SOL_SOCKET/SO_RCVLOWAT socket option.
0334    *
0335    * @par Examples
0336    * Setting the option:
0337    * @code
0338    * boost::asio::ip::tcp::socket socket(my_context);
0339    * ...
0340    * boost::asio::socket_base::receive_low_watermark option(1024);
0341    * socket.set_option(option);
0342    * @endcode
0343    *
0344    * @par
0345    * Getting the current option value:
0346    * @code
0347    * boost::asio::ip::tcp::socket socket(my_context);
0348    * ...
0349    * boost::asio::socket_base::receive_low_watermark option;
0350    * socket.get_option(option);
0351    * int size = option.value();
0352    * @endcode
0353    *
0354    * @par Concepts:
0355    * Socket_Option, Integer_Socket_Option.
0356    */
0357 #if defined(GENERATING_DOCUMENTATION)
0358   typedef implementation_defined receive_low_watermark;
0359 #else
0360   typedef boost::asio::detail::socket_option::integer<
0361     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_RCVLOWAT)>
0362       receive_low_watermark;
0363 #endif
0364
0365   /// Socket option to allow the socket to be bound to an address that is
0366   /// already in use.
0367   /**
0368    * Implements the SOL_SOCKET/SO_REUSEADDR socket option.
0369    *
0370    * @par Examples
0371    * Setting the option:
0372    * @code
0373    * boost::asio::ip::tcp::acceptor acceptor(my_context);
0374    * ...
0375    * boost::asio::socket_base::reuse_address option(true);
0376    * acceptor.set_option(option);
0377    * @endcode
0378    *
0379    * @par
0380    * Getting the current option value:
0381    * @code
0382    * boost::asio::ip::tcp::acceptor acceptor(my_context);
0383    * ...
0384    * boost::asio::socket_base::reuse_address option;
0385    * acceptor.get_option(option);
0386    * bool is_set = option.value();
0387    * @endcode
0388    *
0389    * @par Concepts:
0390    * Socket_Option, Boolean_Socket_Option.
0391    */
0392 #if defined(GENERATING_DOCUMENTATION)
0393   typedef implementation_defined reuse_address;
0394 #else
0395   typedef boost::asio::detail::socket_option::boolean<
0396     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_REUSEADDR)>
0397       reuse_address;
0398 #endif
0399
0400   /// Socket option to specify whether the socket lingers on close if unsent
0401   /// data is present.
0402   /**
0403    * Implements the SOL_SOCKET/SO_LINGER socket option.
0404    *
0405    * @par Examples
0406    * Setting the option:
0407    * @code
0408    * boost::asio::ip::tcp::socket socket(my_context);
0409    * ...
0410    * boost::asio::socket_base::linger option(true, 30);
0411    * socket.set_option(option);
0412    * @endcode
0413    *
0414    * @par
0415    * Getting the current option value:
0416    * @code
0417    * boost::asio::ip::tcp::socket socket(my_context);
0418    * ...
0419    * boost::asio::socket_base::linger option;
0420    * socket.get_option(option);
0421    * bool is_set = option.enabled();
0422    * unsigned short timeout = option.timeout();
0423    * @endcode
0424    *
0425    * @par Concepts:
0426    * Socket_Option, Linger_Socket_Option.
0427    */
0428 #if defined(GENERATING_DOCUMENTATION)
0429   typedef implementation_defined linger;
0430 #else
0431   typedef boost::asio::detail::socket_option::linger<
0432     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_LINGER)>
0433       linger;
0434 #endif
0435
0436   /// Socket option for putting received out-of-band data inline.
0437   /**
0438    * Implements the SOL_SOCKET/SO_OOBINLINE socket option.
0439    *
0440    * @par Examples
0441    * Setting the option:
0442    * @code
0443    * boost::asio::ip::tcp::socket socket(my_context);
0444    * ...
0445    * boost::asio::socket_base::out_of_band_inline option(true);
0446    * socket.set_option(option);
0447    * @endcode
0448    *
0449    * @par
0450    * Getting the current option value:
0451    * @code
0452    * boost::asio::ip::tcp::socket socket(my_context);
0453    * ...
0454    * boost::asio::socket_base::out_of_band_inline option;
0455    * socket.get_option(option);
0456    * bool value = option.value();
0457    * @endcode
0458    *
0459    * @par Concepts:
0460    * Socket_Option, Boolean_Socket_Option.
0461    */
0462 #if defined(GENERATING_DOCUMENTATION)
0463   typedef implementation_defined out_of_band_inline;
0464 #else
0465   typedef boost::asio::detail::socket_option::boolean<
0466     BOOST_ASIO_OS_DEF(SOL_SOCKET), BOOST_ASIO_OS_DEF(SO_OOBINLINE)>
0467       out_of_band_inline;
0468 #endif
0469
0470   /// Socket option to report aborted connections on accept.
0471   /**
0472    * Implements a custom socket option that determines whether or not an accept
0473    * operation is permitted to fail with boost::asio::error::connection_aborted.
0474    * By default the option is false.
0475    *
0476    * @par Examples
0477    * Setting the option:
0478    * @code
0479    * boost::asio::ip::tcp::acceptor acceptor(my_context);
0480    * ...
0481    * boost::asio::socket_base::enable_connection_aborted option(true);
0482    * acceptor.set_option(option);
0483    * @endcode
0484    *
0485    * @par
0486    * Getting the current option value:
0487    * @code
0488    * boost::asio::ip::tcp::acceptor acceptor(my_context);
0489    * ...
0490    * boost::asio::socket_base::enable_connection_aborted option;
0491    * acceptor.get_option(option);
0492    * bool is_set = option.value();
0493    * @endcode
0494    *
0495    * @par Concepts:
0496    * Socket_Option, Boolean_Socket_Option.
0497    */
0498 #if defined(GENERATING_DOCUMENTATION)
0499   typedef implementation_defined enable_connection_aborted;
0500 #else
0501   typedef boost::asio::detail::socket_option::boolean<
0502     boost::asio::detail::custom_socket_option_level,
0503     boost::asio::detail::enable_connection_aborted_option>
0504     enable_connection_aborted;
0505 #endif
0506
0507   /// IO control command to get the amount of data that can be read without
0508   /// blocking.
0509   /**
0510    * Implements the FIONREAD IO control command.
0511    *
0512    * @par Example
0513    * @code
0514    * boost::asio::ip::tcp::socket socket(my_context);
0515    * ...
0516    * boost::asio::socket_base::bytes_readable command(true);
0517    * socket.io_control(command);
0518    * std::size_t bytes_readable = command.get();
0519    * @endcode
0520    *
0521    * @par Concepts:
0522    * IO_Control_Command, Size_IO_Control_Command.
0523    */
0524 #if defined(GENERATING_DOCUMENTATION)
0525   typedef implementation_defined bytes_readable;
0526 #else
0527   typedef boost::asio::detail::io_control::bytes_readable bytes_readable;
0528 #endif
0529
0530   /// The maximum length of the queue of pending incoming connections.
0531 #if defined(GENERATING_DOCUMENTATION)
0532   static const int max_listen_connections = implementation_defined;
0533 #else
0534   BOOST_ASIO_STATIC_CONSTANT(int, max_listen_connections
0535       = BOOST_ASIO_OS_DEF(SOMAXCONN));
0536 #endif
0537
0538 #if !defined(BOOST_ASIO_NO_DEPRECATED)
0539   /// (Deprecated: Use max_listen_connections.) The maximum length of the queue
0540   /// of pending incoming connections.
0541 #if defined(GENERATING_DOCUMENTATION)
0542   static const int max_connections = implementation_defined;
0543 #else
0544   BOOST_ASIO_STATIC_CONSTANT(int, max_connections
0545       = BOOST_ASIO_OS_DEF(SOMAXCONN));
0546 #endif
0547 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
0548
0549 protected:
0550   /// Protected destructor to prevent deletion through this type.
0551   ~socket_base()
0552   {
0553   }
0554 };
0555
0556 } // namespace asio
0557 } // namespace boost
0558
0559 #include <boost/asio/detail/pop_options.hpp>
0560
0561 #endif // BOOST_ASIO_SOCKET_BASE_HPP