libs/asio/doc/requirements/SerialPortService.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:SerialPortService Serial port service requirements]
   9
  10 A serial port 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 serial port service class, `a` and `ao` denote
  15 values of type `X`, `d` denotes a serial port device name of type `std::string`,
  16 `b` and `c` denote values of type `X::implementation_type`, `n` denotes a value
  17 of type `X::native_handle_type`, `ec` denotes a value of type `error_code`, `s`
  18 denotes a value meeting [link boost_asio.reference.SettableSerialPortOption
  19 `SettableSerialPortOption`] requirements, `g` denotes a value meeting [link
  20 boost_asio.reference.GettableSerialPortOption `GettableSerialPortOption`]
  21 requirements, `mb` denotes a value satisfying [link
  22 boost_asio.reference.MutableBufferSequence mutable buffer sequence] requirements,
  23 `rh` denotes a value meeting [link boost_asio.reference.ReadHandler `ReadHandler`]
  24 requirements, `cb` denotes a value satisfying [link
  25 boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
  26 `wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
  27 requirements. and `u` and `v` denote identifiers.
  28
  29 [table SerialPortService requirements
  30   [[expression] [return type] [assertion/note\npre/post-condition]]
  31   [
  32     [`X::native_handle_type`]
  33     []
  34     [
  35       The implementation-defined native representation of a serial port. Must
  36       satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3),
  37       and the requirements of `Assignable` types (C++ Std, 23.1).
  38     ]
  39   ]
  40   [
  41     [`a.construct(b);`]
  42     []
  43     [
  44       From [link boost_asio.reference.IoObjectService IoObjectService]
  45       requirements.\n
  46       post: `!a.is_open(b)`.
  47     ]
  48   ]
  49   [
  50     [`a.destroy(b);`]
  51     []
  52     [
  53       From [link boost_asio.reference.IoObjectService IoObjectService]
  54       requirements. Implicitly cancels asynchronous operations, as if by calling
  55       `a.close(b, ec)`.
  56     ]
  57   ]
  58   [
  59     [``
  60       a.move_construct(b, c);
  61     ``]
  62     []
  63     [
  64       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  65       The underlying native representation is moved from `c` to `b`.
  66     ]
  67   ]
  68   [
  69     [``
  70       a.move_assign(b, ao, c);
  71     ``]
  72     []
  73     [
  74       From [link boost_asio.reference.IoObjectService IoObjectService] requirements.
  75       Implicitly cancels asynchronous operations associated with `b`, as if by
  76       calling `a.close(b, ec)`. Then the underlying native representation is
  77       moved from `c` to `b`.
  78     ]
  79   ]
  80   [
  81     [``
  82       const std::string& u = d;
  83       a.open(b, u, ec);
  84     ``]
  85     [`error_code`]
  86     [
  87       pre: `!a.is_open(b)`.\n
  88       post: `!!ec || a.is_open(b)`.
  89     ]
  90   ]
  91   [
  92     [``
  93       a.assign(b, n, ec);
  94     ``]
  95     [`error_code`]
  96     [
  97       pre: `!a.is_open(b)`.\n
  98       post: `!!ec || a.is_open(b)`.
  99     ]
 100   ]
 101   [
 102     [``
 103       a.is_open(b);
 104     ``]
 105     [`bool`]
 106     [
 107     ]
 108   ]
 109   [
 110     [``
 111       const X& u = a;
 112       const X::implementation_type& v = b;
 113       u.is_open(v);
 114     ``]
 115     [`bool`]
 116     [
 117     ]
 118   ]
 119   [
 120     [``
 121       a.close(b, ec);
 122     ``]
 123     [`error_code`]
 124     [
 125       If `a.is_open()` is true, causes any outstanding asynchronous operations
 126       to complete as soon as possible. Handlers for cancelled operations shall
 127       be passed the error code `error::operation_aborted`.\n
 128       post: `!a.is_open(b)`.
 129     ]
 130   ]
 131   [
 132     [``
 133       a.native_handle(b);
 134     ``]
 135     [`X::native_handle_type`]
 136     [
 137     ]
 138   ]
 139   [
 140     [``
 141       a.cancel(b, ec);
 142     ``]
 143     [`error_code`]
 144     [
 145       pre: `a.is_open(b)`.\n
 146       Causes any outstanding asynchronous operations to complete as soon as
 147       possible. Handlers for cancelled operations shall be passed the error
 148       code `error::operation_aborted`.
 149     ]
 150   ]
 151   [
 152     [``
 153       a.set_option(b, s, ec);
 154     ``]
 155     [`error_code`]
 156     [
 157       pre: `a.is_open(b)`.
 158     ]
 159   ]
 160   [
 161     [``
 162       a.get_option(b, g, ec);
 163     ``]
 164     [`error_code`]
 165     [
 166       pre: `a.is_open(b)`.
 167     ]
 168   ]
 169   [
 170     [``
 171       const X& u = a;
 172       const X::implementation_type& v = b;
 173       u.get_option(v, g, ec);
 174     ``]
 175     [`error_code`]
 176     [
 177       pre: `a.is_open(b)`.
 178     ]
 179   ]
 180   [
 181     [``
 182       a.send_break(b, ec);
 183     ``]
 184     [`error_code`]
 185     [
 186       pre: `a.is_open(b)`.
 187     ]
 188   ]
 189   [
 190     [`a.read_some(b, mb, ec);`]
 191     [`size_t`]
 192     [
 193       pre: `a.is_open(b)`.\n
 194       \n
 195       Reads one or more bytes of data from a serial port `b`.\n
 196       \n
 197       The mutable buffer sequence `mb` specifies memory where the data should
 198       be placed. The operation shall always fill a buffer in the sequence
 199       completely before proceeding to the next.\n
 200       \n
 201       If successful, returns the number of bytes read. Otherwise returns `0`.
 202       If the total size of all buffers in the sequence `mb` is `0`, the
 203       function shall return `0` immediately.\n
 204       \n
 205       If the operation completes due to graceful connection closure by the
 206       peer, the operation shall fail with `error::eof`.
 207     ]
 208   ]
 209   [
 210     [`a.async_read_some(b, mb, rh);`]
 211     [`void`]
 212     [
 213       pre: `a.is_open(b)`.\n
 214       \n
 215       Initiates an asynchronous operation to read one or more bytes of data
 216       from a serial port `b`. The operation is performed via the
 217       `io_service` object `a.get_io_service()` and behaves according to [link
 218       boost_asio.reference.asynchronous_operations asynchronous operation]
 219       requirements.\n
 220       \n
 221       The mutable buffer sequence `mb` specifies memory where the data should
 222       be placed. The operation shall always fill a buffer in the sequence
 223       completely before proceeding to the next.\n
 224       \n
 225       The implementation shall maintain one or more copies of `mb` until such
 226       time as the read operation no longer requires access to the memory
 227       specified by the buffers in the sequence. The program must ensure the
 228       memory is valid until:\n
 229       \n
 230       [mdash] the last copy of `mb` is destroyed, or\n
 231       \n
 232       [mdash] the handler for the asynchronous operation is invoked,\n
 233       \n
 234       whichever comes first. If the total size of all buffers in the sequence
 235       `mb` is `0`, the asynchronous read operation shall complete immediately
 236       and pass `0` as the argument to the handler that specifies the number of
 237       bytes read.\n
 238       \n
 239       If the operation completes due to graceful connection closure by the
 240       peer, the operation shall fail with `error::eof`.\n
 241       \n
 242       If the operation completes successfully, the `ReadHandler` object
 243       `rh` is invoked with the number of bytes transferred. Otherwise it is
 244       invoked with `0`.
 245     ]
 246   ]
 247   [
 248     [`a.write_some(b, cb, ec);`]
 249     [`size_t`]
 250     [
 251       pre: `a.is_open(b)`.\n
 252       \n
 253       Writes one or more bytes of data to a serial port `b`.\n
 254       \n
 255       The constant buffer sequence `cb` specifies memory where the data to be
 256       written is located. The operation shall always write a buffer in the
 257       sequence completely before proceeding to the next.\n
 258       \n
 259       If successful, returns the number of bytes written. Otherwise returns `0`.
 260       If the total size of all buffers in the sequence `cb` is `0`, the
 261       function shall return `0` immediately.
 262     ]
 263   ]
 264   [
 265     [`a.async_write_some(b, cb, wh);`]
 266     [`void`]
 267     [
 268       pre: `a.is_open(b)`.\n
 269       \n
 270       Initiates an asynchronous operation to write one or more bytes of data to
 271       a serial port `b`. The operation is performed via the `io_service`
 272       object `a.get_io_service()` and behaves according to [link
 273       boost_asio.reference.asynchronous_operations asynchronous operation]
 274       requirements.\n
 275       \n
 276       The constant buffer sequence `cb` specifies memory where the data to be
 277       written is located. The operation shall always write a buffer in the
 278       sequence completely before proceeding to the next.\n
 279       \n
 280       The implementation shall maintain one or more copies of `cb` until such
 281       time as the write operation no longer requires access to the memory
 282       specified by the buffers in the sequence. The program must ensure the
 283       memory is valid until:\n
 284       \n
 285       [mdash] the last copy of `cb` is destroyed, or\n
 286       \n
 287       [mdash] the handler for the asynchronous operation is invoked,\n
 288       \n
 289       whichever comes first. If the total size of all buffers in the sequence
 290       `cb` is `0`, the asynchronous operation shall complete immediately and
 291       pass `0` as the argument to the handler that specifies the number of
 292       bytes read.\n
 293       \n
 294       If the operation completes successfully, the `WriteHandler` object `wh`
 295       is invoked with the number of bytes transferred. Otherwise it is invoked
 296       with `0`.
 297     ]
 298   ]
 299 ]
 300
 301 [endsect]