asio/ip/basic_resolver_results.hpp

0001 //
0002 // ip/basic_resolver_results.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_BASIC_RESOLVER_RESULTS_HPP
0012 #define BOOST_ASIO_IP_BASIC_RESOLVER_RESULTS_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 <cstddef>
0020 #include <cstring>
0021 #include <boost/asio/detail/socket_ops.hpp>
0022 #include <boost/asio/detail/socket_types.hpp>
0023 #include <boost/asio/ip/basic_resolver_iterator.hpp>
0024
0025 #if defined(BOOST_ASIO_WINDOWS_RUNTIME)
0026 # include <boost/asio/detail/winrt_utils.hpp>
0027 #endif // defined(BOOST_ASIO_WINDOWS_RUNTIME)
0028
0029 #include <boost/asio/detail/push_options.hpp>
0030
0031 namespace boost {
0032 namespace asio {
0033 namespace ip {
0034
0035 /// A range of entries produced by a resolver.
0036 /**
0037  * The boost::asio::ip::basic_resolver_results class template is used to define
0038  * a range over the results returned by a resolver.
0039  *
0040  * The iterator's value_type, obtained when a results iterator is dereferenced,
0041  * is: @code const basic_resolver_entry<InternetProtocol> @endcode
0042  *
0043  * @note For backward compatibility, basic_resolver_results is derived from
0044  * basic_resolver_iterator. This derivation is deprecated.
0045  *
0046  * @par Thread Safety
0047  * @e Distinct @e objects: Safe.@n
0048  * @e Shared @e objects: Unsafe.
0049  */
0050 template <typename InternetProtocol>
0051 class basic_resolver_results
0052   : private basic_resolver_iterator<InternetProtocol>
0053 {
0054 public:
0055   /// The protocol type associated with the results.
0056   typedef InternetProtocol protocol_type;
0057
0058   /// The endpoint type associated with the results.
0059   typedef typename protocol_type::endpoint endpoint_type;
0060
0061   /// The type of a value in the results range.
0062   typedef basic_resolver_entry<protocol_type> value_type;
0063
0064   /// The type of a const reference to a value in the range.
0065   typedef const value_type& const_reference;
0066
0067   /// The type of a non-const reference to a value in the range.
0068   typedef value_type& reference;
0069
0070   /// The type of an iterator into the range.
0071   typedef basic_resolver_iterator<protocol_type> const_iterator;
0072
0073   /// The type of an iterator into the range.
0074   typedef const_iterator iterator;
0075
0076   /// Type used to represent the distance between two iterators in the range.
0077   typedef std::ptrdiff_t difference_type;
0078
0079   /// Type used to represent a count of the elements in the range.
0080   typedef std::size_t size_type;
0081
0082   /// Default constructor creates an empty range.
0083   basic_resolver_results()
0084   {
0085   }
0086
0087   /// Copy constructor.
0088   basic_resolver_results(const basic_resolver_results& other)
0089     : basic_resolver_iterator<InternetProtocol>(other)
0090   {
0091   }
0092
0093   /// Move constructor.
0094   basic_resolver_results(basic_resolver_results&& other)
0095     : basic_resolver_iterator<InternetProtocol>(
0096         static_cast<basic_resolver_results&&>(other))
0097   {
0098   }
0099
0100   /// Assignment operator.
0101   basic_resolver_results& operator=(const basic_resolver_results& other)
0102   {
0103     basic_resolver_iterator<InternetProtocol>::operator=(other);
0104     return *this;
0105   }
0106
0107   /// Move-assignment operator.
0108   basic_resolver_results& operator=(basic_resolver_results&& other)
0109   {
0110     basic_resolver_iterator<InternetProtocol>::operator=(
0111         static_cast<basic_resolver_results&&>(other));
0112     return *this;
0113   }
0114
0115 #if !defined(GENERATING_DOCUMENTATION)
0116   // Create results from an addrinfo list returned by getaddrinfo.
0117   static basic_resolver_results create(
0118       boost::asio::detail::addrinfo_type* address_info,
0119       const std::string& host_name, const std::string& service_name)
0120   {
0121     basic_resolver_results results;
0122     if (!address_info)
0123       return results;
0124
0125     std::string actual_host_name = host_name;
0126     if (address_info->ai_canonname)
0127       actual_host_name = address_info->ai_canonname;
0128
0129     results.values_.reset(new values_type);
0130
0131     while (address_info)
0132     {
0133       if (address_info->ai_family == BOOST_ASIO_OS_DEF(AF_INET)
0134           || address_info->ai_family == BOOST_ASIO_OS_DEF(AF_INET6))
0135       {
0136         using namespace std; // For memcpy.
0137         typename InternetProtocol::endpoint endpoint;
0138         endpoint.resize(static_cast<std::size_t>(address_info->ai_addrlen));
0139         memcpy(endpoint.data(), address_info->ai_addr,
0140             address_info->ai_addrlen);
0141         results.values_->push_back(
0142             basic_resolver_entry<InternetProtocol>(endpoint,
0143               actual_host_name, service_name));
0144       }
0145       address_info = address_info->ai_next;
0146     }
0147
0148     return results;
0149   }
0150
0151   // Create results from an endpoint, host name and service name.
0152   static basic_resolver_results create(const endpoint_type& endpoint,
0153       const std::string& host_name, const std::string& service_name)
0154   {
0155     basic_resolver_results results;
0156     results.values_.reset(new values_type);
0157     results.values_->push_back(
0158         basic_resolver_entry<InternetProtocol>(
0159           endpoint, host_name, service_name));
0160     return results;
0161   }
0162
0163   // Create results from a sequence of endpoints, host and service name.
0164   template <typename EndpointIterator>
0165   static basic_resolver_results create(
0166       EndpointIterator begin, EndpointIterator end,
0167       const std::string& host_name, const std::string& service_name)
0168   {
0169     basic_resolver_results results;
0170     if (begin != end)
0171     {
0172       results.values_.reset(new values_type);
0173       for (EndpointIterator ep_iter = begin; ep_iter != end; ++ep_iter)
0174       {
0175         results.values_->push_back(
0176             basic_resolver_entry<InternetProtocol>(
0177               *ep_iter, host_name, service_name));
0178       }
0179     }
0180     return results;
0181   }
0182
0183 # if defined(BOOST_ASIO_WINDOWS_RUNTIME)
0184   // Create results from a Windows Runtime list of EndpointPair objects.
0185   static basic_resolver_results create(
0186       Windows::Foundation::Collections::IVectorView<
0187         Windows::Networking::EndpointPair^>^ endpoints,
0188       const boost::asio::detail::addrinfo_type& hints,
0189       const std::string& host_name, const std::string& service_name)
0190   {
0191     basic_resolver_results results;
0192     if (endpoints->Size)
0193     {
0194       results.values_.reset(new values_type);
0195       for (unsigned int i = 0; i < endpoints->Size; ++i)
0196       {
0197         auto pair = endpoints->GetAt(i);
0198
0199         if (hints.ai_family == BOOST_ASIO_OS_DEF(AF_INET)
0200             && pair->RemoteHostName->Type
0201               != Windows::Networking::HostNameType::Ipv4)
0202           continue;
0203
0204         if (hints.ai_family == BOOST_ASIO_OS_DEF(AF_INET6)
0205             && pair->RemoteHostName->Type
0206               != Windows::Networking::HostNameType::Ipv6)
0207           continue;
0208
0209         results.values_->push_back(
0210             basic_resolver_entry<InternetProtocol>(
0211               typename InternetProtocol::endpoint(
0212                 ip::make_address(
0213                   boost::asio::detail::winrt_utils::string(
0214                     pair->RemoteHostName->CanonicalName)),
0215                 boost::asio::detail::winrt_utils::integer(
0216                   pair->RemoteServiceName)),
0217               host_name, service_name));
0218       }
0219     }
0220     return results;
0221   }
0222 # endif // defined(BOOST_ASIO_WINDOWS_RUNTIME)
0223 #endif // !defined(GENERATING_DOCUMENTATION)
0224
0225   /// Get the number of entries in the results range.
0226   size_type size() const noexcept
0227   {
0228     return this->values_ ? this->values_->size() : 0;
0229   }
0230
0231   /// Get the maximum number of entries permitted in a results range.
0232   size_type max_size() const noexcept
0233   {
0234     return this->values_ ? this->values_->max_size() : values_type().max_size();
0235   }
0236
0237   /// Determine whether the results range is empty.
0238   bool empty() const noexcept
0239   {
0240     return this->values_ ? this->values_->empty() : true;
0241   }
0242
0243   /// Obtain a begin iterator for the results range.
0244   const_iterator begin() const
0245   {
0246     basic_resolver_results tmp(*this);
0247     tmp.index_ = 0;
0248     return static_cast<basic_resolver_results&&>(tmp);
0249   }
0250
0251   /// Obtain an end iterator for the results range.
0252   const_iterator end() const
0253   {
0254     return const_iterator();
0255   }
0256
0257   /// Obtain a begin iterator for the results range.
0258   const_iterator cbegin() const
0259   {
0260     return begin();
0261   }
0262
0263   /// Obtain an end iterator for the results range.
0264   const_iterator cend() const
0265   {
0266     return end();
0267   }
0268
0269   /// Swap the results range with another.
0270   void swap(basic_resolver_results& that) noexcept
0271   {
0272     if (this != &that)
0273     {
0274       this->values_.swap(that.values_);
0275       std::size_t index = this->index_;
0276       this->index_ = that.index_;
0277       that.index_ = index;
0278     }
0279   }
0280
0281   /// Test two iterators for equality.
0282   friend bool operator==(const basic_resolver_results& a,
0283       const basic_resolver_results& b)
0284   {
0285     return a.equal(b);
0286   }
0287
0288   /// Test two iterators for inequality.
0289   friend bool operator!=(const basic_resolver_results& a,
0290       const basic_resolver_results& b)
0291   {
0292     return !a.equal(b);
0293   }
0294
0295 private:
0296   typedef std::vector<basic_resolver_entry<InternetProtocol>> values_type;
0297 };
0298
0299 } // namespace ip
0300 } // namespace asio
0301 } // namespace boost
0302
0303 #include <boost/asio/detail/pop_options.hpp>
0304
0305 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_RESULTS_HPP