<refentry id="gnome-vfs-20-gnome-vfs-socket-buffer">
<refmeta>
<refentrytitle id="top_of_page">Unified bufferd network I/O</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Unified bufferd network I/O</refname>
<refpurpose>Posix style buffered network input/output.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link>* <link linkend="gnome-vfs-socket-buffer-new">gnome_vfs_socket_buffer_new</link>
                                            (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-destroy">gnome_vfs_socket_buffer_destroy</link>
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gboolean">gboolean</link> close_socket,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-read">gnome_vfs_socket_buffer_read</link> (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gpointer">gpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-peekc">gnome_vfs_socket_buffer_peekc</link>
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="char">char</link> *character,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-write">gnome_vfs_socket_buffer_write</link>
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gconstpointer">gconstpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_written,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-flush">gnome_vfs_socket_buffer_flush</link>
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-buffer-read-until">gnome_vfs_socket_buffer_read_until</link>
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gpointer">gpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="gconstpointer">gconstpointer</link> boundary,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> boundary_len,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read,
                                             <link linkend="gboolean">gboolean</link> *got_boundary,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>
The GnomeVFSSocketBuffer functions are very similar to the GnomeVFSSocket
ones. The only difference is that all input/output is done through an internally
managed buffer. This might increase I/O performance as well as give you the
possibility to use some convenient functions like <link linkend="gnome-vfs-socket-buffer-peekc"><type>gnome_vfs_socket_buffer_peekc</type></link>
and <link linkend="gnome-vfs-socket-buffer-read-until"><type>gnome_vfs_socket_buffer_read_until</type></link>.

<para>
</para>

You can manually force all internally buffered data to get written with
<link linkend="gnome-vfs-socket-buffer-flush"><type>gnome_vfs_socket_buffer_flush</type></link>.

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-new" role="function"/>gnome_vfs_socket_buffer_new ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_new</primary></indexterm><programlisting><link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link>* gnome_vfs_socket_buffer_new
                                            (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket);</programlisting>
<para>
Create a socket buffer around <parameter>socket</parameter>. A buffered
socket allows data to be poked at without reading it
as it will be buffered. A future read will retrieve
the data again.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> socket to be buffered.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated <link linkend="GnomeVFSSocketBuffer"><type>GnomeVFSSocketBuffer</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-destroy" role="function"/>gnome_vfs_socket_buffer_destroy ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_destroy</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_destroy
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gboolean">gboolean</link> close_socket,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Free the socket buffer.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> buffered socket to destroy.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>close_socket</parameter>&nbsp;:</term>
<listitem><simpara> if <literal>TRUE</literal>, the socket being buffered will be closed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-read" role="function"/>gnome_vfs_socket_buffer_read ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_read</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_read (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gpointer">gpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Read <parameter>bytes</parameter> bytes of data from the <parameter>socket</parameter> into <parameter>socket_buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> buffered socket to read data from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> allocated buffer of at least <parameter>bytes</parameter> bytes to be read into.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> number of bytes to read from <parameter>socket_buffer</parameter> into <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_read</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link>, will contain
the number of bytes actually read from the <parameter>socket_buffer</parameter> on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-peekc" role="function"/>gnome_vfs_socket_buffer_peekc ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_peekc</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_peekc
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="char">char</link> *character,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Peek at the next character in <parameter>socket_buffer</parameter> without actually reading
the character in. The next read will retrieve <parameter>c</parameter> (as well as any following
data if requested).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> the socket buffer to read from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>character</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a char, will contain a character on return from
a successful "peek".
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-write" role="function"/>gnome_vfs_socket_buffer_write ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_write</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_write
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gconstpointer">gconstpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_written,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Write <parameter>bytes</parameter> bytes of data from <parameter>buffer</parameter> to <parameter>socket_buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> buffered socket to write data to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> data to write to the <parameter>socket_buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> number of bytes to write from <parameter>buffer</parameter> to <parameter>socket_buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link>, will contain
the number of bytes actually written to the <parameter>socket_buffer</parameter> on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-flush" role="function"/>gnome_vfs_socket_buffer_flush ()</title>
<indexterm><primary>gnome_vfs_socket_buffer_flush</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_flush
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Write all outstanding data to <parameter>socket_buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> buffer to flush.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-buffer-read-until" role="function" condition="since:2.8"/>gnome_vfs_socket_buffer_read_until ()</title>
<indexterm role="2.8"><primary>gnome_vfs_socket_buffer_read_until</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_buffer_read_until
                                            (<link linkend="GnomeVFSSocketBuffer">GnomeVFSSocketBuffer</link> *socket_buffer,
                                             <link linkend="gpointer">gpointer</link> buffer,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
                                             <link linkend="gconstpointer">gconstpointer</link> boundary,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> boundary_len,
                                             <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read,
                                             <link linkend="gboolean">gboolean</link> *got_boundary,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Read up to <parameter>bytes</parameter> bytes of data from the <parameter>socket_buffer</parameter> into <parameter>buffer</parameter> 
until boundary is reached. <parameter>got_boundary</parameter> will be set accordingly.
</para>
<para>
Note that if <parameter>bytes</parameter> is smaller than <parameter>boundary_len</parameter> there is no way
to detected the boundary! So if you want to make sure that every boundary
is found (in a loop maybe) assure that <parameter>bytes</parameter> is at least as big as 
<parameter>boundary_len</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket_buffer</parameter>&nbsp;:</term>
<listitem><simpara> buffered socket to read data from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> allocated buffer of at least <parameter>bytes</parameter> bytes to be read into.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> maximum number of bytes to read from <parameter>socket_buffer</parameter> into <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boundary</parameter>&nbsp;:</term>
<listitem><simpara> the boundary until which is read.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>boundary_len</parameter>&nbsp;:</term>
<listitem><simpara> the length of the <parameter>boundary</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_read</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="GnomeVFSFileSize"><type>GnomeVFSFileSize</type></link>, will contain
the number of bytes actually read from the <parameter>socket_buffer</parameter> on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>got_boundary</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="gboolean"><type>gboolean</type></link>  which will be <literal>TRUE</literal> if the boundary
was found or <literal>FALSE</literal> otherwise.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.

</simpara></listitem></varlistentry>
</variablelist><para>Since  2.8
</para></refsect2>

</refsect1>




</refentry>
