<refentry id="camel-CamelStreamBuffer">
<refmeta>
<refentrytitle role="top_of_page" id="camel-CamelStreamBuffer.top_of_page">CamelStreamBuffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAMEL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>CamelStreamBuffer</refname>
<refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv id="camel-CamelStreamBuffer.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
struct              <link linkend="CamelStreamBuffer">CamelStreamBuffer</link>;
enum                <link linkend="CamelStreamBufferMode">CamelStreamBufferMode</link>;
<link linkend="CamelStream">CamelStream</link> *       <link linkend="camel-stream-buffer-new">camel_stream_buffer_new</link>             (<link linkend="CamelStream">CamelStream</link> *stream,
                                                         <link linkend="CamelStreamBufferMode">CamelStreamBufferMode</link> mode);
<link linkend="CamelStream">CamelStream</link> *       <link linkend="camel-stream-buffer-new-with-vbuf">camel_stream_buffer_new_with_vbuf</link>   (<link linkend="CamelStream">CamelStream</link> *stream,
                                                         <link linkend="CamelStreamBufferMode">CamelStreamBufferMode</link> mode,
                                                         <link linkend="char">char</link> *buf,
                                                         <link linkend="guint32">guint32</link> size);
<link linkend="int">int</link>                 <link linkend="camel-stream-buffer-gets">camel_stream_buffer_gets</link>            (<link linkend="CamelStreamBuffer">CamelStreamBuffer</link> *sbf,
                                                         <link linkend="char">char</link> *buf,
                                                         unsigned <link linkend="int">int</link> max);
<link linkend="char">char</link> *              <link linkend="camel-stream-buffer-read-line">camel_stream_buffer_read_line</link>       (<link linkend="CamelStreamBuffer">CamelStreamBuffer</link> *sbf);
</synopsis>
</refsynopsisdiv>









<refsect1 id="camel-CamelStreamBuffer.description" role="desc">
<title role="desc.title">Description</title>
<para>
</para>
</refsect1>

<refsect1 id="camel-CamelStreamBuffer.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CamelStreamBuffer" role="struct">
<title>struct CamelStreamBuffer</title>
<indexterm zone="CamelStreamBuffer"><primary sortas="CamelStreamBuffer">CamelStreamBuffer</primary></indexterm><programlisting>struct CamelStreamBuffer {
	CamelStream parent_object;

	/* these are all of course, private */
	CamelStream *stream;

	unsigned char *buf, *ptr, *end;
	int size;

	unsigned char *linebuf;	/* for reading lines at a time */
	int linesize;

	CamelStreamBufferMode mode;
	unsigned int flags;	/* internal flags */
};
</programlisting>
<para>
</para></refsect2>
<refsect2 id="CamelStreamBufferMode" role="enum">
<title>enum CamelStreamBufferMode</title>
<indexterm zone="CamelStreamBufferMode"><primary sortas="CamelStreamBufferMode">CamelStreamBufferMode</primary></indexterm><programlisting>typedef enum {
	CAMEL_STREAM_BUFFER_BUFFER = 0,
	CAMEL_STREAM_BUFFER_NONE,
	CAMEL_STREAM_BUFFER_READ = 0x00,
	CAMEL_STREAM_BUFFER_WRITE = 0x80,
	CAMEL_STREAM_BUFFER_MODE = 0x80
} CamelStreamBufferMode;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="camel-stream-buffer-new" role="function">
<title>camel_stream_buffer_new ()</title>
<indexterm zone="camel-stream-buffer-new"><primary sortas="camel_stream_buffer_new">camel_stream_buffer_new</primary></indexterm><programlisting><link linkend="CamelStream">CamelStream</link> *       camel_stream_buffer_new             (<link linkend="CamelStream">CamelStream</link> *stream,
                                                         <link linkend="CamelStreamBufferMode">CamelStreamBufferMode</link> mode);</programlisting>
<para>
Create a new buffered stream of another stream.  A default
buffer size (1024 bytes), automatically managed will be used
for buffering.
</para>
<para>
See <link linkend="camel-stream-buffer-new-with-vbuf"><type>camel_stream_buffer_new_with_vbuf</type></link> for details on the
<parameter>mode</parameter> parameter.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>stream</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelStream"><type>CamelStream</type></link> object to buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&#160;:</term>
<listitem><simpara> Operational mode of buffered stream.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly created buffered stream.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-stream-buffer-new-with-vbuf" role="function">
<title>camel_stream_buffer_new_with_vbuf ()</title>
<indexterm zone="camel-stream-buffer-new-with-vbuf"><primary sortas="camel_stream_buffer_new_with_vbuf">camel_stream_buffer_new_with_vbuf</primary></indexterm><programlisting><link linkend="CamelStream">CamelStream</link> *       camel_stream_buffer_new_with_vbuf   (<link linkend="CamelStream">CamelStream</link> *stream,
                                                         <link linkend="CamelStreamBufferMode">CamelStreamBufferMode</link> mode,
                                                         <link linkend="char">char</link> *buf,
                                                         <link linkend="guint32">guint32</link> size);</programlisting>
<para>
Create a new stream which buffers another stream, <parameter>stream</parameter>.
</para>
<para>
The following values are available for <parameter>mode</parameter>:
</para>
<para>
<link linkend="CAMEL-STREAM-BUFFER-BUFFER--CAPS"><type>CAMEL_STREAM_BUFFER_BUFFER</type></link>, Buffer the input/output in blocks.
<link linkend="CAMEL-STREAM-BUFFER-NEWLINE--CAPS"><type>CAMEL_STREAM_BUFFER_NEWLINE</type></link>, Buffer on newlines (for output).
<link linkend="CAMEL-STREAM-BUFFER-NONE--CAPS"><type>CAMEL_STREAM_BUFFER_NONE</type></link>, Perform no buffering.
</para>
<para>
Note that currently this is ignored and <link linkend="CAMEL-STREAM-BUFFER-BUFFER--CAPS"><type>CAMEL_STREAM_BUFFER_BUFFER</type></link>
is always used.
</para>
<para>
In addition, one of the following mode options should be or'd
together with the buffering mode:
</para>
<para>
<link linkend="CAMEL-STREAM-BUFFER-WRITE--CAPS"><type>CAMEL_STREAM_BUFFER_WRITE</type></link>, Buffer in write mode.
<link linkend="CAMEL-STREAM-BUFFER-READ--CAPS"><type>CAMEL_STREAM_BUFFER_READ</type></link>, Buffer in read mode.
</para>
<para>
Buffering can only be done in one direction for any
buffer instance.
</para>
<para>
If <parameter>buf</parameter> is non-NULL, then use the memory pointed to
(for upto <parameter>size</parameter> bytes) as the buffer for all buffering
operations.  It is upto the application to free this buffer.
If <parameter>buf</parameter> is NULL, then allocate and manage <parameter>size</parameter> bytes
for all buffering.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>stream</parameter>&#160;:</term>
<listitem><simpara> An existing stream to buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&#160;:</term>
<listitem><simpara> Mode to buffer in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> Memory to use for buffering.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara> Size of buffer to use.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A new stream with buffering applied.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-stream-buffer-gets" role="function">
<title>camel_stream_buffer_gets ()</title>
<indexterm zone="camel-stream-buffer-gets"><primary sortas="camel_stream_buffer_gets">camel_stream_buffer_gets</primary></indexterm><programlisting><link linkend="int">int</link>                 camel_stream_buffer_gets            (<link linkend="CamelStreamBuffer">CamelStreamBuffer</link> *sbf,
                                                         <link linkend="char">char</link> *buf,
                                                         unsigned <link linkend="int">int</link> max);</programlisting>
<para>
Read a line of characters up to the next newline character or
<parameter>max</parameter>-1 characters.
</para>
<para>
If the newline character is encountered, then it will be
included in the buffer <parameter>buf</parameter>.  The buffer will be <link linkend="NUL--CAPS"><type>NUL</type></link> terminated.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sbf</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelStreamBuffer"><type>CamelStreamBuffer</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> Memory to write the string to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max</parameter>&#160;:</term>
<listitem><simpara> Maxmimum number of characters to store.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of characters read, or <link linkend="0--CAPS"><literal>0</literal></link> for end of file,
and <link linkend="1--CAPS"><literal>-1</literal></link> on error.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="camel-stream-buffer-read-line" role="function">
<title>camel_stream_buffer_read_line ()</title>
<indexterm zone="camel-stream-buffer-read-line"><primary sortas="camel_stream_buffer_read_line">camel_stream_buffer_read_line</primary></indexterm><programlisting><link linkend="char">char</link> *              camel_stream_buffer_read_line       (<link linkend="CamelStreamBuffer">CamelStreamBuffer</link> *sbf);</programlisting>
<para>
This function reads a complete newline-terminated line from the stream
and returns it in allocated memory. The trailing newline (and carriage
return if any) are not included in the returned string.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sbf</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="CamelStreamBuffer"><type>CamelStreamBuffer</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the line read, which the caller must free when done with,
or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on eof. If an error occurs, <parameter>ex</parameter> will be set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
