boost/asio/ip/basic_endpoint.hpp

   1 //
   2 // ip/basic_endpoint.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 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_IP_BASIC_ENDPOINT_HPP
  12 #define BOOST_ASIO_IP_BASIC_ENDPOINT_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 <boost/asio/ip/address.hpp>
  20 #include <boost/asio/ip/detail/endpoint.hpp>
  21
  22 #if !defined(BOOST_ASIO_NO_IOSTREAM)
  23 # include <iosfwd>
  24 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
  25
  26 #include <boost/asio/detail/push_options.hpp>
  27
  28 namespace boost {
  29 namespace asio {
  30 namespace ip {
  31
  32 /// Describes an endpoint for a version-independent IP socket.
  33 /**
  34  * The boost::asio::ip::basic_endpoint class template describes an endpoint that
  35  * may be associated with a particular socket.
  36  *
  37  * @par Thread Safety
  38  * @e Distinct @e objects: Safe.@n
  39  * @e Shared @e objects: Unsafe.
  40  *
  41  * @par Concepts:
  42  * Endpoint.
  43  */
  44 template <typename InternetProtocol>
  45 class basic_endpoint
  46 {
  47 public:
  48   /// The protocol type associated with the endpoint.
  49   typedef InternetProtocol protocol_type;
  50
  51   /// The type of the endpoint structure. This type is dependent on the
  52   /// underlying implementation of the socket layer.
  53 #if defined(GENERATING_DOCUMENTATION)
  54   typedef implementation_defined data_type;
  55 #else
  56   typedef boost::asio::detail::socket_addr_type data_type;
  57 #endif
  58
  59   /// Default constructor.
  60   basic_endpoint() BOOST_ASIO_NOEXCEPT
  61     : impl_()
  62   {
  63   }
  64
  65   /// Construct an endpoint using a port number, specified in the host's byte
  66   /// order. The IP address will be the any address (i.e. INADDR_ANY or
  67   /// in6addr_any). This constructor would typically be used for accepting new
  68   /// connections.
  69   /**
  70    * @par Examples
  71    * To initialise an IPv4 TCP endpoint for port 1234, use:
  72    * @code
  73    * boost::asio::ip::tcp::endpoint ep(boost::asio::ip::tcp::v4(), 1234);
  74    * @endcode
  75    *
  76    * To specify an IPv6 UDP endpoint for port 9876, use:
  77    * @code
  78    * boost::asio::ip::udp::endpoint ep(boost::asio::ip::udp::v6(), 9876);
  79    * @endcode
  80    */
  81   basic_endpoint(const InternetProtocol& internet_protocol,
  82       unsigned short port_num) BOOST_ASIO_NOEXCEPT
  83     : impl_(internet_protocol.family(), port_num)
  84   {
  85   }
  86
  87   /// Construct an endpoint using a port number and an IP address. This
  88   /// constructor may be used for accepting connections on a specific interface
  89   /// or for making a connection to a remote endpoint.
  90   basic_endpoint(const boost::asio::ip::address& addr,
  91       unsigned short port_num) BOOST_ASIO_NOEXCEPT
  92     : impl_(addr, port_num)
  93   {
  94   }
  95
  96   /// Copy constructor.
  97   basic_endpoint(const basic_endpoint& other) BOOST_ASIO_NOEXCEPT
  98     : impl_(other.impl_)
  99   {
 100   }
 101
 102 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 103   /// Move constructor.
 104   basic_endpoint(basic_endpoint&& other) BOOST_ASIO_NOEXCEPT
 105     : impl_(other.impl_)
 106   {
 107   }
 108 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 109
 110   /// Assign from another endpoint.
 111   basic_endpoint& operator=(const basic_endpoint& other) BOOST_ASIO_NOEXCEPT
 112   {
 113     impl_ = other.impl_;
 114     return *this;
 115   }
 116
 117 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 118   /// Move-assign from another endpoint.
 119   basic_endpoint& operator=(basic_endpoint&& other) BOOST_ASIO_NOEXCEPT
 120   {
 121     impl_ = other.impl_;
 122     return *this;
 123   }
 124 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 125
 126   /// The protocol associated with the endpoint.
 127   protocol_type protocol() const BOOST_ASIO_NOEXCEPT
 128   {
 129     if (impl_.is_v4())
 130       return InternetProtocol::v4();
 131     return InternetProtocol::v6();
 132   }
 133
 134   /// Get the underlying endpoint in the native type.
 135   data_type* data() BOOST_ASIO_NOEXCEPT
 136   {
 137     return impl_.data();
 138   }
 139
 140   /// Get the underlying endpoint in the native type.
 141   const data_type* data() const BOOST_ASIO_NOEXCEPT
 142   {
 143     return impl_.data();
 144   }
 145
 146   /// Get the underlying size of the endpoint in the native type.
 147   std::size_t size() const BOOST_ASIO_NOEXCEPT
 148   {
 149     return impl_.size();
 150   }
 151
 152   /// Set the underlying size of the endpoint in the native type.
 153   void resize(std::size_t new_size)
 154   {
 155     impl_.resize(new_size);
 156   }
 157
 158   /// Get the capacity of the endpoint in the native type.
 159   std::size_t capacity() const BOOST_ASIO_NOEXCEPT
 160   {
 161     return impl_.capacity();
 162   }
 163
 164   /// Get the port associated with the endpoint. The port number is always in
 165   /// the host's byte order.
 166   unsigned short port() const BOOST_ASIO_NOEXCEPT
 167   {
 168     return impl_.port();
 169   }
 170
 171   /// Set the port associated with the endpoint. The port number is always in
 172   /// the host's byte order.
 173   void port(unsigned short port_num) BOOST_ASIO_NOEXCEPT
 174   {
 175     impl_.port(port_num);
 176   }
 177
 178   /// Get the IP address associated with the endpoint.
 179   boost::asio::ip::address address() const BOOST_ASIO_NOEXCEPT
 180   {
 181     return impl_.address();
 182   }
 183
 184   /// Set the IP address associated with the endpoint.
 185   void address(const boost::asio::ip::address& addr) BOOST_ASIO_NOEXCEPT
 186   {
 187     impl_.address(addr);
 188   }
 189
 190   /// Compare two endpoints for equality.
 191   friend bool operator==(const basic_endpoint<InternetProtocol>& e1,
 192       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 193   {
 194     return e1.impl_ == e2.impl_;
 195   }
 196
 197   /// Compare two endpoints for inequality.
 198   friend bool operator!=(const basic_endpoint<InternetProtocol>& e1,
 199       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 200   {
 201     return !(e1 == e2);
 202   }
 203
 204   /// Compare endpoints for ordering.
 205   friend bool operator<(const basic_endpoint<InternetProtocol>& e1,
 206       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 207   {
 208     return e1.impl_ < e2.impl_;
 209   }
 210
 211   /// Compare endpoints for ordering.
 212   friend bool operator>(const basic_endpoint<InternetProtocol>& e1,
 213       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 214   {
 215     return e2.impl_ < e1.impl_;
 216   }
 217
 218   /// Compare endpoints for ordering.
 219   friend bool operator<=(const basic_endpoint<InternetProtocol>& e1,
 220       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 221   {
 222     return !(e2 < e1);
 223   }
 224
 225   /// Compare endpoints for ordering.
 226   friend bool operator>=(const basic_endpoint<InternetProtocol>& e1,
 227       const basic_endpoint<InternetProtocol>& e2) BOOST_ASIO_NOEXCEPT
 228   {
 229     return !(e1 < e2);
 230   }
 231
 232 private:
 233   // The underlying IP endpoint.
 234   boost::asio::ip::detail::endpoint impl_;
 235 };
 236
 237 #if !defined(BOOST_ASIO_NO_IOSTREAM)
 238
 239 /// Output an endpoint as a string.
 240 /**
 241  * Used to output a human-readable string for a specified endpoint.
 242  *
 243  * @param os The output stream to which the string will be written.
 244  *
 245  * @param endpoint The endpoint to be written.
 246  *
 247  * @return The output stream.
 248  *
 249  * @relates boost::asio::ip::basic_endpoint
 250  */
 251 template <typename Elem, typename Traits, typename InternetProtocol>
 252 std::basic_ostream<Elem, Traits>& operator<<(
 253     std::basic_ostream<Elem, Traits>& os,
 254     const basic_endpoint<InternetProtocol>& endpoint);
 255
 256 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
 257
 258 } // namespace ip
 259 } // namespace asio
 260 } // namespace boost
 261
 262 #include <boost/asio/detail/pop_options.hpp>
 263
 264 #include <boost/asio/ip/impl/basic_endpoint.hpp>
 265
 266 #endif // BOOST_ASIO_IP_BASIC_ENDPOINT_HPP