| Home | Libraries | People | FAQ | More

### Serial port service requirements

A serial port service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, `X` denotes a serial port service class, `a` and `ao` denote values of type `X`, `d` denotes a serial port device name of type `std::string`, `b` and `c` denote values of type `X::implementation_type`, `n` denotes a value of type `X::native_handle_type`, `ec` denotes a value of type `error_code`, `s` denotes a value meeting `SettableSerialPortOption` requirements, `g` denotes a value meeting `GettableSerialPortOption` requirements, `mb` denotes a value satisfying mutable buffer sequence requirements, `rh` denotes a value meeting `ReadHandler` requirements, `cb` denotes a value satisfying constant buffer sequence requirements, and `wh` denotes a value meeting `WriteHandler` requirements. and `u` and `v` denote identifiers.

Table 25. SerialPortService requirements

expression | return type | assertion/note pre/post-condition
--- | --- | ---
`X::native_handle_type` |  | The implementation-defined native representation of a serial port. Must satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
`a.construct(b);` |  | From IoObjectService requirements. post: `!a.is_open(b)`.
`a.destroy(b);` |  | From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling `a.close(b, ec)`.
    a.move_construct(b, c);
|  | From IoObjectService requirements. The underlying native representation is moved from `c` to `b`.
    a.move_assign(b, ao, c);
|  | From IoObjectService requirements. Implicitly cancels asynchronous operations associated with `b`, as if by calling `a.close(b, ec)`. Then the underlying native representation is moved from `c` to `b`.
    const std::string& u = d;
    a.open(b, u, ec);
| `error_code` | pre: `!a.is_open(b)`. post: `!!ec || a.is_open(b)`.
    a.assign(b, n, ec);
| `error_code` | pre: `!a.is_open(b)`. post: `!!ec || a.is_open(b)`.
    a.is_open(b);
| `bool` |
    const X& u = a;
    const X::implementation_type& v = b;
    u.is_open(v);
| `bool` |
    a.close(b, ec);
| `error_code` | If `a.is_open()` is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`. post: `!a.is_open(b)`.
    a.native_handle(b);
| `X::native_handle_type` |
    a.cancel(b, ec);
| `error_code` | pre: `a.is_open(b)`. Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code `error::operation_aborted`.
    a.set_option(b, s, ec);
| `error_code` | pre: `a.is_open(b)`.
    a.get_option(b, g, ec);
| `error_code` | pre: `a.is_open(b)`.
    const X& u = a;
    const X::implementation_type& v = b;
    u.get_option(v, g, ec);
| `error_code` | pre: `a.is_open(b)`.
    a.send_break(b, ec);
| `error_code` | pre: `a.is_open(b)`.
`a.read_some(b, mb, ec);` | `size_t` | pre: `a.is_open(b)`. Reads one or more bytes of data from a serial port `b`. The mutable buffer sequence `mb` specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next. If successful, returns the number of bytes read. Otherwise returns `0`. If the total size of all buffers in the sequence `mb` is `0`, the function shall return `0` immediately. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`.
`a.async_read_some(b, mb, rh);` | `void` | pre: `a.is_open(b)`. Initiates an asynchronous operation to read one or more bytes of data from a serial port `b`. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The mutable buffer sequence `mb` specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next. The implementation shall maintain one or more copies of `mb` until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until: — the last copy of `mb` is destroyed, or — the handler for the asynchronous operation is invoked, whichever comes first. If the total size of all buffers in the sequence `mb` is `0`, the asynchronous read operation shall complete immediately and pass `0` as the argument to the handler that specifies the number of bytes read. If the operation completes due to graceful connection closure by the peer, the operation shall fail with `error::eof`. If the operation completes successfully, the `ReadHandler` object `rh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.
`a.write_some(b, cb, ec);` | `size_t` | pre: `a.is_open(b)`. Writes one or more bytes of data to a serial port `b`. The constant buffer sequence `cb` specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next. If successful, returns the number of bytes written. Otherwise returns `0`. If the total size of all buffers in the sequence `cb` is `0`, the function shall return `0` immediately.
`a.async_write_some(b, cb, wh);` | `void` | pre: `a.is_open(b)`. Initiates an asynchronous operation to write one or more bytes of data to a serial port `b`. The operation is performed via the `io_service` object `a.get_io_service()` and behaves according to asynchronous operation requirements. The constant buffer sequence `cb` specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next. The implementation shall maintain one or more copies of `cb` until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until: — the last copy of `cb` is destroyed, or — the handler for the asynchronous operation is invoked, whichever comes first. If the total size of all buffers in the sequence `cb` is `0`, the asynchronous operation shall complete immediately and pass `0` as the argument to the handler that specifies the number of bytes read. If the operation completes successfully, the `WriteHandler` object `wh` is invoked with the number of bytes transferred. Otherwise it is invoked with `0`.