libs/asio/doc/requirements/ResolverService.qbk

   1 [/
   2  / Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:ResolverService Resolver service requirements]
   9
  10 A resolver service must meet the requirements for an [link
  11 boost_asio.reference.IoObjectService I/O object service], as well as the
  12 additional requirements listed below.
  13
  14 In the table below, `X` denotes a resolver service class for protocol
  15 `InternetProtocol`, `a` denotes a value of type `X`, `b` denotes a value of
  16 type `X::implementation_type`, `q` denotes a value of type
  17 `ip::basic_resolver_query<InternetProtocol>`, `e` denotes a value of type
  18 `ip::basic_endpoint<InternetProtocol>`, `ec` denotes a value of type
  19 `error_code`, and `h` denotes a value meeting [link
  20 boost_asio.reference.ResolveHandler `ResolveHandler`] requirements.
  21
  22 [table ResolverService requirements
  23   [[expression] [return type] [assertion/note\npre/post-condition]]
  24   [
  25     [`a.destroy(b);`]
  26     []
  27     [
  28       From [link boost_asio.reference.IoObjectService IoObjectService]
  29       requirements. Implicitly cancels asynchronous resolve operations, as if by
  30       calling `a.cancel(b, ec)`.
  31     ]
  32   ]
  33   [
  34     [``
  35       a.cancel(b, ec);
  36     ``]
  37     [`error_code`]
  38     [
  39       Causes any outstanding asynchronous resolve operations to complete as
  40       soon as possible. Handlers for cancelled operations shall be passed the
  41       error code `error::operation_aborted`.
  42     ]
  43   ]
  44   [
  45     [``
  46       a.resolve(b, q, ec);
  47     ``]
  48     [``
  49       ip::basic_resolver_iterator<
  50         InternetProtocol>
  51     ``]
  52     [
  53       On success, returns an iterator `i` such that `i !=
  54       ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns
  55       `ip::basic_resolver_iterator<InternetProtocol>()`.
  56     ]
  57   ]
  58   [
  59     [``
  60       a.async_resolve(b, q, h);
  61     ``]
  62     []
  63     [
  64       Initiates an asynchronous resolve operation that is performed via the
  65       `io_service` object `a.get_io_service()` and behaves according to [link
  66       boost_asio.reference.asynchronous_operations asynchronous operation]
  67       requirements.\n
  68       \n
  69       If the operation completes successfully, the `ResolveHandler` object `h`
  70       shall be invoked with an iterator object `i` such that the condition `i
  71       != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it
  72       is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.
  73     ]
  74   ]
  75   [
  76     [``
  77       a.resolve(b, e, ec);
  78     ``]
  79     [``
  80       ip::basic_resolver_iterator<
  81         InternetProtocol>
  82     ``]
  83     [
  84       On success, returns an iterator `i` such that `i !=
  85       ip::basic_resolver_iterator<InternetProtocol>()`. Otherwise returns
  86       `ip::basic_resolver_iterator<InternetProtocol>()`.
  87     ]
  88   ]
  89   [
  90     [``
  91       a.async_resolve(b, e, h);
  92     ``]
  93     []
  94     [
  95       Initiates an asynchronous resolve operation that is performed via the
  96       `io_service` object `a.get_io_service()` and behaves according to [link
  97       boost_asio.reference.asynchronous_operations asynchronous operation]
  98       requirements.\n
  99       \n
 100       If the operation completes successfully, the `ResolveHandler` object `h`
 101       shall be invoked with an iterator object `i` such that the condition `i
 102       != ip::basic_resolver_iterator<InternetProtocol>()` holds. Otherwise it
 103       is invoked with `ip::basic_resolver_iterator<InternetProtocol>()`.
 104     ]
 105   ]
 106 ]
 107
 108 [endsect]