doc/html/boost_asio/reference/StreamDescriptorService.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Stream descriptor 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="SocketService.html" title="Socket service requirements">
  10 <link rel="next" href="StreamHandleService.html" title="Stream handle service 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="SocketService.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="StreamHandleService.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.StreamDescriptorService"></a><a class="link" href="StreamDescriptorService.html" title="Stream descriptor service requirements">Stream
  28       descriptor service requirements</a>
  29 </h3></div></div></div>
  30 <p>
  31         A stream descriptor service must meet the requirements for a <a class="link" href="DescriptorService.html" title="Descriptor service requirements">descriptor
  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 descriptor 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">mb</span></code> denotes a value satisfying
  42         <a class="link" href="MutableBufferSequence.html" title="Mutable buffer sequence requirements">mutable buffer
  43         sequence</a> requirements, <code class="computeroutput"><span class="identifier">rh</span></code>
  44         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
  45         buffer sequence</a> requirements, and <code class="computeroutput"><span class="identifier">wh</span></code>
  46         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.
  47       </p>
  48 <div class="table">
  49 <a name="boost_asio.reference.StreamDescriptorService.t0"></a><p class="title"><b>Table&#160;31.&#160;StreamDescriptorService requirements</b></p>
  50 <div class="table-contents"><table class="table" summary="StreamDescriptorService requirements">
  51 <colgroup>
  52 <col>
  53 <col>
  54 <col>
  55 </colgroup>
  56 <thead><tr>
  57 <th>
  58                 <p>
  59                   expression
  60                 </p>
  61               </th>
  62 <th>
  63                 <p>
  64                   return type
  65                 </p>
  66               </th>
  67 <th>
  68                 <p>
  69                   assertion/note<br> pre/post-condition
  70                 </p>
  71               </th>
  72 </tr></thead>
  73 <tbody>
  74 <tr>
  75 <td>
  76                 <p>
  77                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">read_some</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
  78                   <span class="identifier">mb</span><span class="special">,</span>
  79                   <span class="identifier">ec</span><span class="special">);</span></code>
  80                 </p>
  81               </td>
  82 <td>
  83                 <p>
  84                   <code class="computeroutput"><span class="identifier">size_t</span></code>
  85                 </p>
  86               </td>
  87 <td>
  88                 <p>
  89                   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>
  90                   <br> Reads one or more bytes of data from a descriptor <code class="computeroutput"><span class="identifier">b</span></code>.<br> <br> The mutable buffer
  91                   sequence <code class="computeroutput"><span class="identifier">mb</span></code> specifies
  92                   memory where the data should be placed. The operation shall always
  93                   fill a buffer in the sequence completely before proceeding to the
  94                   next.<br> <br> If successful, returns the number of bytes read.
  95                   Otherwise returns <code class="computeroutput"><span class="number">0</span></code>.
  96                   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>,
  97                   the function shall return <code class="computeroutput"><span class="number">0</span></code>
  98                   immediately.<br> <br> If the operation completes due to graceful
  99                   connection closure by the peer, the operation shall fail with
 100                   <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">eof</span></code>.
 101                 </p>
 102               </td>
 103 </tr>
 104 <tr>
 105 <td>
 106                 <p>
 107                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 108                   <span class="identifier">mb</span><span class="special">,</span>
 109                   <span class="identifier">rh</span><span class="special">);</span></code>
 110                 </p>
 111               </td>
 112 <td>
 113                 <p>
 114                   <code class="computeroutput"><span class="keyword">void</span></code>
 115                 </p>
 116               </td>
 117 <td>
 118                 <p>
 119                   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>
 120                   <br> Initiates an asynchronous operation to read one or more
 121                   bytes of data from a descriptor <code class="computeroutput"><span class="identifier">b</span></code>.
 122                   The operation is performed via the <code class="computeroutput"><span class="identifier">io_service</span></code>
 123                   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>
 124                   and behaves according to <a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">asynchronous
 125                   operation</a> requirements.<br> <br> The mutable buffer
 126                   sequence <code class="computeroutput"><span class="identifier">mb</span></code> specifies
 127                   memory where the data should be placed. The operation shall always
 128                   fill a buffer in the sequence completely before proceeding to the
 129                   next.<br> <br> The implementation shall maintain one or more
 130                   copies of <code class="computeroutput"><span class="identifier">mb</span></code> until
 131                   such time as the read operation no longer requires access to the
 132                   memory specified by the buffers in the sequence. The program must
 133                   ensure the memory is valid until:<br> <br> &#8212; the last copy of
 134                   <code class="computeroutput"><span class="identifier">mb</span></code> is destroyed,
 135                   or<br> <br> &#8212; the handler for the asynchronous operation is invoked,<br>
 136                   <br> whichever comes first. If the total size of all buffers
 137                   in the sequence <code class="computeroutput"><span class="identifier">mb</span></code>
 138                   is <code class="computeroutput"><span class="number">0</span></code>, the asynchronous
 139                   read operation shall complete immediately and pass <code class="computeroutput"><span class="number">0</span></code> as the argument to the handler
 140                   that specifies the number of bytes read.<br> <br> If the operation
 141                   completes due to graceful connection closure by the peer, the operation
 142                   shall fail with <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">eof</span></code>.<br>
 143                   <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
 144                   of bytes transferred. Otherwise it is invoked with <code class="computeroutput"><span class="number">0</span></code>.
 145                 </p>
 146               </td>
 147 </tr>
 148 <tr>
 149 <td>
 150                 <p>
 151                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">write_some</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 152                   <span class="identifier">cb</span><span class="special">,</span>
 153                   <span class="identifier">ec</span><span class="special">);</span></code>
 154                 </p>
 155               </td>
 156 <td>
 157                 <p>
 158                   <code class="computeroutput"><span class="identifier">size_t</span></code>
 159                 </p>
 160               </td>
 161 <td>
 162                 <p>
 163                   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>
 164                   <br> Writes one or more bytes of data to a descriptor <code class="computeroutput"><span class="identifier">b</span></code>.<br> <br> The constant
 165                   buffer sequence <code class="computeroutput"><span class="identifier">cb</span></code>
 166                   specifies memory where the data to be written is located. The operation
 167                   shall always write a buffer in the sequence completely before proceeding
 168                   to the next.<br> <br> If successful, returns the number of
 169                   bytes written. Otherwise returns <code class="computeroutput"><span class="number">0</span></code>.
 170                   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>,
 171                   the function shall return <code class="computeroutput"><span class="number">0</span></code>
 172                   immediately.
 173                 </p>
 174               </td>
 175 </tr>
 176 <tr>
 177 <td>
 178                 <p>
 179                   <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">async_write_some</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
 180                   <span class="identifier">cb</span><span class="special">,</span>
 181                   <span class="identifier">wh</span><span class="special">);</span></code>
 182                 </p>
 183               </td>
 184 <td>
 185                 <p>
 186                   <code class="computeroutput"><span class="keyword">void</span></code>
 187                 </p>
 188               </td>
 189 <td>
 190                 <p>
 191                   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>
 192                   <br> Initiates an asynchronous operation to write one or more
 193                   bytes of data to a descriptor <code class="computeroutput"><span class="identifier">b</span></code>.
 194                   The operation is performed via the <code class="computeroutput"><span class="identifier">io_service</span></code>
 195                   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>
 196                   and behaves according to <a class="link" href="asynchronous_operations.html" title="Requirements on asynchronous operations">asynchronous
 197                   operation</a> requirements.<br> <br> The constant buffer
 198                   sequence <code class="computeroutput"><span class="identifier">cb</span></code> specifies
 199                   memory where the data to be written is located. The operation shall
 200                   always write a buffer in the sequence completely before proceeding
 201                   to the next.<br> <br> The implementation shall maintain one
 202                   or more copies of <code class="computeroutput"><span class="identifier">cb</span></code>
 203                   until such time as the write operation no longer requires access
 204                   to the memory specified by the buffers in the sequence. The program
 205                   must ensure the memory is valid until:<br> <br> &#8212; the last copy
 206                   of <code class="computeroutput"><span class="identifier">cb</span></code> is destroyed,
 207                   or<br> <br> &#8212; the handler for the asynchronous operation is invoked,<br>
 208                   <br> whichever comes first. If the total size of all buffers
 209                   in the sequence <code class="computeroutput"><span class="identifier">cb</span></code>
 210                   is <code class="computeroutput"><span class="number">0</span></code>, the asynchronous
 211                   operation shall complete immediately and pass <code class="computeroutput"><span class="number">0</span></code>
 212                   as the argument to the handler that specifies the number of bytes
 213                   read.<br> <br> If the operation completes successfully, the
 214                   <code class="computeroutput"><span class="identifier">WriteHandler</span></code> object
 215                   <code class="computeroutput"><span class="identifier">wh</span></code> is invoked with
 216                   the number of bytes transferred. Otherwise it is invoked with
 217                   <code class="computeroutput"><span class="number">0</span></code>.
 218                 </p>
 219               </td>
 220 </tr>
 221 </tbody>
 222 </table></div>
 223 </div>
 224 <br class="table-break">
 225 </div>
 226 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 227 <td align="left"></td>
 228 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2014 Christopher M. Kohlhoff<p>
 229         Distributed under the Boost Software License, Version 1.0. (See accompanying
 230         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>)
 231       </p>
 232 </div></td>
 233 </tr></table>
 234 <hr>
 235 <div class="spirit-nav">
 236 <a accesskey="p" href="SocketService.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="StreamHandleService.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
 237 </div>
 238 </body>
 239 </html>