/src/contrib/boost/asio/ip/basic_resolver.hpp

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