364 lines
16 KiB
HTML
364 lines
16 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
|
|
<title>streambuf</title>
|
||
|
|
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
|
||
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
|
||
|
|
<link rel="home" href="../../index.html" title="Asio">
|
||
|
|
<link rel="up" href="../reference.html" title="Reference">
|
||
|
|
<link rel="prev" href="stream_file.html" title="stream_file">
|
||
|
|
<link rel="next" href="system_category.html" title="system_category">
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
|
</head>
|
||
|
|
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
|
|
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../../asio.png"></td></tr></table>
|
||
|
|
<hr>
|
||
|
|
<div class="spirit-nav">
|
||
|
|
<a accesskey="p" href="stream_file.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="system_category.html"><img src="../../next.png" alt="Next"></a>
|
||
|
|
</div>
|
||
|
|
<div class="section">
|
||
|
|
<div class="titlepage"><div><div><h3 class="title">
|
||
|
|
<a name="asio.reference.streambuf"></a><a class="link" href="streambuf.html" title="streambuf">streambuf</a>
|
||
|
|
</h3></div></div></div>
|
||
|
|
<p>
|
||
|
|
<a class="indexterm" name="asio.indexterm.streambuf"></a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
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>
|
||
|
|
<h5>
|
||
|
|
<a name="asio.reference.streambuf.h0"></a>
|
||
|
|
<span><a name="asio.reference.streambuf.types"></a></span><a class="link" href="streambuf.html#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>
|
||
|
|
<h5>
|
||
|
|
<a name="asio.reference.streambuf.h1"></a>
|
||
|
|
<span><a name="asio.reference.streambuf.member_functions"></a></span><a class="link" href="streambuf.html#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> <span class="silver">[constructor]</span>
|
||
|
|
</p>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<p>
|
||
|
|
Construct a basic_streambuf object.
|
||
|
|
</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<p>
|
||
|
|
<a class="link" href="basic_streambuf/capacity.html" title="basic_streambuf::capacity"><span class="bold"><strong>capacity</strong></span></a>
|
||
|
|
</p>
|
||
|
|
</td>
|
||
|
|
<td>
|
||
|
|
<p>
|
||
|
|
Get the current capacity of the basic_streambuf.
|
||
|
|
</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>
|
||
|
|
<h5>
|
||
|
|
<a name="asio.reference.streambuf.h2"></a>
|
||
|
|
<span><a name="asio.reference.streambuf.protected_member_functions"></a></span><a class="link" href="streambuf.html#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>
|
||
|
|
<h5>
|
||
|
|
<a name="asio.reference.streambuf.h3"></a>
|
||
|
|
<span><a name="asio.reference.streambuf.examples"></a></span><a class="link" href="streambuf.html#asio.reference.streambuf.examples">Examples</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
Writing directly from an streambuf to a socket:
|
||
|
|
</p>
|
||
|
|
<pre class="programlisting"><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">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">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>
|
||
|
|
<h5>
|
||
|
|
<a name="asio.reference.streambuf.h4"></a>
|
||
|
|
<span><a name="asio.reference.streambuf.requirements"></a></span><a class="link" href="streambuf.html#asio.reference.streambuf.requirements">Requirements</a>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<span class="emphasis"><em>Header: </em></span><code class="literal">asio/streambuf.hpp</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<span class="emphasis"><em>Convenience header: </em></span><code class="literal">asio.hpp</code>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<div class="copyright-footer">Copyright © 2003-2023 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>
|
||
|
|
<hr>
|
||
|
|
<div class="spirit-nav">
|
||
|
|
<a accesskey="p" href="stream_file.html"><img src="../../prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../home.png" alt="Home"></a><a accesskey="n" href="system_category.html"><img src="../../next.png" alt="Next"></a>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|