<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>st-transfer</title><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"><link rel="start" href="index.html" title="streamtuner Developers Manual"><link rel="up" href="api-reference.html" title="API Reference"><link rel="prev" href="streamtuner-st-stream-api.html" title="STStream"><link rel="next" href="streamtuner-st-util-api.html" title="st-util"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><style type="text/css"> .synopsis, .classsynopsis { background: #eeeeee; border: solid 1px #aaaaaa; padding: 0.5em; } .programlisting { background: #feffde; border: solid 1px #e9ed1c; padding: 0.5em; } .variablelist { padding: 4px; margin-left: 3em; } .navigation { background: #daffd1; border: solid 1px #74ff54; margin-top: 0.5em; margin-bottom: 0.5em; } .navigation a { color: #2fba0f; } .navigation a:visited { color: #22850b; } .navigation .title { font-size: 200%; } </style></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="streamtuner-st-stream-api.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="api-reference.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">streamtuner Developers Manual</th><td><a accesskey="n" href="streamtuner-st-util-api.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="streamtuner-st-transfer-api"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">st-transfer</span></h2><p>st-transfer — functions for transferring data over the network.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> struct <a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a>; enum <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a>; void (<a href="streamtuner-st-transfer-api.html#STTransferLineCallback">*STTransferLineCallback</a>) (const char *line, gpointer data); <a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a>* <a href="streamtuner-st-transfer-api.html#st-transfer-session-new">st_transfer_session_new</a> (void); void <a href="streamtuner-st-transfer-api.html#st-transfer-session-free">st_transfer_session_free</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session); gboolean <a href="streamtuner-st-transfer-api.html#st-transfer-session-get">st_transfer_session_get</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, char **headers, char **body, GError **err); gboolean <a href="streamtuner-st-transfer-api.html#st-transfer-session-get-binary">st_transfer_session_get_binary</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, char **headers, guint8 **body, unsigned int *body_len, GError **err); gboolean <a href="streamtuner-st-transfer-api.html#st-transfer-session-get-by-line">st_transfer_session_get_by_line</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> header_cb, gpointer header_data, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> body_cb, gpointer body_data, GError **err); char* <a href="streamtuner-st-transfer-api.html#st-transfer-escape">st_transfer_escape</a> (const char *url); char* <a href="streamtuner-st-transfer-api.html#st-transfer-get-full">st_transfer_get_full</a> (const char *url, GError **err); gboolean <a href="streamtuner-st-transfer-api.html#st-transfer-get-lines">st_transfer_get_lines</a> (const char *url, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> cb, gpointer data, GError **err); char* <a href="streamtuner-st-transfer-api.html#st-transfer-get-full-with-session">st_transfer_get_full_with_session</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, GError **err); gboolean <a href="streamtuner-st-transfer-api.html#st-transfer-get-lines-with-session">st_transfer_get_lines_with_session</a> (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> cb, gpointer data, GError **err); </pre></div><div class="refsect1" lang="en"><a name="id2632212"></a><h2>Description</h2><p> </p></div><div class="refsect1" lang="en"><a name="id2632221"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2632227"></a><h3><a name="STTransferSession"></a>struct STTransferSession</h3><a class="indexterm" name="id2632235"></a><pre class="programlisting">struct STTransferSession;</pre><p> </p></div><hr><div class="refsect2" lang="en"><a name="id2632249"></a><h3><a name="STTransferFlags"></a>enum STTransferFlags</h3><a class="indexterm" name="id2632258"></a><pre class="programlisting">typedef enum { ST_TRANSFER_PASS_NEWLINE = 1 << 0, ST_TRANSFER_UTF8 = 1 << 1, ST_TRANSFER_PARSE_HTTP_CHARSET = 1 << 2, ST_TRANSFER_PARSE_HTML_CHARSET = 1 << 3 } STTransferFlags; </pre><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><tt class="literal">ST_TRANSFER_PASS_NEWLINE</tt></span></td><td>specifies that the line terminator should be included in the line passed to <a href="streamtuner-st-transfer-api.html#STTransferLineCallback"><tt class="function">STTransferLineCallback()</tt></a>. </td></tr><tr><td><span class="term"><tt class="literal">ST_TRANSFER_UTF8</tt></span></td><td>specifies that <a href="streamtuner-st-transfer-api.html#st-transfer-session-get"><tt class="function">st_transfer_session_get()</tt></a> should fail if the body cannot be converted to UTF-8, and that <a href="streamtuner-st-transfer-api.html#st-transfer-session-get-by-line"><tt class="function">st_transfer_session_get_by_line()</tt></a> should skip the body lines which cannot be converted to UTF-8. </td></tr><tr><td><span class="term"><tt class="literal">ST_TRANSFER_PARSE_HTTP_CHARSET</tt></span></td><td>specifies that charset information should be extracted from the HTTP Content-Type header, if present. To be used along with <span class="type">ST_TRANSFER_UTF8</span>. </td></tr><tr><td><span class="term"><tt class="literal">ST_TRANSFER_PARSE_HTML_CHARSET</tt></span></td><td>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 <span class="type">ST_TRANSFER_UTF8</span>. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2632371"></a><h3><a name="STTransferLineCallback"></a>STTransferLineCallback ()</h3><a class="indexterm" name="id2632379"></a><pre class="programlisting">void (*STTransferLineCallback) (const char *line, gpointer data);</pre><p> Specifies the type of function to pass to <a href="streamtuner-st-transfer-api.html#st-transfer-session-get-by-line"><tt class="function">st_transfer_session_get_by_line()</tt></a>. </p><p> The function will be called whenever a line has been transferred.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>line</tt></i> :</span></td><td> a line. If <span class="type">ST_TRANSFER_PASS_NEWLINE</span> was used, the line terminator is included. If <span class="type">ST_TRANSFER_UTF8</span> was used, the line is valid UTF-8. </td></tr><tr><td><span class="term"><i class="parameter"><tt>data</tt></i> :</span></td><td> data pointer passed to <a href="streamtuner-st-transfer-api.html#st-transfer-session-get-by-line"><tt class="function">st_transfer_session_get_by_line()</tt></a>. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2632550"></a><h3><a name="st-transfer-session-new"></a>st_transfer_session_new ()</h3><a class="indexterm" name="id2632558"></a><pre class="programlisting"><a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a>* st_transfer_session_new (void);</pre><p> Creates a new transfer session.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the new session, which should be freed with <a href="streamtuner-st-transfer-api.html#st-transfer-session-free"><tt class="function">st_transfer_session_free()</tt></a> when no longer needed. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2632605"></a><h3><a name="st-transfer-session-free"></a>st_transfer_session_free ()</h3><a class="indexterm" name="id2632614"></a><pre class="programlisting">void st_transfer_session_free (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session);</pre><p> Destroys <i class="parameter"><tt>session</tt></i>.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> the transfer session to destroy. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2632665"></a><h3><a name="st-transfer-session-get"></a>st_transfer_session_get ()</h3><a class="indexterm" name="id2632674"></a><pre class="programlisting">gboolean st_transfer_session_get (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, char **headers, char **body, GError **err);</pre><p> Gets the data located at <i class="parameter"><tt>url</tt></i>.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> a transfer session. </td></tr><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> the URL of the data to get. </td></tr><tr><td><span class="term"><i class="parameter"><tt>flags</tt></i> :</span></td><td> the transfer flags. Valid flags are <span class="type">ST_TRANSFER_UTF8</span>, <span class="type">ST_TRANSFER_PARSE_HTTP_CHARSET</span> and <span class="type">ST_TRANSFER_PARSE_HTML_CHARSET</span>. </td></tr><tr><td><span class="term"><i class="parameter"><tt>headers</tt></i> :</span></td><td> a location to return the header data, or <tt class="literal">NULL</tt>. The returned data is guaranteed to be valid ASCII. </td></tr><tr><td><span class="term"><i class="parameter"><tt>body</tt></i> :</span></td><td> a location to return the body data, or <tt class="literal">NULL</tt>. If <span class="type">ST_TRANSFER_UTF8</span> is used, the returned data is guaranteed to be valid UTF-8. </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> a location to store errors, or <tt class="literal">NULL</tt>. </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> <tt class="literal">FALSE</tt> if there was an error (in such case, <i class="parameter"><tt>err</tt></i> will be set). If <tt class="literal">TRUE</tt> is returned, strings will be stored at <i class="parameter"><tt>headers</tt></i> and <i class="parameter"><tt>body</tt></i>. They should be freed when no longer needed. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2632914"></a><h3><a name="st-transfer-session-get-binary"></a>st_transfer_session_get_binary ()</h3><a class="indexterm" name="id2632923"></a><pre class="programlisting">gboolean st_transfer_session_get_binary (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, char **headers, guint8 **body, unsigned int *body_len, GError **err);</pre><p> Gets the binary data located at <i class="parameter"><tt>url</tt></i>.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> a transfer session. </td></tr><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> the URL of the data to get. </td></tr><tr><td><span class="term"><i class="parameter"><tt>flags</tt></i> :</span></td><td> must be 0. </td></tr><tr><td><span class="term"><i class="parameter"><tt>headers</tt></i> :</span></td><td> a location to return the header data, or <tt class="literal">NULL</tt>. The returned data is guaranteed to be valid ASCII. </td></tr><tr><td><span class="term"><i class="parameter"><tt>body</tt></i> :</span></td><td> a location to return the body data, or <tt class="literal">NULL</tt>. If set, <i class="parameter"><tt>body_len</tt></i> must also be set. </td></tr><tr><td><span class="term"><i class="parameter"><tt>body_len</tt></i> :</span></td><td> a location to return the body length, or <tt class="literal">NULL</tt>. </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> a location to store errors, or <tt class="literal">NULL</tt>. </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> <tt class="literal">FALSE</tt> if there was an error (in such case, <i class="parameter"><tt>err</tt></i> will be set). If <tt class="literal">TRUE</tt> is returned, a string will be stored at <i class="parameter"><tt>headers</tt></i> and a character buffer will be stored at <i class="parameter"><tt>body</tt></i>. They both should be freed when no longer needed. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633162"></a><h3><a name="st-transfer-session-get-by-line"></a>st_transfer_session_get_by_line ()</h3><a class="indexterm" name="id2633172"></a><pre class="programlisting">gboolean st_transfer_session_get_by_line (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferFlags">STTransferFlags</a> flags, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> header_cb, gpointer header_data, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> body_cb, gpointer body_data, GError **err);</pre><p> Gets the data located at <i class="parameter"><tt>url</tt></i>, splitting it into lines and passing them to <i class="parameter"><tt>header_cb</tt></i> and <i class="parameter"><tt>body_cb</tt></i>.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> a transfer session. </td></tr><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> the URL of the data to get. </td></tr><tr><td><span class="term"><i class="parameter"><tt>flags</tt></i> :</span></td><td> the transfer flags. Valid flags are <span class="type">ST_TRANSFER_PASS_NEWLINE</span>, <span class="type">ST_TRANSFER_UTF8</span>, <span class="type">ST_TRANSFER_PARSE_HTTP_CHARSET</span> and <span class="type">ST_TRANSFER_PARSE_HTML_CHARSET</span>. </td></tr><tr><td><span class="term"><i class="parameter"><tt>header_cb</tt></i> :</span></td><td> a function to call when a header line arrives, or <tt class="literal">NULL</tt>. The line passed to the function is guaranteed to be valid ASCII. </td></tr><tr><td><span class="term"><i class="parameter"><tt>header_data</tt></i> :</span></td><td> data to pass to <i class="parameter"><tt>header_cb</tt></i>. </td></tr><tr><td><span class="term"><i class="parameter"><tt>body_cb</tt></i> :</span></td><td> a function to call when a body line arrives, or <tt class="literal">NULL</tt>. If <span class="type">ST_TRANSFER_UTF8</span> is used, the line passed to the function is guaranteed to be valid UTF-8. </td></tr><tr><td><span class="term"><i class="parameter"><tt>body_data</tt></i> :</span></td><td> data to pass to <i class="parameter"><tt>body_cb</tt></i>. </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> a location to store errors, or <tt class="literal">NULL</tt>. </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> <tt class="literal">FALSE</tt> if there was an error (in such case, <i class="parameter"><tt>err</tt></i> will be set). </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633593"></a><h3><a name="st-transfer-escape"></a>st_transfer_escape ()</h3><a class="indexterm" name="id2633602"></a><pre class="programlisting">char* st_transfer_escape (const char *url);</pre><p> Escapes unsafe characters of <i class="parameter"><tt>url</tt></i> using standard percent notation.</p><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> an URL or URL part to escape. </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> <i class="parameter"><tt>url</tt></i> with unsafe characters escaped. The returned string must be freed when no longer needed. </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633668"></a><h3><a name="st-transfer-get-full"></a>st_transfer_get_full ()</h3><a class="indexterm" name="id2633676"></a><pre class="programlisting">char* st_transfer_get_full (const char *url, GError **err);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">st_transfer_get_full</tt> is deprecated and should not be used in newly-written code.</p></div><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633756"></a><h3><a name="st-transfer-get-lines"></a>st_transfer_get_lines ()</h3><a class="indexterm" name="id2633765"></a><pre class="programlisting">gboolean st_transfer_get_lines (const char *url, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> cb, gpointer data, GError **err);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">st_transfer_get_lines</tt> is deprecated and should not be used in newly-written code.</p></div><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>cb</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>data</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633883"></a><h3><a name="st-transfer-get-full-with-session"></a>st_transfer_get_full_with_session ()</h3><a class="indexterm" name="id2633896"></a><pre class="programlisting">char* st_transfer_get_full_with_session (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, GError **err);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">st_transfer_get_full_with_session</tt> is deprecated and should not be used in newly-written code.</p></div><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> </td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2633996"></a><h3><a name="st-transfer-get-lines-with-session"></a>st_transfer_get_lines_with_session ()</h3><a class="indexterm" name="id2634009"></a><pre class="programlisting">gboolean st_transfer_get_lines_with_session (<a href="streamtuner-st-transfer-api.html#STTransferSession">STTransferSession</a> *session, const char *url, <a href="streamtuner-st-transfer-api.html#STTransferLineCallback">STTransferLineCallback</a> cb, gpointer data, GError **err);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">st_transfer_get_lines_with_session</tt> is deprecated and should not be used in newly-written code.</p></div><p> </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>session</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>url</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>cb</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>data</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> </td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id2634149"></a><h2>See Also</h2><p> <a href="streamtuner-st-sgml-ref-api.html" title="st-sgml-ref">st-sgml-ref</a> </p></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="streamtuner-st-stream-api.html"><b><< STStream</b></a></td><td align="right"><a accesskey="n" href="streamtuner-st-util-api.html"><b>st-util >></b></a></td></tr></table></body></html>