libs/asio/doc/requirements/SocketService.qbk

   1 [/
   2  / Copyright (c) 2003-2014 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:SocketService Socket service requirements]
   9
  10 A socket service must meet the requirements for an [link
  11 boost_asio.reference.IoObjectService I/O object service] with support for movability,
  12 as well as the  additional requirements listed below.
  13
  14 In the table below, `X` denotes a socket service class for protocol [link
  15 boost_asio.reference.Protocol `Protocol`], `a` and `ao` denote values of type `X`,
  16 `b` and `c` denote values of type `X::implementation_type`, `p` denotes a value
  17 of type `Protocol`, `n` denotes a value of type `X::native_handle_type`, `e`
  18 denotes a value of type `Protocol::endpoint`, `ec` denotes a value of type
  19 `error_code`, `s` denotes a value meeting [link
  20 boost_asio.reference.SettableSocketOption `SettableSocketOption`] requirements, `g`
  21 denotes a value meeting [link boost_asio.reference.GettableSocketOption
  22 `GettableSocketOption`] requirements, `i` denotes a value meeting [link
  23 boost_asio.reference.IoControlCommand `IoControlCommand`] requirements, `h`
  24 denotes a value of type `socket_base::shutdown_type`, `ch` denotes a value
  25 meeting [link boost_asio.reference.ConnectHandler `ConnectHandler`]
  26 requirements, and `u` and `v` denote identifiers.
  27
  28 [table SocketService requirements
  29   [[expression] [return type] [assertion/note\npre/post-condition]]
  30   [
  31     [`X::native_handle_type`]
  32     []
  33     [
  34       The implementation-defined native representation of a socket. Must
  35       satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3),
  36       and the requirements of `Assignable` types (C++ Std, 23.1).
  37     ]
  38   ]
  39   [
  40     [`a.construct(b);`]
  41     []
  42     [
  43       From [link boost_asio.reference.IoObjectService IoObjectService]
  44       requirements.\n
  45       post: `!a.is_open(b)`.
  46     ]
  47   ]
  48   [
  49     [`a.destroy(b);`]
  50     []
  51     [
  52       From [link boost_asio.reference.IoObjectService IoObjectService]
  53       requirements. Implicitly cancels asynchronous operations, as if by calling
  54       `a.close(b, ec)`.
  55     ]
  56   ]
  57   [
  58     [``
  59       a.move_construct(b, c);
  60     ``]
  61     []
  62     [
  63       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  64       The underlying native representation is moved from `c` to `b`.
  65     ]
  66   ]
  67   [
  68     [``
  69       a.move_assign(b, ao, c);
  70     ``]
  71     []
  72     [
  73       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  74       Implicitly cancels asynchronous operations associated with `b`, as if by
  75       calling `a.close(b, ec)`. Then the underlying native representation is
  76       moved from `c` to `b`.
  77     ]
  78   ]
  79   [
  80     [``
  81       a.open(b, p, ec);
  82     ``]
  83     [`error_code`]
  84     [
  85       pre: `!a.is_open(b)`.\n
  86       post: `!!ec || a.is_open(b)`.
  87     ]
  88   ]
  89   [
  90     [``
  91       a.assign(b, p, n, ec);
  92     ``]
  93     [`error_code`]
  94     [
  95       pre: `!a.is_open(b)`.\n
  96       post: `!!ec || a.is_open(b)`.
  97     ]
  98   ]
  99   [
 100     [``
 101       a.is_open(b);
 102     ``]
 103     [`bool`]
 104     [
 105     ]
 106   ]
 107   [
 108     [``
 109       const X& u = a;
 110       const X::implementation_type& v = b;
 111       u.is_open(v);
 112     ``]
 113     [`bool`]
 114     [
 115     ]
 116   ]
 117   [
 118     [``
 119       a.close(b, ec);
 120     ``]
 121     [`error_code`]
 122     [
 123       If `a.is_open()` is true, causes any outstanding asynchronous operations
 124       to complete as soon as possible. Handlers for cancelled operations shall
 125       be passed the error code `error::operation_aborted`.\n
 126       post: `!a.is_open(b)`.
 127     ]
 128   ]
 129   [
 130     [``
 131       a.native_handle(b);
 132     ``]
 133     [`X::native_handle_type`]
 134     [
 135     ]
 136   ]
 137   [
 138     [``
 139       a.cancel(b, ec);
 140     ``]
 141     [`error_code`]
 142     [
 143       pre: `a.is_open(b)`.\n
 144       Causes any outstanding asynchronous operations to complete as soon as
 145       possible. Handlers for cancelled operations shall be passed the error
 146       code `error::operation_aborted`.
 147     ]
 148   ]
 149   [
 150     [``
 151       a.set_option(b, s, ec);
 152     ``]
 153     [`error_code`]
 154     [
 155       pre: `a.is_open(b)`.
 156     ]
 157   ]
 158   [
 159     [``
 160       a.get_option(b, g, ec);
 161     ``]
 162     [`error_code`]
 163     [
 164       pre: `a.is_open(b)`.
 165     ]
 166   ]
 167   [
 168     [``
 169       const X& u = a;
 170       const X::implementation_type& v = b;
 171       u.get_option(v, g, ec);
 172     ``]
 173     [`error_code`]
 174     [
 175       pre: `a.is_open(b)`.
 176     ]
 177   ]
 178   [
 179     [``
 180       a.io_control(b, i, ec);
 181     ``]
 182     [`error_code`]
 183     [
 184       pre: `a.is_open(b)`.
 185     ]
 186   ]
 187   [
 188     [``
 189       a.at_mark(b, ec);
 190     ``]
 191     [`bool`]
 192     [
 193       pre: `a.is_open(b)`.
 194     ]
 195   ]
 196   [
 197     [``
 198       const X& u = a;
 199       const X::implementation_type& v = b;
 200       u.at_mark(v, ec);
 201     ``]
 202     [`bool`]
 203     [
 204       pre: `a.is_open(b)`.
 205     ]
 206   ]
 207   [
 208     [``
 209       a.available(b, ec);
 210     ``]
 211     [`size_t`]
 212     [
 213       pre: `a.is_open(b)`.
 214     ]
 215   ]
 216   [
 217     [``
 218       const X& u = a;
 219       const X::implementation_type& v = b;
 220       u.available(v, ec);
 221     ``]
 222     [`size_t`]
 223     [
 224       pre: `a.is_open(b)`.
 225     ]
 226   ]
 227   [
 228     [``
 229       const typename Protocol::endpoint& u = e;
 230       a.bind(b, u, ec);
 231     ``]
 232     [`error_code`]
 233     [
 234       pre: `a.is_open(b)`.
 235     ]
 236   ]
 237   [
 238     [``
 239       a.shutdown(b, h, ec);
 240     ``]
 241     [`error_code`]
 242     [
 243       pre: `a.is_open(b)`.
 244     ]
 245   ]
 246   [
 247     [``
 248       a.local_endpoint(b, ec);
 249     ``]
 250     [`Protocol::endpoint`]
 251     [
 252       pre: `a.is_open(b)`.
 253     ]
 254   ]
 255   [
 256     [``
 257       const X& u = a;
 258       const X::implementation_type& v = b;
 259       u.local_endpoint(v, ec);
 260     ``]
 261     [`Protocol::endpoint`]
 262     [
 263       pre: `a.is_open(b)`.
 264     ]
 265   ]
 266   [
 267     [``
 268       a.remote_endpoint(b, ec);
 269     ``]
 270     [`Protocol::endpoint`]
 271     [
 272       pre: `a.is_open(b)`.
 273     ]
 274   ]
 275   [
 276     [``
 277       const X& u = a;
 278       const X::implementation_type& v = b;
 279       u.remote_endpoint(v, ec);
 280     ``]
 281     [`Protocol::endpoint`]
 282     [
 283       pre: `a.is_open(b)`.
 284     ]
 285   ]
 286   [
 287     [``
 288       const typename Protocol::endpoint& u = e;
 289       a.connect(b, u, ec);
 290     ``]
 291     [`error_code`]
 292     [
 293       pre: `a.is_open(b)`.
 294     ]
 295   ]
 296   [
 297     [``
 298       const typename Protocol::endpoint& u = e;
 299       a.async_connect(b, u, ch);
 300     ``]
 301     []
 302     [
 303       pre: `a.is_open(b)`.\n
 304       Initiates an asynchronous connect operation that is performed via the
 305       `io_service` object `a.get_io_service()` and behaves according to [link
 306       boost_asio.reference.asynchronous_operations asynchronous operation]
 307       requirements.
 308     ]
 309   ]
 310 ]
 311
 312 [endsect]