]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2003-2016 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:StreamSocketService Stream socket service requirements] | |
9 | ||
10 | A stream socket service must meet the requirements for a [link | |
11 | boost_asio.reference.SocketService socket service], as well as the additional | |
12 | requirements listed below. | |
13 | ||
14 | In the table below, `X` denotes a stream socket service class, `a` denotes a | |
15 | value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec` | |
16 | denotes a value of type `error_code`, `f` denotes a value of type | |
17 | `socket_base::message_flags`, `mb` denotes a value satisfying [link | |
18 | boost_asio.reference.MutableBufferSequence mutable buffer sequence] | |
19 | requirements, `rh` denotes a value meeting [link | |
20 | boost_asio.reference.ReadHandler `ReadHandler`] requirements, `cb` denotes a | |
21 | value satisfying [link boost_asio.reference.ConstBufferSequence constant | |
22 | buffer sequence] requirements, and `wh` denotes a value meeting [link | |
23 | boost_asio.reference.WriteHandler `WriteHandler`] requirements. | |
24 | ||
25 | [table StreamSocketService requirements | |
26 | [[expression] [return type] [assertion/note\npre/post-condition]] | |
27 | [ | |
28 | [`a.receive(b, mb, f, ec);`] | |
29 | [`size_t`] | |
30 | [ | |
31 | pre: `a.is_open(b)`.\n | |
32 | \n | |
33 | Reads one or more bytes of data from a connected socket `b`.\n | |
34 | \n | |
35 | The mutable buffer sequence `mb` specifies memory where the data should | |
36 | be placed. The operation shall always fill a buffer in the sequence | |
37 | completely before proceeding to the next.\n | |
38 | \n | |
39 | If successful, returns the number of bytes read. Otherwise returns `0`. | |
40 | If the total size of all buffers in the sequence `mb` is `0`, the | |
41 | function shall return `0` immediately.\n | |
42 | \n | |
43 | If the operation completes due to graceful connection closure by the | |
44 | peer, the operation shall fail with `error::eof`. | |
45 | ] | |
46 | ] | |
47 | [ | |
48 | [`a.async_receive(b, mb, f, rh);`] | |
49 | [`void`] | |
50 | [ | |
51 | pre: `a.is_open(b)`.\n | |
52 | \n | |
53 | Initiates an asynchronous operation to read one or more bytes of data | |
54 | from a connected socket `b`. The operation is performed via the | |
55 | `io_service` object `a.get_io_service()` and behaves according to [link | |
56 | boost_asio.reference.asynchronous_operations asynchronous operation] | |
57 | requirements.\n | |
58 | \n | |
59 | The mutable buffer sequence `mb` specifies memory where the data should | |
60 | be placed. The operation shall always fill a buffer in the sequence | |
61 | completely before proceeding to the next.\n | |
62 | \n | |
63 | The implementation shall maintain one or more copies of `mb` until such | |
64 | time as the read operation no longer requires access to the memory | |
65 | specified by the buffers in the sequence. The program must ensure the | |
66 | memory is valid until:\n | |
67 | \n | |
68 | [mdash] the last copy of `mb` is destroyed, or\n | |
69 | \n | |
70 | [mdash] the handler for the asynchronous operation is invoked,\n | |
71 | \n | |
72 | whichever comes first. If the total size of all buffers in the sequence | |
73 | `mb` is `0`, the asynchronous read operation shall complete immediately | |
74 | and pass `0` as the argument to the handler that specifies the number of | |
75 | bytes read.\n | |
76 | \n | |
77 | If the operation completes due to graceful connection closure by the | |
78 | peer, the operation shall fail with `error::eof`.\n | |
79 | \n | |
80 | If the operation completes successfully, the `ReadHandler` object | |
81 | `rh` is invoked with the number of bytes transferred. Otherwise it is | |
82 | invoked with `0`. | |
83 | ] | |
84 | ] | |
85 | [ | |
86 | [`a.send(b, cb, f, ec);`] | |
87 | [`size_t`] | |
88 | [ | |
89 | pre: `a.is_open(b)`.\n | |
90 | \n | |
91 | Writes one or more bytes of data to a connected socket `b`.\n | |
92 | \n | |
93 | The constant buffer sequence `cb` specifies memory where the data to be | |
94 | written is located. The operation shall always write a buffer in the | |
95 | sequence completely before proceeding to the next.\n | |
96 | \n | |
97 | If successful, returns the number of bytes written. Otherwise returns `0`. | |
98 | If the total size of all buffers in the sequence `cb` is `0`, the | |
99 | function shall return `0` immediately. | |
100 | ] | |
101 | ] | |
102 | [ | |
103 | [`a.async_send(b, cb, f, wh);`] | |
104 | [`void`] | |
105 | [ | |
106 | pre: `a.is_open(b)`.\n | |
107 | \n | |
108 | Initiates an asynchronous operation to write one or more bytes of data to | |
109 | a connected socket `b`. The operation is performed via the `io_service` | |
110 | object `a.get_io_service()` and behaves according to [link | |
111 | boost_asio.reference.asynchronous_operations asynchronous operation] | |
112 | requirements.\n | |
113 | \n | |
114 | The constant buffer sequence `cb` specifies memory where the data to be | |
115 | written is located. The operation shall always write a buffer in the | |
116 | sequence completely before proceeding to the next.\n | |
117 | \n | |
118 | The implementation shall maintain one or more copies of `cb` until such | |
119 | time as the write operation no longer requires access to the memory | |
120 | specified by the buffers in the sequence. The program must ensure the | |
121 | memory is valid until:\n | |
122 | \n | |
123 | [mdash] the last copy of `cb` is destroyed, or\n | |
124 | \n | |
125 | [mdash] the handler for the asynchronous operation is invoked,\n | |
126 | \n | |
127 | whichever comes first. If the total size of all buffers in the sequence | |
128 | `cb` is `0`, the asynchronous operation shall complete immediately and | |
129 | pass `0` as the argument to the handler that specifies the number of | |
130 | bytes read.\n | |
131 | \n | |
132 | If the operation completes successfully, the `WriteHandler` object `wh` | |
133 | is invoked with the number of bytes transferred. Otherwise it is invoked | |
134 | with `0`. | |
135 | ] | |
136 | ] | |
137 | ] | |
138 | ||
139 | [endsect] |