boost_1_45_0/libs/asio/doc/requirements/ResolverService.qbk

[/
 / Copyright (c) 2003-2010 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:ResolverService Resolver service requirements]

A resolver service must meet the requirements for an [link
boost_asio.reference.IoObjectService I/O object service], as well as the
additional requirements listed below.

In the table below, `X` denotes a resolver service class for protocol
`InternetProtocol`, `a` denotes a value of type `X`, `b` denotes a value of
type `X::implementation_type`, `q` denotes a value of type
`ip::basic_resolver_query<InternetProtocol>`, `e` denotes a value of type
`ip::basic_endpoint<InternetProtocol>`, `ec` denotes a value of type
`error_code`, and `h` denotes a value meeting [link
boost_asio.reference.ResolveHandler `ResolveHandler`] requirements.

[table ResolverService requirements
  [[expression] [return type] [assertion/note\npre/post-condition]]
  [
    [`a.destroy(b);`]
    []
    [
      From [link boost_asio.reference.IoObjectService IoObjectService]
      requirements. Implicitly cancels asynchronous resolve operations, as if by
      calling `a.cancel(b, ec)`.
    ]
  ]
  [
    [``
      a.cancel(b, ec);
    ``]
    [`error_code`]
    [
      Causes any outstanding asynchronous resolve operations to complete as
      soon as possible. Handlers for cancelled operations shall be passed the
      error code `error::operation_aborted`.
    ]
  ]
  [
    [``
      a.resolve(b, q, ec);
    ``]
    [``
      ip::basic_resolver_iterator<
        InternetProtocol>
    ``]
    [
      On success, returns an iterator `i` such that `i !=
      ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns
      `ip::basic_resolver_iterator<InternetProtocol>()`.
    ]
  ]
  [
    [``
      a.async_resolve(b, q, h);
    ``]
    []
    [
      Initiates an asynchronous resolve operation that is performed via the
      `io_service` object `a.io_service()` and behaves according to [link
      boost_asio.reference.asynchronous_operations asynchronous operation]
      requirements.\n
      \n
      If the operation completes successfully, the `ResolveHandler` object `h`
      shall be invoked with an iterator object `i` such that the condition `i
      != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it
      is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.
    ]
  ]
  [
    [``
      a.resolve(b, e, ec);
    ``]
    [``
      ip::basic_resolver_iterator<
        InternetProtocol>
    ``]
    [
      On success, returns an iterator `i` such that `i !=
      ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns
      `ip::basic_resolver_iterator<InternetProtocol>()`.
    ]
  ]
  [
    [``
      a.async_resolve(b, e, h);
    ``]
    []
    [
      Initiates an asynchronous resolve operation that is performed via the
      `io_service` object `a.io_service()` and behaves according to [link
      boost_asio.reference.asynchronous_operations asynchronous operation]
      requirements.\n
      \n
      If the operation completes successfully, the `ResolveHandler` object `h`
      shall be invoked with an iterator object `i` such that the condition `i
      != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it
      is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.
    ]
  ]
]

[endsect]