<refentry id="gnome-vfs-20-gnome-vfs-ssl">
<refmeta>
<refentrytitle id="top_of_page">SSL support functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>SSL support functions</refname>
<refpurpose>Functions to send and receive encrypted data over a socket.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



<link linkend="gboolean">gboolean</link>    <link linkend="gnome-vfs-ssl-enabled">gnome_vfs_ssl_enabled</link>           (void);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-ssl-create">gnome_vfs_ssl_create</link>         (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> **handle_return,
                                             const <link linkend="char">char</link> *host,
                                             unsigned <link linkend="int">int</link> port,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-ssl-create-from-fd">gnome_vfs_ssl_create_from_fd</link> (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> **handle_return,
                                             <link linkend="gint">gint</link> fd,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-ssl-read">gnome_vfs_ssl_read</link>           (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <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-ssl-write">gnome_vfs_ssl_write</link>          (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <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="gnome-vfs-ssl-destroy">gnome_vfs_ssl_destroy</link>           (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
<link linkend="GnomeVFSSocket">GnomeVFSSocket</link>* <link linkend="gnome-vfs-ssl-to-socket">gnome_vfs_ssl_to_socket</link>     (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl);
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-ssl-set-timeout">gnome_vfs_ssl_set_timeout</link>    (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <link linkend="GTimeVal">GTimeVal</link> *timeout,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="gnome-vfs-ssl-enabled" role="function"/>gnome_vfs_ssl_enabled ()</title>
<indexterm><primary>gnome_vfs_ssl_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_vfs_ssl_enabled           (void);</programlisting>
<para>
Checks whether gnome-vfs was compiled with SSL support.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <literal>TRUE</literal> if gnome-vfs was compiled with SSL support,
otherwise <literal>FALSE</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-ssl-create" role="function"/>gnome_vfs_ssl_create ()</title>
<indexterm><primary>gnome_vfs_ssl_create</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_ssl_create         (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> **handle_return,
                                             const <link linkend="char">char</link> *host,
                                             unsigned <link linkend="int">int</link> port,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Creates an SSL socket connection at <parameter>handle_return</parameter> to <parameter>host</parameter> using
port <parameter>port</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="GnomeVFSSSL"><type>GnomeVFSSSL</type></link> struct, which will
contain an allocated <link linkend="GnomeVFSSSL"><type>GnomeVFSSSL</type></link> object on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>host</parameter>&nbsp;:</term>
<listitem><simpara> string indicating the hostname to establish an SSL connection with.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>port</parameter>&nbsp;:</term>
<listitem><simpara> port number to connect to.
</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-ssl-create-from-fd" role="function"/>gnome_vfs_ssl_create_from_fd ()</title>
<indexterm><primary>gnome_vfs_ssl_create_from_fd</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_ssl_create_from_fd (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> **handle_return,
                                             <link linkend="gint">gint</link> fd,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Try to establish an SSL connection over the file descriptor <parameter>fd</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>handle_return</parameter>&nbsp;:</term>
<listitem><simpara> pointer to a <link linkend="GnomeVFSSSL"><type>GnomeVFSSSL</type></link> struct, which will
contain an allocated <link linkend="GnomeVFSSSL"><type>GnomeVFSSSL</type></link> object on return.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fd</parameter>&nbsp;:</term>
<listitem><simpara> file descriptior to try and establish an SSL connection over.
</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> a <link linkend="GnomeVFSResult"><type>GnomeVFSResult</type></link> indicating the success of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-ssl-read" role="function"/>gnome_vfs_ssl_read ()</title>
<indexterm><primary>gnome_vfs_ssl_read</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_ssl_read           (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <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 SSL socket <parameter>ssl</parameter> into <parameter>buffer</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ssl</parameter>&nbsp;:</term>
<listitem><simpara> SSL 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 write into.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> number of bytes to read from <parameter>ssl</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 <parameter>ssl</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-ssl-write" role="function"/>gnome_vfs_ssl_write ()</title>
<indexterm><primary>gnome_vfs_ssl_write</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_ssl_write          (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <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>ssl</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ssl</parameter>&nbsp;:</term>
<listitem><simpara> SSL 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 to write from <parameter>buffer</parameter> to <parameter>ssl</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 socket 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-ssl-destroy" role="function"/>gnome_vfs_ssl_destroy ()</title>
<indexterm><primary>gnome_vfs_ssl_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_vfs_ssl_destroy           (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <link linkend="GnomeVFSCancellation">GnomeVFSCancellation</link> *cancellation);</programlisting>
<para>
Free resources used by <parameter>ssl</parameter> and close the connection.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ssl</parameter>&nbsp;:</term>
<listitem><simpara> SSL socket to be closed and destroyed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellation</parameter>&nbsp;:</term>
<listitem><simpara> handle allowing cancellation of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-ssl-to-socket" role="function"/>gnome_vfs_ssl_to_socket ()</title>
<indexterm><primary>gnome_vfs_ssl_to_socket</primary></indexterm><programlisting><link linkend="GnomeVFSSocket">GnomeVFSSocket</link>* gnome_vfs_ssl_to_socket     (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl);</programlisting>
<para>
Wrap an SSL socket inside a standard <link linkend="GnomeVFSSocket"><type>GnomeVFSSocket</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ssl</parameter>&nbsp;:</term>
<listitem><simpara> SSL socket to convert into a standard socket.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated <link linkend="GnomeVFSSocket"><type>GnomeVFSSocket</type></link> corresponding to <parameter>ssl</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-ssl-set-timeout" role="function" condition="since:2.8"/>gnome_vfs_ssl_set_timeout ()</title>
<indexterm role="2.8"><primary>gnome_vfs_ssl_set_timeout</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_ssl_set_timeout    (<link linkend="GnomeVFSSSL">GnomeVFSSSL</link> *ssl,
                                             <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>ssl</parameter>&nbsp;:</term>
<listitem><simpara> SSL 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>
