asio/ip/address_v6.hpp

0001 //
0002 // ip/address_v6.hpp
0003 // ~~~~~~~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2025 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_IP_ADDRESS_V6_HPP
0012 #define BOOST_ASIO_IP_ADDRESS_V6_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 <functional>
0020 #include <string>
0021 #include <boost/asio/detail/array.hpp>
0022 #include <boost/asio/detail/cstdint.hpp>
0023 #include <boost/asio/detail/socket_types.hpp>
0024 #include <boost/asio/detail/string_view.hpp>
0025 #include <boost/asio/detail/winsock_init.hpp>
0026 #include <boost/system/error_code.hpp>
0027 #include <boost/asio/ip/address_v4.hpp>
0028
0029 #if !defined(BOOST_ASIO_NO_IOSTREAM)
0030 # include <iosfwd>
0031 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
0032
0033 #include <boost/asio/detail/push_options.hpp>
0034
0035 namespace boost {
0036 namespace asio {
0037 namespace ip {
0038
0039 template <typename> class basic_address_iterator;
0040
0041 /// Type used for storing IPv6 scope IDs.
0042 typedef uint_least32_t scope_id_type;
0043
0044 /// Implements IP version 6 style addresses.
0045 /**
0046  * The boost::asio::ip::address_v6 class provides the ability to use and
0047  * manipulate IP version 6 addresses.
0048  *
0049  * @par Thread Safety
0050  * @e Distinct @e objects: Safe.@n
0051  * @e Shared @e objects: Unsafe.
0052  */
0053 class address_v6
0054 {
0055 public:
0056   /// The type used to represent an address as an array of bytes.
0057   /**
0058    * @note This type is defined in terms of the C++0x template @c std::array
0059    * when it is available. Otherwise, it uses @c boost:array.
0060    */
0061 #if defined(GENERATING_DOCUMENTATION)
0062   typedef array<unsigned char, 16> bytes_type;
0063 #else
0064   typedef boost::asio::detail::array<unsigned char, 16> bytes_type;
0065 #endif
0066
0067   /// Default constructor.
0068   /**
0069    * Initialises the @c address_v6 object such that:
0070    * @li <tt>to_bytes()</tt> yields <tt>{0, 0, ..., 0}</tt>; and
0071    * @li <tt>scope_id() == 0</tt>.
0072    */
0073   BOOST_ASIO_DECL address_v6() noexcept;
0074
0075   /// Construct an address from raw bytes and scope ID.
0076   /**
0077    * Initialises the @c address_v6 object such that:
0078    * @li <tt>to_bytes() == bytes</tt>; and
0079    * @li <tt>this->scope_id() == scope_id</tt>.
0080    *
0081    * @throws out_of_range Thrown if any element in @c bytes is not in the range
0082    * <tt>0 - 0xFF</tt>. Note that no range checking is required for platforms
0083    * where <tt>std::numeric_limits<unsigned char>::max()</tt> is <tt>0xFF</tt>.
0084    */
0085   BOOST_ASIO_DECL explicit address_v6(const bytes_type& bytes,
0086       scope_id_type scope_id = 0);
0087
0088   /// Copy constructor.
0089   BOOST_ASIO_DECL address_v6(const address_v6& other) noexcept;
0090
0091   /// Move constructor.
0092   BOOST_ASIO_DECL address_v6(address_v6&& other) noexcept;
0093
0094   /// Assign from another address.
0095   BOOST_ASIO_DECL address_v6& operator=(
0096       const address_v6& other) noexcept;
0097
0098   /// Move-assign from another address.
0099   BOOST_ASIO_DECL address_v6& operator=(address_v6&& other) noexcept;
0100
0101   /// The scope ID of the address.
0102   /**
0103    * Returns the scope ID associated with the IPv6 address.
0104    */
0105   scope_id_type scope_id() const noexcept
0106   {
0107     return scope_id_;
0108   }
0109
0110   /// The scope ID of the address.
0111   /**
0112    * Modifies the scope ID associated with the IPv6 address.
0113    *
0114    * @param id The new scope ID.
0115    */
0116   void scope_id(scope_id_type id) noexcept
0117   {
0118     scope_id_ = id;
0119   }
0120
0121   /// Get the address in bytes, in network byte order.
0122   BOOST_ASIO_DECL bytes_type to_bytes() const noexcept;
0123
0124   /// Get the address as a string.
0125   BOOST_ASIO_DECL std::string to_string() const;
0126
0127   /// Determine whether the address is a loopback address.
0128   /**
0129    * This function tests whether the address is the loopback address
0130    * <tt>::1</tt>.
0131    */
0132   BOOST_ASIO_DECL bool is_loopback() const noexcept;
0133
0134   /// Determine whether the address is unspecified.
0135   /**
0136    * This function tests whether the address is the loopback address
0137    * <tt>::</tt>.
0138    */
0139   BOOST_ASIO_DECL bool is_unspecified() const noexcept;
0140
0141   /// Determine whether the address is link local.
0142   BOOST_ASIO_DECL bool is_link_local() const noexcept;
0143
0144   /// Determine whether the address is site local.
0145   BOOST_ASIO_DECL bool is_site_local() const noexcept;
0146
0147   /// Determine whether the address is a mapped IPv4 address.
0148   BOOST_ASIO_DECL bool is_v4_mapped() const noexcept;
0149
0150   /// Determine whether the address is a multicast address.
0151   BOOST_ASIO_DECL bool is_multicast() const noexcept;
0152
0153   /// Determine whether the address is a global multicast address.
0154   BOOST_ASIO_DECL bool is_multicast_global() const noexcept;
0155
0156   /// Determine whether the address is a link-local multicast address.
0157   BOOST_ASIO_DECL bool is_multicast_link_local() const noexcept;
0158
0159   /// Determine whether the address is a node-local multicast address.
0160   BOOST_ASIO_DECL bool is_multicast_node_local() const noexcept;
0161
0162   /// Determine whether the address is a org-local multicast address.
0163   BOOST_ASIO_DECL bool is_multicast_org_local() const noexcept;
0164
0165   /// Determine whether the address is a site-local multicast address.
0166   BOOST_ASIO_DECL bool is_multicast_site_local() const noexcept;
0167
0168   /// Compare two addresses for equality.
0169   BOOST_ASIO_DECL friend bool operator==(const address_v6& a1,
0170       const address_v6& a2) noexcept;
0171
0172   /// Compare two addresses for inequality.
0173   friend bool operator!=(const address_v6& a1,
0174       const address_v6& a2) noexcept
0175   {
0176     return !(a1 == a2);
0177   }
0178
0179   /// Compare addresses for ordering.
0180   BOOST_ASIO_DECL friend bool operator<(const address_v6& a1,
0181       const address_v6& a2) noexcept;
0182
0183   /// Compare addresses for ordering.
0184   friend bool operator>(const address_v6& a1,
0185       const address_v6& a2) noexcept
0186   {
0187     return a2 < a1;
0188   }
0189
0190   /// Compare addresses for ordering.
0191   friend bool operator<=(const address_v6& a1,
0192       const address_v6& a2) noexcept
0193   {
0194     return !(a2 < a1);
0195   }
0196
0197   /// Compare addresses for ordering.
0198   friend bool operator>=(const address_v6& a1,
0199       const address_v6& a2) noexcept
0200   {
0201     return !(a1 < a2);
0202   }
0203
0204   /// Obtain an address object that represents any address.
0205   /**
0206    * This functions returns an address that represents the "any" address
0207    * <tt>::</tt>.
0208    *
0209    * @returns A default-constructed @c address_v6 object.
0210    */
0211   static address_v6 any() noexcept
0212   {
0213     return address_v6();
0214   }
0215
0216   /// Obtain an address object that represents the loopback address.
0217   /**
0218    * This function returns an address that represents the well-known loopback
0219    * address <tt>::1</tt>.
0220    */
0221   BOOST_ASIO_DECL static address_v6 loopback() noexcept;
0222
0223 private:
0224   friend class basic_address_iterator<address_v6>;
0225
0226   // The underlying IPv6 address.
0227   boost::asio::detail::in6_addr_type addr_;
0228
0229   // The scope ID associated with the address.
0230   scope_id_type scope_id_;
0231 };
0232
0233 /// Create an IPv6 address from raw bytes and scope ID.
0234 /**
0235  * @relates address_v6
0236  */
0237 inline address_v6 make_address_v6(const address_v6::bytes_type& bytes,
0238     scope_id_type scope_id = 0)
0239 {
0240   return address_v6(bytes, scope_id);
0241 }
0242
0243 /// Create an IPv6 address from an IP address string.
0244 /**
0245  * @relates address_v6
0246  */
0247 BOOST_ASIO_DECL address_v6 make_address_v6(const char* str);
0248
0249 /// Create an IPv6 address from an IP address string.
0250 /**
0251  * @relates address_v6
0252  */
0253 BOOST_ASIO_DECL address_v6 make_address_v6(const char* str,
0254     boost::system::error_code& ec) noexcept;
0255
0256 /// Createan IPv6 address from an IP address string.
0257 /**
0258  * @relates address_v6
0259  */
0260 BOOST_ASIO_DECL address_v6 make_address_v6(const std::string& str);
0261
0262 /// Create an IPv6 address from an IP address string.
0263 /**
0264  * @relates address_v6
0265  */
0266 BOOST_ASIO_DECL address_v6 make_address_v6(const std::string& str,
0267     boost::system::error_code& ec) noexcept;
0268
0269 #if defined(BOOST_ASIO_HAS_STRING_VIEW) \
0270   || defined(GENERATING_DOCUMENTATION)
0271
0272 /// Create an IPv6 address from an IP address string.
0273 /**
0274  * @relates address_v6
0275  */
0276 BOOST_ASIO_DECL address_v6 make_address_v6(string_view str);
0277
0278 /// Create an IPv6 address from an IP address string.
0279 /**
0280  * @relates address_v6
0281  */
0282 BOOST_ASIO_DECL address_v6 make_address_v6(string_view str,
0283     boost::system::error_code& ec) noexcept;
0284
0285 #endif // defined(BOOST_ASIO_HAS_STRING_VIEW)
0286        //  || defined(GENERATING_DOCUMENTATION)
0287
0288 /// Tag type used for distinguishing overloads that deal in IPv4-mapped IPv6
0289 /// addresses.
0290 enum v4_mapped_t { v4_mapped };
0291
0292 /// Create an IPv4 address from a IPv4-mapped IPv6 address.
0293 /**
0294  * @relates address_v4
0295  */
0296 BOOST_ASIO_DECL address_v4 make_address_v4(
0297     v4_mapped_t, const address_v6& v6_addr);
0298
0299 /// Create an IPv4-mapped IPv6 address from an IPv4 address.
0300 /**
0301  * @relates address_v6
0302  */
0303 BOOST_ASIO_DECL address_v6 make_address_v6(
0304     v4_mapped_t, const address_v4& v4_addr);
0305
0306 #if !defined(BOOST_ASIO_NO_IOSTREAM)
0307
0308 /// Output an address as a string.
0309 /**
0310  * Used to output a human-readable string for a specified address.
0311  *
0312  * @param os The output stream to which the string will be written.
0313  *
0314  * @param addr The address to be written.
0315  *
0316  * @return The output stream.
0317  *
0318  * @relates boost::asio::ip::address_v6
0319  */
0320 template <typename Elem, typename Traits>
0321 std::basic_ostream<Elem, Traits>& operator<<(
0322     std::basic_ostream<Elem, Traits>& os, const address_v6& addr);
0323
0324 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
0325
0326 } // namespace ip
0327 } // namespace asio
0328 } // namespace boost
0329
0330 namespace std {
0331
0332 template <>
0333 struct hash<boost::asio::ip::address_v6>
0334 {
0335   std::size_t operator()(const boost::asio::ip::address_v6& addr)
0336     const noexcept
0337   {
0338     const boost::asio::ip::address_v6::bytes_type bytes = addr.to_bytes();
0339     std::size_t result = static_cast<std::size_t>(addr.scope_id());
0340     combine_4_bytes(result, &bytes[0]);
0341     combine_4_bytes(result, &bytes[4]);
0342     combine_4_bytes(result, &bytes[8]);
0343     combine_4_bytes(result, &bytes[12]);
0344     return result;
0345   }
0346
0347 private:
0348   static void combine_4_bytes(std::size_t& seed, const unsigned char* bytes)
0349   {
0350     const std::size_t bytes_hash =
0351       (static_cast<std::size_t>(bytes[0]) << 24) |
0352       (static_cast<std::size_t>(bytes[1]) << 16) |
0353       (static_cast<std::size_t>(bytes[2]) << 8) |
0354       (static_cast<std::size_t>(bytes[3]));
0355     seed ^= bytes_hash + 0x9e3779b9 + (seed << 6) + (seed >> 2);
0356   }
0357 };
0358
0359 } // namespace std
0360
0361 #include <boost/asio/detail/pop_options.hpp>
0362
0363 #include <boost/asio/ip/impl/address_v6.hpp>
0364 #if defined(BOOST_ASIO_HEADER_ONLY)
0365 # include <boost/asio/ip/impl/address_v6.ipp>
0366 #endif // defined(BOOST_ASIO_HEADER_ONLY)
0367
0368 #endif // BOOST_ASIO_IP_ADDRESS_V6_HPP