doc/html/boost_asio/reference/StreamSocketService.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Stream socket service requirements</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../reference.html" title="Reference">
   9 <link rel="prev" href="StreamHandleService.html" title="Stream handle service requirements">
  10 <link rel="next" href="SyncRandomAccessReadDevice.html" title="Buffer-oriented synchronous random-access read device requirements">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="StreamHandleService.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="SyncRandomAccessReadDevice.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_asio.reference.StreamSocketService"></a><a class="link" href="StreamSocketService.html" title="Stream socket service requirements">Stream socket
  28       service requirements</a>
  29 </h3></div></div></div>
  30 <p>
  31         A stream socket service must meet the requirements for a <a class="link" href="SocketService.html" title="Socket service requirements">socket
  32         service</a>, as well as the additional requirements listed below.
  33       </p>
  34 <p>
  35         In the table below, <code class="computeroutput"><span class="identifier">X</span></code> denotes
  36         a stream socket service class, <code class="computeroutput"><span class="identifier">a</span></code>
  37         denotes a value of type <code class="computeroutput"><span class="identifier">X</span></code>,
  38         <code class="computeroutput"><span class="identifier">b</span></code> denotes a value of type
  39         <code class="computeroutput"><span class="identifier">X</span><span class="special">::</span><span class="identifier">implementation_type</span></code>, <code class="computeroutput"><span class="identifier">ec</span></code>
  40         denotes a value of type <code class="computeroutput"><span class="identifier">error_code</span></code>,
  41         <code class="computeroutput"><span class="identifier">f</span></code> denotes a value of type
  42         <code class="computeroutput"><span class="identifier">socket_base</span><span class="special">::</span><span class="identifier">message_flags</span></code>, <code class="computeroutput"><span class="identifier">mb</span></code>
  43         denotes a value satisfying <a class="link" href="MutableBufferSequence.html" title="Mutable buffer sequence requirements">mutable
  44         buffer sequence</a> requirements, <code class="computeroutput"><span class="identifier">rh</span></code>
  45         denotes a value meeting <a class="link" href="ReadHandler.html" title="Read handler requirements"><code class="computeroutput"><span class="identifier">ReadHandler</span></code></a> requirements, <code class="computeroutput"><span class="identifier">cb</span></code> denotes a value satisfying <a class="link" href="ConstBufferSequence.html" title="Constant buffer sequence requirements">constant
  46         buffer sequence</a> requirements, and <code class="computeroutput"><span class="identifier">wh</span></code>
  47         denotes a value meeting <a class="link" href="WriteHandler.html" title="Write handler requirements"><code class="computeroutput"><span class="identifier">WriteHandler</span></code></a> requirements.
  48       </p>
  49 <div class="table">
  50 <a name="boost_asio.reference.StreamSocketService.t0"></a><p class="title"><b>Table&#160;33.&#160;StreamSocketService requirements</b></p>
  51 <div class="table-contents"><table class="table" summary="StreamSocketService requirements">
  52 <colgroup>
  53 <col>
  54 <col>
  55 <col>
  56 </colgroup>
  57 <thead><tr>
  58 <th>
  59                 <p>
  60                   expression
  61                 </p>
  62               </th>
  63 <th>
  64                 <p>
  65                   return type
  66                 </p>
  67               </th>
  68 <th>
  69                 <p>
  70                   assertion/note<br> pre/post-condition
  71                 </p>
  72               </th>
  73 </tr></thead>
  74 <tbody>
  75 <tr>
  76 <td>
  77                 <p>
  78                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">receive</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
  79                   <span class="identifier">mb</span><span class="special">,</span>
  80                   <span class="identifier">f</span><span class="special">,</span>
  81                   <span class="identifier">ec</span><span class="special">);</span></code>
  82                 </p>
  83               </td>
  84 <td>
  85                 <p>
  86                   <code class="computeroutput"><span class="identifier">size_t</span></code>
  87                 </p>
  88               </td>
  89 <td>
  90                 <p>
  91                   pre: <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code>.<br>
  92                   <br> Reads one or more bytes of data from a connected socket
  93                   <code class="computeroutput"><span class="identifier">b</span></code>.<br> <br>
  94                   The mutable buffer sequence <code class="computeroutput"><span class="identifier">mb</span></code>
  95                   specifies memory where the data should be placed. The operation
  96                   shall always fill a buffer in the sequence completely before proceeding
  97                   to the next.<br> <br> If successful, returns the number of
  98                   bytes read. Otherwise returns <code class="computeroutput"><span class="number">0</span></code>.
  99                   If the total size of all buffers in the sequence <code class="computeroutput"><span class="identifier">mb</span></code> is <code class="computeroutput"><span class="number">0</span></code>,
 100                   the function shall return <code class="computeroutput"><span class="number">0</span></code>
 101                   immediately.<br> <br> If the operation completes due to graceful
 102                   connection closure by the peer, the operation shall fail with
 103                   <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">eof</span></code>.
 104                 </p>
 105               </td>
 106 </tr>
 107 <tr>
 108 <td>
 109                 <p>
 110                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">async_receive</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 111                   <span class="identifier">mb</span><span class="special">,</span>
 112                   <span class="identifier">f</span><span class="special">,</span>
 113                   <span class="identifier">rh</span><span class="special">);</span></code>
 114                 </p>
 115               </td>
 116 <td>
 117                 <p>
 118                   <code class="computeroutput"><span class="keyword">void</span></code>
 119                 </p>
 120               </td>
 121 <td>
 122                 <p>
 123                   pre: <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code>.<br>
 124                   <br> Initiates an asynchronous operation to read one or more
 125                   bytes of data from a connected socket <code class="computeroutput"><span class="identifier">b</span></code>.
 126                   The operation is performed via the <code class="computeroutput"><span class="identifier">io_service</span></code>
 127                   object <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">get_io_service</span><span class="special">()</span></code>
 128                   and behaves according to <a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">asynchronous
 129                   operation</a> requirements.<br> <br> The mutable buffer
 130                   sequence <code class="computeroutput"><span class="identifier">mb</span></code> specifies
 131                   memory where the data should be placed. The operation shall always
 132                   fill a buffer in the sequence completely before proceeding to the
 133                   next.<br> <br> The implementation shall maintain one or more
 134                   copies of <code class="computeroutput"><span class="identifier">mb</span></code> until
 135                   such time as the read operation no longer requires access to the
 136                   memory specified by the buffers in the sequence. The program must
 137                   ensure the memory is valid until:<br> <br> &#8212; the last copy of
 138                   <code class="computeroutput"><span class="identifier">mb</span></code> is destroyed,
 139                   or<br> <br> &#8212; the handler for the asynchronous operation is invoked,<br>
 140                   <br> whichever comes first. If the total size of all buffers
 141                   in the sequence <code class="computeroutput"><span class="identifier">mb</span></code>
 142                   is <code class="computeroutput"><span class="number">0</span></code>, the asynchronous
 143                   read operation shall complete immediately and pass <code class="computeroutput"><span class="number">0</span></code> as the argument to the handler
 144                   that specifies the number of bytes read.<br> <br> If the operation
 145                   completes due to graceful connection closure by the peer, the operation
 146                   shall fail with <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">eof</span></code>.<br>
 147                   <br> If the operation completes successfully, the <code class="computeroutput"><span class="identifier">ReadHandler</span></code> object <code class="computeroutput"><span class="identifier">rh</span></code> is invoked with the number
 148                   of bytes transferred. Otherwise it is invoked with <code class="computeroutput"><span class="number">0</span></code>.
 149                 </p>
 150               </td>
 151 </tr>
 152 <tr>
 153 <td>
 154                 <p>
 155                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 156                   <span class="identifier">cb</span><span class="special">,</span>
 157                   <span class="identifier">f</span><span class="special">,</span>
 158                   <span class="identifier">ec</span><span class="special">);</span></code>
 159                 </p>
 160               </td>
 161 <td>
 162                 <p>
 163                   <code class="computeroutput"><span class="identifier">size_t</span></code>
 164                 </p>
 165               </td>
 166 <td>
 167                 <p>
 168                   pre: <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code>.<br>
 169                   <br> Writes one or more bytes of data to a connected socket
 170                   <code class="computeroutput"><span class="identifier">b</span></code>.<br> <br>
 171                   The constant buffer sequence <code class="computeroutput"><span class="identifier">cb</span></code>
 172                   specifies memory where the data to be written is located. The operation
 173                   shall always write a buffer in the sequence completely before proceeding
 174                   to the next.<br> <br> If successful, returns the number of
 175                   bytes written. Otherwise returns <code class="computeroutput"><span class="number">0</span></code>.
 176                   If the total size of all buffers in the sequence <code class="computeroutput"><span class="identifier">cb</span></code> is <code class="computeroutput"><span class="number">0</span></code>,
 177                   the function shall return <code class="computeroutput"><span class="number">0</span></code>
 178                   immediately.
 179                 </p>
 180               </td>
 181 </tr>
 182 <tr>
 183 <td>
 184                 <p>
 185                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">async_send</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 186                   <span class="identifier">cb</span><span class="special">,</span>
 187                   <span class="identifier">f</span><span class="special">,</span>
 188                   <span class="identifier">wh</span><span class="special">);</span></code>
 189                 </p>
 190               </td>
 191 <td>
 192                 <p>
 193                   <code class="computeroutput"><span class="keyword">void</span></code>
 194                 </p>
 195               </td>
 196 <td>
 197                 <p>
 198                   pre: <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code>.<br>
 199                   <br> Initiates an asynchronous operation to write one or more
 200                   bytes of data to a connected socket <code class="computeroutput"><span class="identifier">b</span></code>.
 201                   The operation is performed via the <code class="computeroutput"><span class="identifier">io_service</span></code>
 202                   object <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">get_io_service</span><span class="special">()</span></code>
 203                   and behaves according to <a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">asynchronous
 204                   operation</a> requirements.<br> <br> The constant buffer
 205                   sequence <code class="computeroutput"><span class="identifier">cb</span></code> specifies
 206                   memory where the data to be written is located. The operation shall
 207                   always write a buffer in the sequence completely before proceeding
 208                   to the next.<br> <br> The implementation shall maintain one
 209                   or more copies of <code class="computeroutput"><span class="identifier">cb</span></code>
 210                   until such time as the write operation no longer requires access
 211                   to the memory specified by the buffers in the sequence. The program
 212                   must ensure the memory is valid until:<br> <br> &#8212; the last copy
 213                   of <code class="computeroutput"><span class="identifier">cb</span></code> is destroyed,
 214                   or<br> <br> &#8212; the handler for the asynchronous operation is invoked,<br>
 215                   <br> whichever comes first. If the total size of all buffers
 216                   in the sequence <code class="computeroutput"><span class="identifier">cb</span></code>
 217                   is <code class="computeroutput"><span class="number">0</span></code>, the asynchronous
 218                   operation shall complete immediately and pass <code class="computeroutput"><span class="number">0</span></code>
 219                   as the argument to the handler that specifies the number of bytes
 220                   read.<br> <br> If the operation completes successfully, the
 221                   <code class="computeroutput"><span class="identifier">WriteHandler</span></code> object
 222                   <code class="computeroutput"><span class="identifier">wh</span></code> is invoked with
 223                   the number of bytes transferred. Otherwise it is invoked with
 224                   <code class="computeroutput"><span class="number">0</span></code>.
 225                 </p>
 226               </td>
 227 </tr>
 228 </tbody>
 229 </table></div>
 230 </div>
 231 <br class="table-break">
 232 </div>
 233 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 234 <td align="left"></td>
 235 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2014 Christopher M. Kohlhoff<p>
 236         Distributed under the Boost Software License, Version 1.0. (See accompanying
 237         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 238       </p>
 239 </div></td>
 240 </tr></table>
 241 <hr>
 242 <div class="spirit-nav">
 243 <a accesskey="p" href="StreamHandleService.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="SyncRandomAccessReadDevice.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 244 </div>
 245 </body>
 246 </html>