Chris@16: // Chris@16: // ip/basic_resolver.hpp Chris@16: // ~~~~~~~~~~~~~~~~~~~~~ Chris@16: // Chris@101: // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) Chris@16: // Chris@16: // Distributed under the Boost Software License, Version 1.0. (See accompanying Chris@16: // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Chris@16: // Chris@16: Chris@16: #ifndef BOOST_ASIO_IP_BASIC_RESOLVER_HPP Chris@16: #define BOOST_ASIO_IP_BASIC_RESOLVER_HPP Chris@16: Chris@16: #if defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: # pragma once Chris@16: #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { Chris@16: namespace asio { Chris@16: namespace ip { Chris@16: Chris@16: /// Provides endpoint resolution functionality. Chris@16: /** Chris@16: * The basic_resolver class template provides the ability to resolve a query Chris@16: * to a list of endpoints. Chris@16: * Chris@16: * @par Thread Safety Chris@16: * @e Distinct @e objects: Safe.@n Chris@16: * @e Shared @e objects: Unsafe. Chris@16: */ Chris@16: template > Chris@16: class basic_resolver Chris@16: : public basic_io_object Chris@16: { Chris@16: public: Chris@16: /// The protocol type. Chris@16: typedef InternetProtocol protocol_type; Chris@16: Chris@16: /// The endpoint type. Chris@16: typedef typename InternetProtocol::endpoint endpoint_type; Chris@16: Chris@16: /// The query type. Chris@16: typedef basic_resolver_query query; Chris@16: Chris@16: /// The iterator type. Chris@16: typedef basic_resolver_iterator iterator; Chris@16: Chris@16: /// Constructor. Chris@16: /** Chris@16: * This constructor creates a basic_resolver. Chris@16: * Chris@16: * @param io_service The io_service object that the resolver will use to Chris@16: * dispatch handlers for any asynchronous operations performed on the timer. Chris@16: */ Chris@16: explicit basic_resolver(boost::asio::io_service& io_service) Chris@16: : basic_io_object(io_service) Chris@16: { Chris@16: } Chris@16: Chris@16: /// Cancel any asynchronous operations that are waiting on the resolver. Chris@16: /** Chris@16: * This function forces the completion of any pending asynchronous Chris@16: * operations on the host resolver. The handler for each cancelled operation Chris@16: * will be invoked with the boost::asio::error::operation_aborted error code. Chris@16: */ Chris@16: void cancel() Chris@16: { Chris@16: return this->service.cancel(this->implementation); Chris@16: } Chris@16: Chris@16: /// Perform forward resolution of a query to a list of entries. Chris@16: /** Chris@16: * This function is used to resolve a query into a list of endpoint entries. Chris@16: * Chris@16: * @param q A query object that determines what endpoints will be returned. Chris@16: * Chris@16: * @returns A forward-only iterator that can be used to traverse the list Chris@16: * of endpoint entries. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful call to this function is guaranteed to return at least one Chris@16: * entry. Chris@16: */ Chris@16: iterator resolve(const query& q) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: iterator i = this->service.resolve(this->implementation, q, ec); Chris@16: boost::asio::detail::throw_error(ec, "resolve"); Chris@16: return i; Chris@16: } Chris@16: Chris@16: /// Perform forward resolution of a query to a list of entries. Chris@16: /** Chris@16: * This function is used to resolve a query into a list of endpoint entries. Chris@16: * Chris@16: * @param q A query object that determines what endpoints will be returned. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns A forward-only iterator that can be used to traverse the list Chris@16: * of endpoint entries. Returns a default constructed iterator if an error Chris@16: * occurs. Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful call to this function is guaranteed to return at least one Chris@16: * entry. Chris@16: */ Chris@16: iterator resolve(const query& q, boost::system::error_code& ec) Chris@16: { Chris@16: return this->service.resolve(this->implementation, q, ec); Chris@16: } Chris@16: Chris@16: /// Asynchronously perform forward resolution of a query to a list of entries. Chris@16: /** Chris@16: * This function is used to asynchronously resolve a query into a list of Chris@16: * endpoint entries. Chris@16: * Chris@16: * @param q A query object that determines what endpoints will be returned. Chris@16: * Chris@16: * @param handler The handler to be called when the resolve operation Chris@16: * completes. Copies will be made of the handler as required. The function Chris@16: * signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error, // Result of operation. Chris@16: * resolver::iterator iterator // Forward-only iterator that can Chris@16: * // be used to traverse the list Chris@16: * // of endpoint entries. Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation Chris@16: * of the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful resolve operation is guaranteed to pass at least one entry to Chris@16: * the handler. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler, Chris@16: void (boost::system::error_code, iterator)) Chris@16: async_resolve(const query& q, Chris@16: BOOST_ASIO_MOVE_ARG(ResolveHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a ResolveHandler. Chris@16: BOOST_ASIO_RESOLVE_HANDLER_CHECK( Chris@16: ResolveHandler, handler, iterator) type_check; Chris@16: Chris@16: return this->service.async_resolve(this->implementation, q, Chris@16: BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler)); Chris@16: } Chris@16: Chris@16: /// Perform reverse resolution of an endpoint to a list of entries. Chris@16: /** Chris@16: * This function is used to resolve an endpoint into a list of endpoint Chris@16: * entries. Chris@16: * Chris@16: * @param e An endpoint object that determines what endpoints will be Chris@16: * returned. Chris@16: * Chris@16: * @returns A forward-only iterator that can be used to traverse the list Chris@16: * of endpoint entries. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful call to this function is guaranteed to return at least one Chris@16: * entry. Chris@16: */ Chris@16: iterator resolve(const endpoint_type& e) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: iterator i = this->service.resolve(this->implementation, e, ec); Chris@16: boost::asio::detail::throw_error(ec, "resolve"); Chris@16: return i; Chris@16: } Chris@16: Chris@16: /// Perform reverse resolution of an endpoint to a list of entries. Chris@16: /** Chris@16: * This function is used to resolve an endpoint into a list of endpoint Chris@16: * entries. Chris@16: * Chris@16: * @param e An endpoint object that determines what endpoints will be Chris@16: * returned. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns A forward-only iterator that can be used to traverse the list Chris@16: * of endpoint entries. Returns a default constructed iterator if an error Chris@16: * occurs. Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful call to this function is guaranteed to return at least one Chris@16: * entry. Chris@16: */ Chris@16: iterator resolve(const endpoint_type& e, boost::system::error_code& ec) Chris@16: { Chris@16: return this->service.resolve(this->implementation, e, ec); Chris@16: } Chris@16: Chris@16: /// Asynchronously perform reverse resolution of an endpoint to a list of Chris@16: /// entries. Chris@16: /** Chris@16: * This function is used to asynchronously resolve an endpoint into a list of Chris@16: * endpoint entries. Chris@16: * Chris@16: * @param e An endpoint object that determines what endpoints will be Chris@16: * returned. Chris@16: * Chris@16: * @param handler The handler to be called when the resolve operation Chris@16: * completes. Copies will be made of the handler as required. The function Chris@16: * signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error, // Result of operation. Chris@16: * resolver::iterator iterator // Forward-only iterator that can Chris@16: * // be used to traverse the list Chris@16: * // of endpoint entries. Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation Chris@16: * of the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @note A default constructed iterator represents the end of the list. Chris@16: * Chris@16: * A successful resolve operation is guaranteed to pass at least one entry to Chris@16: * the handler. Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler, Chris@16: void (boost::system::error_code, iterator)) Chris@16: async_resolve(const endpoint_type& e, Chris@16: BOOST_ASIO_MOVE_ARG(ResolveHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a ResolveHandler. Chris@16: BOOST_ASIO_RESOLVE_HANDLER_CHECK( Chris@16: ResolveHandler, handler, iterator) type_check; Chris@16: Chris@16: return this->service.async_resolve(this->implementation, e, Chris@16: BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler)); Chris@16: } Chris@16: }; Chris@16: Chris@16: } // namespace ip Chris@16: } // namespace asio Chris@16: } // namespace boost Chris@16: Chris@16: #include Chris@16: Chris@16: #endif // BOOST_ASIO_IP_BASIC_RESOLVER_HPP