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

http://pythonocc.googlecode.com/ · C++ Header · 250 lines · 71 code · 20 blank · 159 comment · 1 complexity · 9ead90fe483d2da5d324911ed98ed71d MD5 · raw file

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