| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>streambuf</title> |
| <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../../boost_asio.html" title="Boost.Asio"> |
| <link rel="up" href="../reference.html" title="Reference"> |
| <link rel="prev" href="stream_socket_service/stream_socket_service.html" title="stream_socket_service::stream_socket_service"> |
| <link rel="next" href="time_traits_lt__ptime__gt_.html" title="time_traits< boost::posix_time::ptime >"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> |
| <td align="center"><a href="../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="stream_socket_service/stream_socket_service.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="time_traits_lt__ptime__gt_.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="boost_asio.reference.streambuf"></a><a class="link" href="streambuf.html" title="streambuf">streambuf</a> |
| </h3></div></div></div> |
| <p> |
| <a class="indexterm" name="id1359204"></a> |
| Typedef for the typical usage of <a class="link" href="basic_streambuf.html" title="basic_streambuf"><code class="computeroutput"><span class="identifier">basic_streambuf</span></code></a>. |
| </p> |
| <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">basic_streambuf</span> <span class="identifier">streambuf</span><span class="special">;</span> |
| </pre> |
| <a name="boost_asio.reference.streambuf.types"></a><h5> |
| <a name="id1359263"></a> |
| <a class="link" href="streambuf.html#boost_asio.reference.streambuf.types">Types</a> |
| </h5> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Name |
| </p> |
| </th> |
| <th> |
| <p> |
| Description |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/const_buffers_type.html" title="basic_streambuf::const_buffers_type"><span class="bold"><strong>const_buffers_type</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The type used to represent the input sequence as a list of buffers. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/mutable_buffers_type.html" title="basic_streambuf::mutable_buffers_type"><span class="bold"><strong>mutable_buffers_type</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The type used to represent the output sequence as a list of buffers. |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <a name="boost_asio.reference.streambuf.member_functions"></a><h5> |
| <a name="id1359376"></a> |
| <a class="link" href="streambuf.html#boost_asio.reference.streambuf.member_functions">Member Functions</a> |
| </h5> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Name |
| </p> |
| </th> |
| <th> |
| <p> |
| Description |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/basic_streambuf.html" title="basic_streambuf::basic_streambuf"><span class="bold"><strong>basic_streambuf</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Construct a basic_streambuf object. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/commit.html" title="basic_streambuf::commit"><span class="bold"><strong>commit</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Move characters from the output sequence to the input sequence. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/consume.html" title="basic_streambuf::consume"><span class="bold"><strong>consume</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Remove characters from the input sequence. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/data.html" title="basic_streambuf::data"><span class="bold"><strong>data</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Get a list of buffers that represents the input sequence. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/max_size.html" title="basic_streambuf::max_size"><span class="bold"><strong>max_size</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Get the maximum size of the basic_streambuf. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/prepare.html" title="basic_streambuf::prepare"><span class="bold"><strong>prepare</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Get a list of buffers that represents the output sequence, with |
| the given size. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/size.html" title="basic_streambuf::size"><span class="bold"><strong>size</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Get the size of the input sequence. |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <a name="boost_asio.reference.streambuf.protected_member_functions"></a><h5> |
| <a name="id1359632"></a> |
| <a class="link" href="streambuf.html#boost_asio.reference.streambuf.protected_member_functions">Protected |
| Member Functions</a> |
| </h5> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Name |
| </p> |
| </th> |
| <th> |
| <p> |
| Description |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/overflow.html" title="basic_streambuf::overflow"><span class="bold"><strong>overflow</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Override std::streambuf behaviour. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/reserve.html" title="basic_streambuf::reserve"><span class="bold"><strong>reserve</strong></span></a> |
| </p> |
| </td> |
| <td> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="basic_streambuf/underflow.html" title="basic_streambuf::underflow"><span class="bold"><strong>underflow</strong></span></a> |
| </p> |
| </td> |
| <td> |
| <p> |
| Override std::streambuf behaviour. |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| The <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> class |
| is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">streambuf</span></code> to associate the streambuf's |
| input and output sequences with one or more character arrays. These character |
| arrays are internal to the <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> |
| object, but direct access to the array elements is provided to permit them |
| to be used efficiently with I/O operations. Characters written to the output |
| sequence of a <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> |
| object are appended to the input sequence of the same object. |
| </p> |
| <p> |
| The <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> class's |
| public interface is intended to permit the following implementation strategies: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| A single contiguous character array, which is reallocated as necessary |
| to accommodate changes in the size of the character sequence. This is |
| the implementation approach currently used in Asio. |
| </li> |
| <li class="listitem"> |
| A sequence of one or more character arrays, where each array is of the |
| same size. Additional character array objects are appended to the sequence |
| to accommodate changes in the size of the character sequence. |
| </li> |
| <li class="listitem"> |
| A sequence of one or more character arrays of varying sizes. Additional |
| character array objects are appended to the sequence to accommodate changes |
| in the size of the character sequence. |
| </li> |
| </ul></div> |
| <p> |
| The constructor for <a class="link" href="basic_streambuf.html" title="basic_streambuf"><code class="computeroutput"><span class="identifier">basic_streambuf</span></code></a> accepts a <code class="computeroutput"><span class="identifier">size_t</span></code> argument specifying the maximum |
| of the sum of the sizes of the input sequence and output sequence. During |
| the lifetime of the <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> |
| object, the following invariant holds: |
| </p> |
| <pre class="programlisting"><span class="identifier">size</span><span class="special">()</span> <span class="special"><=</span> <span class="identifier">max_size</span><span class="special">()</span> |
| </pre> |
| <p> |
| Any member function that would, if successful, cause the invariant to be |
| violated shall throw an exception of class <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">length_error</span></code>. |
| </p> |
| <p> |
| The constructor for <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> |
| takes an Allocator argument. A copy of this argument is used for any memory |
| allocation performed, by the constructor and by all member functions, during |
| the lifetime of each <code class="computeroutput"><span class="identifier">basic_streambuf</span></code> |
| object. |
| </p> |
| <a name="boost_asio.reference.streambuf.examples"></a><h5> |
| <a name="id1360007"></a> |
| <a class="link" href="streambuf.html#boost_asio.reference.streambuf.examples">Examples</a> |
| </h5> |
| <p> |
| Writing directly from an streambuf to a socket: |
| </p> |
| <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">b</span><span class="special">;</span> |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="identifier">os</span><span class="special">(&</span><span class="identifier">b</span><span class="special">);</span> |
| <span class="identifier">os</span> <span class="special"><<</span> <span class="string">"Hello, World!\n"</span><span class="special">;</span> |
| |
| <span class="comment">// try sending some data in input sequence |
| </span><span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">sock</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="identifier">b</span><span class="special">.</span><span class="identifier">data</span><span class="special">());</span> |
| |
| <span class="identifier">b</span><span class="special">.</span><span class="identifier">consume</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span> <span class="comment">// sent data is removed from input sequence |
| </span></pre> |
| <p> |
| Reading from a socket directly into a streambuf: |
| </p> |
| <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">b</span><span class="special">;</span> |
| |
| <span class="comment">// reserve 512 bytes in output sequence |
| </span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span><span class="special">::</span><span class="identifier">mutable_buffers_type</span> <span class="identifier">bufs</span> <span class="special">=</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">prepare</span><span class="special">(</span><span class="number">512</span><span class="special">);</span> |
| |
| <span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">sock</span><span class="special">.</span><span class="identifier">receive</span><span class="special">(</span><span class="identifier">bufs</span><span class="special">);</span> |
| |
| <span class="comment">// received data is "committed" from output sequence to input sequence |
| </span><span class="identifier">b</span><span class="special">.</span><span class="identifier">commit</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span> |
| |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span> <span class="identifier">is</span><span class="special">(&</span><span class="identifier">b</span><span class="special">);</span> |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span><span class="special">;</span> |
| <span class="identifier">is</span> <span class="special">>></span> <span class="identifier">s</span><span class="special">;</span> |
| </pre> |
| <a name="boost_asio.reference.streambuf.requirements"></a><h5> |
| <a name="id1360485"></a> |
| <a class="link" href="streambuf.html#boost_asio.reference.streambuf.requirements">Requirements</a> |
| </h5> |
| <p> |
| <span class="bold"><strong>Header: </strong></span><code class="literal">boost/asio/streambuf.hpp</code> |
| </p> |
| <p> |
| <span class="bold"><strong>Convenience header: </strong></span><code class="literal">boost/asio.hpp</code> |
| </p> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2003 - 2010 Christopher M. Kohlhoff<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| 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>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="stream_socket_service/stream_socket_service.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="time_traits_lt__ptime__gt_.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |
