boost/asio/ip/basic_resolver.hpp

   1 //
   2 // ip/basic_resolver.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2017 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_RESOLVER_HPP
  12 #define BOOST_ASIO_IP_BASIC_RESOLVER_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/basic_io_object.hpp>
  20 #include <boost/asio/detail/handler_type_requirements.hpp>
  21 #include <boost/asio/detail/throw_error.hpp>
  22 #include <boost/asio/error.hpp>
  23 #include <boost/asio/ip/basic_resolver_iterator.hpp>
  24 #include <boost/asio/ip/basic_resolver_query.hpp>
  25 #include <boost/asio/ip/resolver_service.hpp>
  26
  27 #include <boost/asio/detail/push_options.hpp>
  28
  29 namespace boost {
  30 namespace asio {
  31 namespace ip {
  32
  33 /// Provides endpoint resolution functionality.
  34 /**
  35  * The basic_resolver class template provides the ability to resolve a query
  36  * to a list of endpoints.
  37  *
  38  * @par Thread Safety
  39  * @e Distinct @e objects: Safe.@n
  40  * @e Shared @e objects: Unsafe.
  41  */
  42 template <typename InternetProtocol,
  43     typename ResolverService = resolver_service<InternetProtocol> >
  44 class basic_resolver
  45   : public basic_io_object<ResolverService>
  46 {
  47 public:
  48   /// The protocol type.
  49   typedef InternetProtocol protocol_type;
  50
  51   /// The endpoint type.
  52   typedef typename InternetProtocol::endpoint endpoint_type;
  53
  54   /// The query type.
  55   typedef basic_resolver_query<InternetProtocol> query;
  56
  57   /// The iterator type.
  58   typedef basic_resolver_iterator<InternetProtocol> iterator;
  59
  60   /// Constructor.
  61   /**
  62    * This constructor creates a basic_resolver.
  63    *
  64    * @param io_service The io_service object that the resolver will use to
  65    * dispatch handlers for any asynchronous operations performed on the timer.
  66    */
  67   explicit basic_resolver(boost::asio::io_service& io_service)
  68     : basic_io_object<ResolverService>(io_service)
  69   {
  70   }
  71
  72   /// Cancel any asynchronous operations that are waiting on the resolver.
  73   /**
  74    * This function forces the completion of any pending asynchronous
  75    * operations on the host resolver. The handler for each cancelled operation
  76    * will be invoked with the boost::asio::error::operation_aborted error code.
  77    */
  78   void cancel()
  79   {
  80     return this->service.cancel(this->implementation);
  81   }
  82
  83   /// Perform forward resolution of a query to a list of entries.
  84   /**
  85    * This function is used to resolve a query into a list of endpoint entries.
  86    *
  87    * @param q A query object that determines what endpoints will be returned.
  88    *
  89    * @returns A forward-only iterator that can be used to traverse the list
  90    * of endpoint entries.
  91    *
  92    * @throws boost::system::system_error Thrown on failure.
  93    *
  94    * @note A default constructed iterator represents the end of the list.
  95    *
  96    * A successful call to this function is guaranteed to return at least one
  97    * entry.
  98    */
  99   iterator resolve(const query& q)
 100   {
 101     boost::system::error_code ec;
 102     iterator i = this->service.resolve(this->implementation, q, ec);
 103     boost::asio::detail::throw_error(ec, "resolve");
 104     return i;
 105   }
 106
 107   /// Perform forward resolution of a query to a list of entries.
 108   /**
 109    * This function is used to resolve a query into a list of endpoint entries.
 110    *
 111    * @param q A query object that determines what endpoints will be returned.
 112    *
 113    * @param ec Set to indicate what error occurred, if any.
 114    *
 115    * @returns A forward-only iterator that can be used to traverse the list
 116    * of endpoint entries. Returns a default constructed iterator if an error
 117    * occurs.
 118    *
 119    * @note A default constructed iterator represents the end of the list.
 120    *
 121    * A successful call to this function is guaranteed to return at least one
 122    * entry.
 123    */
 124   iterator resolve(const query& q, boost::system::error_code& ec)
 125   {
 126     return this->service.resolve(this->implementation, q, ec);
 127   }
 128
 129   /// Asynchronously perform forward resolution of a query to a list of entries.
 130   /**
 131    * This function is used to asynchronously resolve a query into a list of
 132    * endpoint entries.
 133    *
 134    * @param q A query object that determines what endpoints will be returned.
 135    *
 136    * @param handler The handler to be called when the resolve operation
 137    * completes. Copies will be made of the handler as required. The function
 138    * signature of the handler must be:
 139    * @code void handler(
 140    *   const boost::system::error_code& error, // Result of operation.
 141    *   resolver::iterator iterator             // Forward-only iterator that can
 142    *                                           // be used to traverse the list
 143    *                                           // of endpoint entries.
 144    * ); @endcode
 145    * Regardless of whether the asynchronous operation completes immediately or
 146    * not, the handler will not be invoked from within this function. Invocation
 147    * of the handler will be performed in a manner equivalent to using
 148    * boost::asio::io_service::post().
 149    *
 150    * @note A default constructed iterator represents the end of the list.
 151    *
 152    * A successful resolve operation is guaranteed to pass at least one entry to
 153    * the handler.
 154    */
 155   template <typename ResolveHandler>
 156   BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
 157       void (boost::system::error_code, iterator))
 158   async_resolve(const query& q,
 159       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
 160   {
 161     // If you get an error on the following line it means that your handler does
 162     // not meet the documented type requirements for a ResolveHandler.
 163     BOOST_ASIO_RESOLVE_HANDLER_CHECK(
 164         ResolveHandler, handler, iterator) type_check;
 165
 166     return this->service.async_resolve(this->implementation, q,
 167         BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
 168   }
 169
 170   /// Perform reverse resolution of an endpoint to a list of entries.
 171   /**
 172    * This function is used to resolve an endpoint into a list of endpoint
 173    * entries.
 174    *
 175    * @param e An endpoint object that determines what endpoints will be
 176    * returned.
 177    *
 178    * @returns A forward-only iterator that can be used to traverse the list
 179    * of endpoint entries.
 180    *
 181    * @throws boost::system::system_error Thrown on failure.
 182    *
 183    * @note A default constructed iterator represents the end of the list.
 184    *
 185    * A successful call to this function is guaranteed to return at least one
 186    * entry.
 187    */
 188   iterator resolve(const endpoint_type& e)
 189   {
 190     boost::system::error_code ec;
 191     iterator i = this->service.resolve(this->implementation, e, ec);
 192     boost::asio::detail::throw_error(ec, "resolve");
 193     return i;
 194   }
 195
 196   /// Perform reverse resolution of an endpoint to a list of entries.
 197   /**
 198    * This function is used to resolve an endpoint into a list of endpoint
 199    * entries.
 200    *
 201    * @param e An endpoint object that determines what endpoints will be
 202    * returned.
 203    *
 204    * @param ec Set to indicate what error occurred, if any.
 205    *
 206    * @returns A forward-only iterator that can be used to traverse the list
 207    * of endpoint entries. Returns a default constructed iterator if an error
 208    * occurs.
 209    *
 210    * @note A default constructed iterator represents the end of the list.
 211    *
 212    * A successful call to this function is guaranteed to return at least one
 213    * entry.
 214    */
 215   iterator resolve(const endpoint_type& e, boost::system::error_code& ec)
 216   {
 217     return this->service.resolve(this->implementation, e, ec);
 218   }
 219
 220   /// Asynchronously perform reverse resolution of an endpoint to a list of
 221   /// entries.
 222   /**
 223    * This function is used to asynchronously resolve an endpoint into a list of
 224    * endpoint entries.
 225    *
 226    * @param e An endpoint object that determines what endpoints will be
 227    * returned.
 228    *
 229    * @param handler The handler to be called when the resolve operation
 230    * completes. Copies will be made of the handler as required. The function
 231    * signature of the handler must be:
 232    * @code void handler(
 233    *   const boost::system::error_code& error, // Result of operation.
 234    *   resolver::iterator iterator             // Forward-only iterator that can
 235    *                                           // be used to traverse the list
 236    *                                           // of endpoint entries.
 237    * ); @endcode
 238    * Regardless of whether the asynchronous operation completes immediately or
 239    * not, the handler will not be invoked from within this function. Invocation
 240    * of the handler will be performed in a manner equivalent to using
 241    * boost::asio::io_service::post().
 242    *
 243    * @note A default constructed iterator represents the end of the list.
 244    *
 245    * A successful resolve operation is guaranteed to pass at least one entry to
 246    * the handler.
 247    */
 248   template <typename ResolveHandler>
 249   BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
 250       void (boost::system::error_code, iterator))
 251   async_resolve(const endpoint_type& e,
 252       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
 253   {
 254     // If you get an error on the following line it means that your handler does
 255     // not meet the documented type requirements for a ResolveHandler.
 256     BOOST_ASIO_RESOLVE_HANDLER_CHECK(
 257         ResolveHandler, handler, iterator) type_check;
 258
 259     return this->service.async_resolve(this->implementation, e,
 260         BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
 261   }
 262 };
 263
 264 } // namespace ip
 265 } // namespace asio
 266 } // namespace boost
 267
 268 #include <boost/asio/detail/pop_options.hpp>
 269
 270 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_HPP