asio/ip/basic_resolver_query.hpp

0001 //
0002 // ip/basic_resolver_query.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_IP_BASIC_RESOLVER_QUERY_HPP
0012 #define BOOST_ASIO_IP_BASIC_RESOLVER_QUERY_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 <string>
0020 #include <boost/asio/detail/socket_ops.hpp>
0021 #include <boost/asio/ip/resolver_query_base.hpp>
0022
0023 #include <boost/asio/detail/push_options.hpp>
0024
0025 namespace boost {
0026 namespace asio {
0027 namespace ip {
0028
0029 /// An query to be passed to a resolver.
0030 /**
0031  * The boost::asio::ip::basic_resolver_query class template describes a query
0032  * that can be passed to a resolver.
0033  *
0034  * @par Thread Safety
0035  * @e Distinct @e objects: Safe.@n
0036  * @e Shared @e objects: Unsafe.
0037  */
0038 template <typename InternetProtocol>
0039 class basic_resolver_query
0040   : public resolver_query_base
0041 {
0042 public:
0043   /// The protocol type associated with the endpoint query.
0044   typedef InternetProtocol protocol_type;
0045
0046   /// Construct with specified service name for any protocol.
0047   /**
0048    * This constructor is typically used to perform name resolution for local
0049    * service binding.
0050    *
0051    * @param service A string identifying the requested service. This may be a
0052    * descriptive name or a numeric string corresponding to a port number.
0053    *
0054    * @param resolve_flags A set of flags that determine how name resolution
0055    * should be performed. The default flags are suitable for local service
0056    * binding.
0057    *
0058    * @note On POSIX systems, service names are typically defined in the file
0059    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
0060    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
0061    * may use additional locations when resolving service names.
0062    */
0063   basic_resolver_query(const std::string& service,
0064       resolver_query_base::flags resolve_flags = passive | address_configured)
0065     : hints_(),
0066       host_name_(),
0067       service_name_(service)
0068   {
0069     typename InternetProtocol::endpoint endpoint;
0070     hints_.ai_flags = static_cast<int>(resolve_flags);
0071     hints_.ai_family = PF_UNSPEC;
0072     hints_.ai_socktype = endpoint.protocol().type();
0073     hints_.ai_protocol = endpoint.protocol().protocol();
0074     hints_.ai_addrlen = 0;
0075     hints_.ai_canonname = 0;
0076     hints_.ai_addr = 0;
0077     hints_.ai_next = 0;
0078   }
0079
0080   /// Construct with specified service name for a given protocol.
0081   /**
0082    * This constructor is typically used to perform name resolution for local
0083    * service binding with a specific protocol version.
0084    *
0085    * @param protocol A protocol object, normally representing either the IPv4 or
0086    * IPv6 version of an internet protocol.
0087    *
0088    * @param service A string identifying the requested service. This may be a
0089    * descriptive name or a numeric string corresponding to a port number.
0090    *
0091    * @param resolve_flags A set of flags that determine how name resolution
0092    * should be performed. The default flags are suitable for local service
0093    * binding.
0094    *
0095    * @note On POSIX systems, service names are typically defined in the file
0096    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
0097    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
0098    * may use additional locations when resolving service names.
0099    */
0100   basic_resolver_query(const protocol_type& protocol,
0101       const std::string& service,
0102       resolver_query_base::flags resolve_flags = passive | address_configured)
0103     : hints_(),
0104       host_name_(),
0105       service_name_(service)
0106   {
0107     hints_.ai_flags = static_cast<int>(resolve_flags);
0108     hints_.ai_family = protocol.family();
0109     hints_.ai_socktype = protocol.type();
0110     hints_.ai_protocol = protocol.protocol();
0111     hints_.ai_addrlen = 0;
0112     hints_.ai_canonname = 0;
0113     hints_.ai_addr = 0;
0114     hints_.ai_next = 0;
0115   }
0116
0117   /// Construct with specified host name and service name for any protocol.
0118   /**
0119    * This constructor is typically used to perform name resolution for
0120    * communication with remote hosts.
0121    *
0122    * @param host A string identifying a location. May be a descriptive name or
0123    * a numeric address string. If an empty string and the passive flag has been
0124    * specified, the resolved endpoints are suitable for local service binding.
0125    * If an empty string and passive is not specified, the resolved endpoints
0126    * will use the loopback address.
0127    *
0128    * @param service A string identifying the requested service. This may be a
0129    * descriptive name or a numeric string corresponding to a port number. May
0130    * be an empty string, in which case all resolved endpoints will have a port
0131    * number of 0.
0132    *
0133    * @param resolve_flags A set of flags that determine how name resolution
0134    * should be performed. The default flags are suitable for communication with
0135    * remote hosts.
0136    *
0137    * @note On POSIX systems, host names may be locally defined in the file
0138    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
0139    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
0140    * resolution is performed using DNS. Operating systems may use additional
0141    * locations when resolving host names (such as NETBIOS names on Windows).
0142    *
0143    * On POSIX systems, service names are typically defined in the file
0144    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
0145    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
0146    * may use additional locations when resolving service names.
0147    */
0148   basic_resolver_query(const std::string& host, const std::string& service,
0149       resolver_query_base::flags resolve_flags = address_configured)
0150     : hints_(),
0151       host_name_(host),
0152       service_name_(service)
0153   {
0154     typename InternetProtocol::endpoint endpoint;
0155     hints_.ai_flags = static_cast<int>(resolve_flags);
0156     hints_.ai_family = BOOST_ASIO_OS_DEF(AF_UNSPEC);
0157     hints_.ai_socktype = endpoint.protocol().type();
0158     hints_.ai_protocol = endpoint.protocol().protocol();
0159     hints_.ai_addrlen = 0;
0160     hints_.ai_canonname = 0;
0161     hints_.ai_addr = 0;
0162     hints_.ai_next = 0;
0163   }
0164
0165   /// Construct with specified host name and service name for a given protocol.
0166   /**
0167    * This constructor is typically used to perform name resolution for
0168    * communication with remote hosts.
0169    *
0170    * @param protocol A protocol object, normally representing either the IPv4 or
0171    * IPv6 version of an internet protocol.
0172    *
0173    * @param host A string identifying a location. May be a descriptive name or
0174    * a numeric address string. If an empty string and the passive flag has been
0175    * specified, the resolved endpoints are suitable for local service binding.
0176    * If an empty string and passive is not specified, the resolved endpoints
0177    * will use the loopback address.
0178    *
0179    * @param service A string identifying the requested service. This may be a
0180    * descriptive name or a numeric string corresponding to a port number. May
0181    * be an empty string, in which case all resolved endpoints will have a port
0182    * number of 0.
0183    *
0184    * @param resolve_flags A set of flags that determine how name resolution
0185    * should be performed. The default flags are suitable for communication with
0186    * remote hosts.
0187    *
0188    * @note On POSIX systems, host names may be locally defined in the file
0189    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
0190    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
0191    * resolution is performed using DNS. Operating systems may use additional
0192    * locations when resolving host names (such as NETBIOS names on Windows).
0193    *
0194    * On POSIX systems, service names are typically defined in the file
0195    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
0196    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
0197    * may use additional locations when resolving service names.
0198    */
0199   basic_resolver_query(const protocol_type& protocol,
0200       const std::string& host, const std::string& service,
0201       resolver_query_base::flags resolve_flags = address_configured)
0202     : hints_(),
0203       host_name_(host),
0204       service_name_(service)
0205   {
0206     hints_.ai_flags = static_cast<int>(resolve_flags);
0207     hints_.ai_family = protocol.family();
0208     hints_.ai_socktype = protocol.type();
0209     hints_.ai_protocol = protocol.protocol();
0210     hints_.ai_addrlen = 0;
0211     hints_.ai_canonname = 0;
0212     hints_.ai_addr = 0;
0213     hints_.ai_next = 0;
0214   }
0215
0216   /// Get the hints associated with the query.
0217   const boost::asio::detail::addrinfo_type& hints() const
0218   {
0219     return hints_;
0220   }
0221
0222   /// Get the host name associated with the query.
0223   std::string host_name() const
0224   {
0225     return host_name_;
0226   }
0227
0228   /// Get the service name associated with the query.
0229   std::string service_name() const
0230   {
0231     return service_name_;
0232   }
0233
0234 private:
0235   boost::asio::detail::addrinfo_type hints_;
0236   std::string host_name_;
0237   std::string service_name_;
0238 };
0239
0240 } // namespace ip
0241 } // namespace asio
0242 } // namespace boost
0243
0244 #include <boost/asio/detail/pop_options.hpp>
0245
0246 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_QUERY_HPP