<refentry id="streamtuner-st-transfer-api">
<refmeta>
<refentrytitle>st-transfer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>STREAMTUNER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>st-transfer</refname><refpurpose>functions for transferring data over the network.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



struct      <link linkend="STTransferSession">STTransferSession</link>;
enum        <link linkend="STTransferFlags">STTransferFlags</link>;
<link linkend="void">void</link>        (<link linkend="STTransferLineCallback">*STTransferLineCallback</link>)       (const <link linkend="char">char</link> *line,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="STTransferSession">STTransferSession</link>* <link linkend="st-transfer-session-new">st_transfer_session_new</link>  (void);
<link linkend="void">void</link>        <link linkend="st-transfer-session-free">st_transfer_session_free</link>        (<link linkend="STTransferSession">STTransferSession</link> *session);
<link linkend="gboolean">gboolean</link>    <link linkend="st-transfer-session-get">st_transfer_session_get</link>         (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="char">char</link> **headers,
                                             <link linkend="char">char</link> **body,
                                             <link linkend="GError">GError</link> **err);
<link linkend="gboolean">gboolean</link>    <link linkend="st-transfer-session-get-binary">st_transfer_session_get_binary</link>  (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="char">char</link> **headers,
                                             <link linkend="guint8">guint8</link> **body,
                                             unsigned <link linkend="int">int</link> *body_len,
                                             <link linkend="GError">GError</link> **err);
<link linkend="gboolean">gboolean</link>    <link linkend="st-transfer-session-get-by-line">st_transfer_session_get_by_line</link> (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> header_cb,
                                             <link linkend="gpointer">gpointer</link> header_data,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> body_cb,
                                             <link linkend="gpointer">gpointer</link> body_data,
                                             <link linkend="GError">GError</link> **err);
<link linkend="char">char</link>*       <link linkend="st-transfer-escape">st_transfer_escape</link>              (const <link linkend="char">char</link> *url);
<link linkend="char">char</link>*       <link linkend="st-transfer-get-full">st_transfer_get_full</link>            (const <link linkend="char">char</link> *url,
                                             <link linkend="GError">GError</link> **err);
<link linkend="gboolean">gboolean</link>    <link linkend="st-transfer-get-lines">st_transfer_get_lines</link>           (const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **err);
<link linkend="char">char</link>*       <link linkend="st-transfer-get-full-with-session">st_transfer_get_full_with_session</link>
                                            (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="GError">GError</link> **err);
<link linkend="gboolean">gboolean</link>    <link linkend="st-transfer-get-lines-with-session">st_transfer_get_lines_with_session</link>
                                            (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **err);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="STTransferSession"/>struct STTransferSession</title>
<indexterm><primary>STTransferSession</primary></indexterm><programlisting>struct STTransferSession;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="STTransferFlags"/>enum STTransferFlags</title>
<indexterm><primary>STTransferFlags</primary></indexterm><programlisting>typedef enum
{
  ST_TRANSFER_PASS_NEWLINE		= 1 &lt;&lt; 0,
  ST_TRANSFER_UTF8			= 1 &lt;&lt; 1,
  ST_TRANSFER_PARSE_HTTP_CHARSET	= 1 &lt;&lt; 2,
  ST_TRANSFER_PARSE_HTML_CHARSET	= 1 &lt;&lt; 3
} STTransferFlags;
</programlisting>
<para>

</para><variablelist role="enum">
<varlistentry>
<term><literal>ST_TRANSFER_PASS_NEWLINE</literal></term>
<listitem><simpara>specifies that the line terminator should
be included in the line passed to <link linkend="STTransferLineCallback"><function>STTransferLineCallback()</function></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ST_TRANSFER_UTF8</literal></term>
<listitem><simpara>specifies that <link linkend="st-transfer-session-get"><function>st_transfer_session_get()</function></link> should
fail if the body cannot be converted to UTF-8, and that
<link linkend="st-transfer-session-get-by-line"><function>st_transfer_session_get_by_line()</function></link> should skip the body lines which
cannot be converted to UTF-8.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ST_TRANSFER_PARSE_HTTP_CHARSET</literal></term>
<listitem><simpara>specifies that charset information
should be extracted from the HTTP Content-Type header, if present. To
be used along with <link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>ST_TRANSFER_PARSE_HTML_CHARSET</literal></term>
<listitem><simpara>specifies that charset information
should be extracted from the http-equiv="Content-Type" meta tag of the
HTML header, if present. To be used along with <link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link>.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="STTransferLineCallback"/>STTransferLineCallback ()</title>
<indexterm><primary>STTransferLineCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*STTransferLineCallback)       (const <link linkend="char">char</link> *line,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function to pass to
<link linkend="st-transfer-session-get-by-line"><function>st_transfer_session_get_by_line()</function></link>.
</para>
<para>
The function will be called whenever a line has been transferred.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>line</parameter>&nbsp;:</term>
<listitem><simpara> a line. If <link linkend="ST-TRANSFER-PASS-NEWLINE-CAPS"><type>ST_TRANSFER_PASS_NEWLINE</type></link> was used, the line
terminator is included. If <link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link> was used, the line is
valid UTF-8.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> data pointer passed to <link linkend="st-transfer-session-get-by-line"><function>st_transfer_session_get_by_line()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-session-new"/>st_transfer_session_new ()</title>
<indexterm><primary>st_transfer_session_new</primary></indexterm><programlisting><link linkend="STTransferSession">STTransferSession</link>* st_transfer_session_new  (void);</programlisting>
<para>
Creates a new transfer session.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new session, which should be freed with
<link linkend="st-transfer-session-free"><function>st_transfer_session_free()</function></link> when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-session-free"/>st_transfer_session_free ()</title>
<indexterm><primary>st_transfer_session_free</primary></indexterm><programlisting><link linkend="void">void</link>        st_transfer_session_free        (<link linkend="STTransferSession">STTransferSession</link> *session);</programlisting>
<para>
Destroys <parameter>session</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> the transfer session to destroy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-session-get"/>st_transfer_session_get ()</title>
<indexterm><primary>st_transfer_session_get</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_transfer_session_get         (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="char">char</link> **headers,
                                             <link linkend="char">char</link> **body,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<para>
Gets the data located at <parameter>url</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a transfer session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> the URL of the data to get.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> the transfer flags. Valid flags are <link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link>,
<link linkend="ST-TRANSFER-PARSE-HTTP-CHARSET-CAPS"><type>ST_TRANSFER_PARSE_HTTP_CHARSET</type></link> and
<link linkend="ST-TRANSFER-PARSE-HTML-CHARSET-CAPS"><type>ST_TRANSFER_PARSE_HTML_CHARSET</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>headers</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the header data, or <literal>NULL</literal>. The
returned data is guaranteed to be valid ASCII.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>body</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the body data, or <literal>NULL</literal>. If
<link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link> is used, the returned data is guaranteed to be
valid UTF-8.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> a location to store errors, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>FALSE</literal> if there was an error (in such case, <parameter>err</parameter> will
be set). If <literal>TRUE</literal> is returned, strings will be stored at <parameter>headers</parameter>
and <parameter>body</parameter>. They should be freed when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-session-get-binary"/>st_transfer_session_get_binary ()</title>
<indexterm><primary>st_transfer_session_get_binary</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_transfer_session_get_binary  (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="char">char</link> **headers,
                                             <link linkend="guint8">guint8</link> **body,
                                             unsigned <link linkend="int">int</link> *body_len,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<para>
Gets the binary data located at <parameter>url</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a transfer session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> the URL of the data to get.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> must be 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>headers</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the header data, or <literal>NULL</literal>. The
returned data is guaranteed to be valid ASCII.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>body</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the body data, or <literal>NULL</literal>. If set,
<parameter>body_len</parameter> must also be set.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>body_len</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the body length, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> a location to store errors, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>FALSE</literal> if there was an error (in such case, <parameter>err</parameter> will
be set). If <literal>TRUE</literal> is returned, a string will be stored at <parameter>headers</parameter>
and a character buffer will be stored at <parameter>body</parameter>. They both should be
freed when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-session-get-by-line"/>st_transfer_session_get_by_line ()</title>
<indexterm><primary>st_transfer_session_get_by_line</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_transfer_session_get_by_line (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferFlags">STTransferFlags</link> flags,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> header_cb,
                                             <link linkend="gpointer">gpointer</link> header_data,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> body_cb,
                                             <link linkend="gpointer">gpointer</link> body_data,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<para>
Gets the data located at <parameter>url</parameter>, splitting it into lines and passing
them to <parameter>header_cb</parameter> and <parameter>body_cb</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a transfer session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> the URL of the data to get.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> the transfer flags. Valid flags are
<link linkend="ST-TRANSFER-PASS-NEWLINE-CAPS"><type>ST_TRANSFER_PASS_NEWLINE</type></link>, <link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link>,
<link linkend="ST-TRANSFER-PARSE-HTTP-CHARSET-CAPS"><type>ST_TRANSFER_PARSE_HTTP_CHARSET</type></link> and
<link linkend="ST-TRANSFER-PARSE-HTML-CHARSET-CAPS"><type>ST_TRANSFER_PARSE_HTML_CHARSET</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>header_cb</parameter>&nbsp;:</term>
<listitem><simpara> a function to call when a header line arrives, or
<literal>NULL</literal>. The line passed to the function is guaranteed to be valid
ASCII.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>header_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>header_cb</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>body_cb</parameter>&nbsp;:</term>
<listitem><simpara> a function to call when a body line arrives, or <literal>NULL</literal>. If
<link linkend="ST-TRANSFER-UTF8-CAPS"><type>ST_TRANSFER_UTF8</type></link> is used, the line passed to the function is
guaranteed to be valid UTF-8.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>body_data</parameter>&nbsp;:</term>
<listitem><simpara> data to pass to <parameter>body_cb</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> a location to store errors, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>FALSE</literal> if there was an error (in such case, <parameter>err</parameter> will
be set).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-escape"/>st_transfer_escape ()</title>
<indexterm><primary>st_transfer_escape</primary></indexterm><programlisting><link linkend="char">char</link>*       st_transfer_escape              (const <link linkend="char">char</link> *url);</programlisting>
<para>
Escapes unsafe characters of <parameter>url</parameter> using standard percent notation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara> an URL or URL part to escape.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>url</parameter> with unsafe characters escaped. The returned
string must be freed when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-get-full"/>st_transfer_get_full ()</title>
<indexterm><primary>st_transfer_get_full</primary></indexterm><programlisting><link linkend="char">char</link>*       st_transfer_get_full            (const <link linkend="char">char</link> *url,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<warning><para><literal>st_transfer_get_full</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-get-lines"/>st_transfer_get_lines ()</title>
<indexterm><primary>st_transfer_get_lines</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_transfer_get_lines           (const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<warning><para><literal>st_transfer_get_lines</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cb</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-get-full-with-session"/>st_transfer_get_full_with_session ()</title>
<indexterm><primary>st_transfer_get_full_with_session</primary></indexterm><programlisting><link linkend="char">char</link>*       st_transfer_get_full_with_session
                                            (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<warning><para><literal>st_transfer_get_full_with_session</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-transfer-get-lines-with-session"/>st_transfer_get_lines_with_session ()</title>
<indexterm><primary>st_transfer_get_lines_with_session</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_transfer_get_lines_with_session
                                            (<link linkend="STTransferSession">STTransferSession</link> *session,
                                             const <link linkend="char">char</link> *url,
                                             <link linkend="STTransferLineCallback">STTransferLineCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GError">GError</link> **err);</programlisting>
<warning><para><literal>st_transfer_get_lines_with_session</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>url</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cb</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<link linkend="streamtuner-st-sgml-ref-api">st-sgml-ref</link>
</para>
</refsect1>

</refentry>
