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

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

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

<synopsis>



<link linkend="GnomeVFSResult">GnomeVFSResult</link> (<link linkend="GnomeVFSSocketReadFunc">*GnomeVFSSocketReadFunc</link>)    (<link linkend="gpointer">gpointer</link> connection,
                                             <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="GnomeVFSSocketWriteFunc">*GnomeVFSSocketWriteFunc</link>)   (<link linkend="gpointer">gpointer</link> connection,
                                             <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="void">void</link>        (<link linkend="GnomeVFSSocketCloseFunc">*GnomeVFSSocketCloseFunc</link>)      (<link linkend="gpointer">gpointer</link> connection,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
            <link linkend="GnomeVFSSocketImpl">GnomeVFSSocketImpl</link>;
<link linkend="GnomeVFSSocket">GnomeVFSSocket</link>* <link linkend="gnome-vfs-socket-new">gnome_vfs_socket_new</link>        (<link linkend="GnomeVFSSocketImpl">GnomeVFSSocketImpl</link> *impl,
                                             <link linkend="void">void</link> *connection);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-write">gnome_vfs_socket_write</link>       (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="gconstpointer">gconstpointer</link> buffer,
                                             <link linkend="int">int</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-close">gnome_vfs_socket_close</link>       (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-read">gnome_vfs_socket_read</link>        (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <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="void">void</link>        <link linkend="gnome-vfs-socket-free">gnome_vfs_socket_free</link>           (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-socket-set-timeout">gnome_vfs_socket_set_timeout</link> (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="GTimeVal">GTimeVal</link> *timeout,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>
The GnomeVFSSocket function family unifies network I/O through functions
similar to the standard POSIX read/write functions. The main difference is
that all operations are cancellable through the standard GnomeVFS cancellation
mechanism and you can specify a maximum amount of time an operation may take
through <link linkend="gnome-vfs-socket-set-timeout"><type>gnome_vfs_socket_set_timeout</type></link>.

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="GnomeVFSSocketReadFunc" role="function"/>GnomeVFSSocketReadFunc ()</title>
<indexterm><primary>GnomeVFSSocketReadFunc</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> (*GnomeVFSSocketReadFunc)    (<link linkend="gpointer">gpointer</link> connection,
                                             <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>

</para><variablelist role="params">
<varlistentry><term><parameter>connection</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_read</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GnomeVFSSocketWriteFunc" role="function"/>GnomeVFSSocketWriteFunc ()</title>
<indexterm><primary>GnomeVFSSocketWriteFunc</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> (*GnomeVFSSocketWriteFunc)   (<link linkend="gpointer">gpointer</link> connection,
                                             <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>

</para><variablelist role="params">
<varlistentry><term><parameter>connection</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GnomeVFSSocketCloseFunc" role="function"/>GnomeVFSSocketCloseFunc ()</title>
<indexterm><primary>GnomeVFSSocketCloseFunc</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSSocketCloseFunc)      (<link linkend="gpointer">gpointer</link> connection,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>connection</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GnomeVFSSocketImpl" role="struct"/>GnomeVFSSocketImpl</title>
<indexterm><primary>GnomeVFSSocketImpl</primary></indexterm><programlisting>typedef struct {
  GnomeVFSSocketReadFunc read;
  GnomeVFSSocketWriteFunc write;
  GnomeVFSSocketCloseFunc close;
  GnomeVFSSocketSetTimeoutFunc set_timeout;
} GnomeVFSSocketImpl;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-new" role="function"/>gnome_vfs_socket_new ()</title>
<indexterm><primary>gnome_vfs_socket_new</primary></indexterm><programlisting><link linkend="GnomeVFSSocket">GnomeVFSSocket</link>* gnome_vfs_socket_new        (<link linkend="GnomeVFSSocketImpl">GnomeVFSSocketImpl</link> *impl,
                                             <link linkend="void">void</link> *connection);</programlisting>
<para>
Creates a new <link linkend="GnomeVFSSocket"><type>GnomeVFSSocket</type></link> using the specific implementation
<parameter>impl</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>impl</parameter>&nbsp;:</term>
<listitem><simpara> an implementation of socket, e.g. <link linkend="GnomeVFSSSL"><type>GnomeVFSSSL</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>connection</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a connection object used by <parameter>impl</parameter> to track.
state (the exact nature of <parameter>connection</parameter> varies from implementation to
implementation).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly created socket.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-write" role="function"/>gnome_vfs_socket_write ()</title>
<indexterm><primary>gnome_vfs_socket_write</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_write       (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="gconstpointer">gconstpointer</link> buffer,
                                             <link linkend="int">int</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</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> socket to write data to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> data to write to the socket.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> number of bytes from <parameter>buffer</parameter> to write to <parameter>socket</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</parameter> on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> optional cancellation object.
</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-close" role="function"/>gnome_vfs_socket_close ()</title>
<indexterm><primary>gnome_vfs_socket_close</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_close       (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Close <parameter>socket</parameter>, freeing any resources it may be using.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> the socket to be closed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> optional cancellation object.
</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-read" role="function"/>gnome_vfs_socket_read ()</title>
<indexterm><primary>gnome_vfs_socket_read</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_read        (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <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>buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> 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</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 socket on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> optional cancellation object.
</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-free" role="function" condition="since:2.8"/>gnome_vfs_socket_free ()</title>
<indexterm role="2.8"><primary>gnome_vfs_socket_free</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_socket_free           (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket);</programlisting>
<para>
Frees the memory allocated for <parameter>socket</parameter>, but does
not call any <link linkend="GnomeVFSSocketImpl"><type>GnomeVFSSocketImpl</type></link> function.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> The <link linkend="GnomeVFSSocket"><type>GnomeVFSSocket</type></link> you want to free. 
</simpara></listitem></varlistentry>
</variablelist><para>Since  2.8
</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-socket-set-timeout" role="function" condition="since:2.8"/>gnome_vfs_socket_set_timeout ()</title>
<indexterm role="2.8"><primary>gnome_vfs_socket_set_timeout</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_socket_set_timeout (<link linkend="GnomeVFSSocket">GnomeVFSSocket</link> *socket,
                                             <link linkend="GTimeVal">GTimeVal</link> *timeout,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Set a timeout of <parameter>timeout</parameter>. If <parameter>timeout</parameter> is <literal>NULL</literal>, following operations
will block indefinitely).
</para>
<para>
Note if you set <parameter>timeout</parameter> to 0 (means tv_sec and tv_usec are both 0)
every following operation will return immediately. (This can be used
for polling.)</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&nbsp;:</term>
<listitem><simpara> socket to set the timeout of.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout</parameter>&nbsp;:</term>
<listitem><simpara> the timeout.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> optional cancellation object.
</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>
