<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="raptor-section-www">
<refmeta>
<refentrytitle role="top_of_page" id="raptor-section-www.top_of_page">WWW</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RAPTOR Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>WWW</refname>
<refpurpose>Retrieval of URI content from the web.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="raptor-section-www.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
typedef             <link linkend="raptor-www">raptor_www</link>;
<link linkend="void">void</link>                <link linkend="raptor-www-init">raptor_www_init</link>                     (void);
<link linkend="void">void</link>                <link linkend="raptor-www-finish">raptor_www_finish</link>                   (void);
<link linkend="void">void</link>                (<link linkend="raptor-www-write-bytes-handler">*raptor_www_write_bytes_handler</link>)   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         const <link linkend="void">void</link> *ptr,
                                                         <link linkend="size-t">size_t</link> size,
                                                         <link linkend="size-t">size_t</link> nmemb);
<link linkend="void">void</link>                (<link linkend="raptor-www-content-type-handler">*raptor_www_content_type_handler</link>)  (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         const <link linkend="char">char</link> *content_type);
<link linkend="void">void</link>                <link linkend="raptor-www-no-www-library-init-finish">raptor_www_no_www_library_init_finish</link>
                                                        (void);
<link linkend="raptor-www">raptor_www</link>*         <link linkend="raptor-www-new">raptor_www_new</link>                      (void);
<link linkend="raptor-www">raptor_www</link>*         <link linkend="raptor-www-new-with-connection">raptor_www_new_with_connection</link>      (<link linkend="void">void</link> *connection);
<link linkend="void">void</link>                <link linkend="raptor-www-free">raptor_www_free</link>                     (<link linkend="raptor-www">raptor_www</link> *www);
<link linkend="void">void</link>                <link linkend="raptor-www-set-user-agent">raptor_www_set_user_agent</link>           (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *user_agent);
<link linkend="void">void</link>                <link linkend="raptor-www-set-proxy">raptor_www_set_proxy</link>                (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *proxy);
<link linkend="void">void</link>                <link linkend="raptor-www-set-http-accept">raptor_www_set_http_accept</link>          (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *value);
<link linkend="int">int</link>                 <link linkend="raptor-www-set-http-cache-control">raptor_www_set_http_cache_control</link>   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *cache_control);
<link linkend="void">void</link>                <link linkend="raptor-www-set-write-bytes-handler">raptor_www_set_write_bytes_handler</link>  (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-write-bytes-handler">raptor_www_write_bytes_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);
<link linkend="void">void</link>                <link linkend="raptor-www-set-connection-timeout">raptor_www_set_connection_timeout</link>   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="int">int</link> timeout);
<link linkend="void">void</link>                <link linkend="raptor-www-set-content-type-handler">raptor_www_set_content_type_handler</link> (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-content-type-handler">raptor_www_content_type_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);
<link linkend="void">void</link>                <link linkend="raptor-www-set-error-handler">raptor_www_set_error_handler</link>        (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-message-handler">raptor_message_handler</link> error_handler,
                                                         <link linkend="void">void</link> *error_data);
<link linkend="int">int</link>                 (<link linkend="raptor-uri-filter-func">*raptor_uri_filter_func</link>)           (<link linkend="void">void</link> *user_data,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="void">void</link>                <link linkend="raptor-www-set-uri-filter">raptor_www_set_uri_filter</link>           (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri-filter-func">raptor_uri_filter_func</link> filter,
                                                         <link linkend="void">void</link> *user_data);
<link linkend="void">void</link>                (<link linkend="raptor-www-final-uri-handler">*raptor_www_final_uri_handler</link>)     (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         <link linkend="raptor-uri">raptor_uri</link> *final_uri);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-www-get-final-uri">raptor_www_get_final_uri</link>            (<link linkend="raptor-www">raptor_www</link> *www);
<link linkend="void">void</link>                <link linkend="raptor-www-set-final-uri-handler">raptor_www_set_final_uri_handler</link>    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-final-uri-handler">raptor_www_final_uri_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);
<link linkend="int">int</link>                 <link linkend="raptor-www-fetch">raptor_www_fetch</link>                    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="int">int</link>                 <link linkend="raptor-www-fetch-to-string">raptor_www_fetch_to_string</link>          (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="void">void</link> **string_p,
                                                         <link linkend="size-t">size_t</link> *length_p,
                                                         <link linkend="void">void</link>* (malloc_handlersize_t size) ());
<link linkend="void">void</link>*               <link linkend="raptor-www-get-connection">raptor_www_get_connection</link>           (<link linkend="raptor-www">raptor_www</link> *www);
<link linkend="void">void</link>                <link linkend="raptor-www-abort">raptor_www_abort</link>                    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *reason);
</synopsis>
</refsynopsisdiv>









<refsect1 id="raptor-section-www.description" role="desc">
<title role="desc.title">Description</title>
<para>
Provides a wrapper to the resolution of URIs to give content
using an underlying WWW-retrieval library.  The content is
delivered by callbacks and includes returning content type
for handling content-negotation by the caller as well as
chunks of byte content.
</para>
</refsect1>

<refsect1 id="raptor-section-www.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="raptor-www" role="typedef">
<title>raptor_www</title>
<indexterm zone="raptor-www"><primary>raptor_www</primary></indexterm><programlisting>raptor_www* raptor_www;
</programlisting>
<para>
Raptor WWW class</para>
<para>

</para></refsect2>
<refsect2 id="raptor-www-init" role="function">
<title>raptor_www_init ()</title>
<indexterm zone="raptor-www-init"><primary>raptor_www_init</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_init                     (void);</programlisting>
<para>
Initialise the WWW class.
</para>
<para>
Must be called before creating any <link linkend="raptor-www"><type>raptor_www</type></link> object.</para>
<para>

</para></refsect2>
<refsect2 id="raptor-www-finish" role="function">
<title>raptor_www_finish ()</title>
<indexterm zone="raptor-www-finish"><primary>raptor_www_finish</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_finish                   (void);</programlisting>
<para>
Terminate the WWW class.
</para>
<para>
Must be called to clean any resources used by the WWW implementation.</para>
<para>

</para></refsect2>
<refsect2 id="raptor-www-write-bytes-handler" role="function">
<title>raptor_www_write_bytes_handler ()</title>
<indexterm zone="raptor-www-write-bytes-handler"><primary>raptor_www_write_bytes_handler</primary></indexterm><programlisting><link linkend="void">void</link>                (*raptor_www_write_bytes_handler)   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         const <link linkend="void">void</link> *ptr,
                                                         <link linkend="size-t">size_t</link> size,
                                                         <link linkend="size-t">size_t</link> nmemb);</programlisting>
<para>
Receiving bytes of data from WWW retrieval handler.
</para>
<para>
Set by <link linkend="raptor-www-set-write-bytes-handler"><function>raptor_www_set_write_bytes_handler()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>userdata</parameter>&nbsp;:</term>
<listitem><simpara> user data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ptr</parameter>&nbsp;:</term>
<listitem><simpara> data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> size of individual item
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nmemb</parameter>&nbsp;:</term>
<listitem><simpara> number of items
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-content-type-handler" role="function">
<title>raptor_www_content_type_handler ()</title>
<indexterm zone="raptor-www-content-type-handler"><primary>raptor_www_content_type_handler</primary></indexterm><programlisting><link linkend="void">void</link>                (*raptor_www_content_type_handler)  (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         const <link linkend="char">char</link> *content_type);</programlisting>
<para>
Receiving Content-Type: header from WWW retrieval handler.
</para>
<para>
Set by <link linkend="raptor-www-set-content-type-handler"><function>raptor_www_set_content_type_handler()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>userdata</parameter>&nbsp;:</term>
<listitem><simpara> user data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>content_type</parameter>&nbsp;:</term>
<listitem><simpara> content type seen
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-no-www-library-init-finish" role="function">
<title>raptor_www_no_www_library_init_finish ()</title>
<indexterm zone="raptor-www-no-www-library-init-finish"><primary>raptor_www_no_www_library_init_finish</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_no_www_library_init_finish
                                                        (void);</programlisting>
<para>
Do not initialise or finish the lower level WWW library.
</para>
<para>
If this is called then the raptor_www library will neither
initialise or terminate the lower level WWW library.  Usually in
raptor_init either curl_global_init (for libcurl)
are called and in raptor_finish curl_global_cleanup is called.
</para>
<para>
This allows the application finer control over these libraries such
as setting other global options or potentially calling and terminating
raptor several times.  It does mean that applications which use
this call must do their own extra work in order to allocate and free
all resources to the system.
</para>
<para>
This function must be called before raptor_init.</para>
<para>

</para></refsect2>
<refsect2 id="raptor-www-new" role="function">
<title>raptor_www_new ()</title>
<indexterm zone="raptor-www-new"><primary>raptor_www_new</primary></indexterm><programlisting><link linkend="raptor-www">raptor_www</link>*         raptor_www_new                      (void);</programlisting>
<para>
Constructor - create a new <link linkend="raptor-www"><type>raptor_www</type></link> object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-www"><type>raptor_www</type></link> or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-new-with-connection" role="function">
<title>raptor_www_new_with_connection ()</title>
<indexterm zone="raptor-www-new-with-connection"><primary>raptor_www_new_with_connection</primary></indexterm><programlisting><link linkend="raptor-www">raptor_www</link>*         raptor_www_new_with_connection      (<link linkend="void">void</link> *connection);</programlisting>
<para>
Constructor - create a new <link linkend="raptor-www"><type>raptor_www</type></link> object over an existing WWW connection.
</para>
<para>
At present this only works with a libcurl CURL handle object
when raptor is compiled with libcurl suppport. Otherwise the
<parameter>connection</parameter> is ignored.  This allows such things as setting
up special flags on the curl handle before passing into the constructor.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>connection</parameter>&nbsp;:</term>
<listitem><simpara> external WWW connection object.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-www"><type>raptor_www</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-free" role="function">
<title>raptor_www_free ()</title>
<indexterm zone="raptor-www-free"><primary>raptor_www_free</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_free                     (<link linkend="raptor-www">raptor_www</link> *www);</programlisting>
<para>
Destructor - destroy a <link linkend="raptor-www"><type>raptor_www</type></link> object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-user-agent" role="function">
<title>raptor_www_set_user_agent ()</title>
<indexterm zone="raptor-www-set-user-agent"><primary>raptor_www_set_user_agent</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_user_agent           (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *user_agent);</programlisting>
<para>
Set the user agent value, for HTTP requests typically.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_agent</parameter>&nbsp;:</term>
<listitem><simpara> User-Agent string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-proxy" role="function">
<title>raptor_www_set_proxy ()</title>
<indexterm zone="raptor-www-set-proxy"><primary>raptor_www_set_proxy</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_proxy                (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *proxy);</programlisting>
<para>
Set the proxy for the WWW object.
</para>
<para>
The <parameter>proxy</parameter> usually a string of the form http://server.domain:port.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>proxy</parameter>&nbsp;:</term>
<listitem><simpara> proxy string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-http-accept" role="function">
<title>raptor_www_set_http_accept ()</title>
<indexterm zone="raptor-www-set-http-accept"><primary>raptor_www_set_http_accept</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_http_accept          (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *value);</programlisting>
<para>
Set HTTP Accept header.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-www"><type>raptor_www</type></link> class
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> Accept: header value or NULL to have an empty one.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-http-cache-control" role="function">
<title>raptor_www_set_http_cache_control ()</title>
<indexterm zone="raptor-www-set-http-cache-control"><primary>raptor_www_set_http_cache_control</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_www_set_http_cache_control   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *cache_control);</programlisting>
<para>
Set HTTP Cache-Control:header (default none)
</para>
<para>
The <parameter>cache_control</parameter> value can be a string to set it, "" to send
a blank header or NULL to not set the header at all.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cache_control</parameter>&nbsp;:</term>
<listitem><simpara> Cache-Control header value (or NULL to disable)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-write-bytes-handler" role="function">
<title>raptor_www_set_write_bytes_handler ()</title>
<indexterm zone="raptor-www-set-write-bytes-handler"><primary>raptor_www_set_write_bytes_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_write_bytes_handler  (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-write-bytes-handler">raptor_www_write_bytes_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);</programlisting>
<para>
Set the handler to receive bytes written by the <link linkend="raptor-www"><type>raptor_www</type></link> implementation.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> bytes handler function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> bytes handler data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-connection-timeout" role="function">
<title>raptor_www_set_connection_timeout ()</title>
<indexterm zone="raptor-www-set-connection-timeout"><primary>raptor_www_set_connection_timeout</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_connection_timeout   (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="int">int</link> timeout);</programlisting>
<para>
Set WWW connection timeout</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>timeout</parameter>&nbsp;:</term>
<listitem><simpara> Timeout in seconds
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-content-type-handler" role="function">
<title>raptor_www_set_content_type_handler ()</title>
<indexterm zone="raptor-www-set-content-type-handler"><primary>raptor_www_set_content_type_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_content_type_handler (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-content-type-handler">raptor_www_content_type_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);</programlisting>
<para>
Set the handler to receive the HTTP Content-Type header value.
</para>
<para>
This is called if or when the value is discovered during retrieval
by the raptor_www implementation.  Not all implementations provide
access to this.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> content type handler function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> content type handler data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-error-handler" role="function">
<title>raptor_www_set_error_handler ()</title>
<indexterm zone="raptor-www-set-error-handler"><primary>raptor_www_set_error_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_error_handler        (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-message-handler">raptor_message_handler</link> error_handler,
                                                         <link linkend="void">void</link> *error_data);</programlisting>
<para>
Set the error handler routine for the raptor_www class.
</para>
<para>
This takes the same arguments as the <link linkend="raptor-parser-set-error"><function>raptor_parser_set_error()</function></link> and
<link linkend="raptor-parser-set-warning-handler"><function>raptor_parser_set_warning_handler()</function></link> methods.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error_handler</parameter>&nbsp;:</term>
<listitem><simpara> error handler function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error_data</parameter>&nbsp;:</term>
<listitem><simpara> error handler data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-filter-func" role="function">
<title>raptor_uri_filter_func ()</title>
<indexterm zone="raptor-uri-filter-func"><primary>raptor_uri_filter_func</primary></indexterm><programlisting><link linkend="int">int</link>                 (*raptor_uri_filter_func)           (<link linkend="void">void</link> *user_data,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Callback function for <link linkend="raptor-www-set-uri-filter"><type>raptor_www_set_uri_filter</type></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> user data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-uri"><type>raptor_uri</type></link> URI to check
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 to filter the URI
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-uri-filter" role="function">
<title>raptor_www_set_uri_filter ()</title>
<indexterm zone="raptor-www-set-uri-filter"><primary>raptor_www_set_uri_filter</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_uri_filter           (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri-filter-func">raptor_uri_filter_func</link> filter,
                                                         <link linkend="void">void</link> *user_data);</programlisting>
<para>
Set URI filter function for WWW retrieval.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>filter</parameter>&nbsp;:</term>
<listitem><simpara> URI filter function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> User data to pass to filter function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-final-uri-handler" role="function">
<title>raptor_www_final_uri_handler ()</title>
<indexterm zone="raptor-www-final-uri-handler"><primary>raptor_www_final_uri_handler</primary></indexterm><programlisting><link linkend="void">void</link>                (*raptor_www_final_uri_handler)     (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="void">void</link> *userdata,
                                                         <link linkend="raptor-uri">raptor_uri</link> *final_uri);</programlisting>
<para>
Receiving the final resolved URI from a WWW retrieval
</para>
<para>
Set by <link linkend="raptor-www-set-final-uri-handler"><function>raptor_www_set_final_uri_handler()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>userdata</parameter>&nbsp;:</term>
<listitem><simpara> user data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>final_uri</parameter>&nbsp;:</term>
<listitem><simpara> final URI seen
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-get-final-uri" role="function">
<title>raptor_www_get_final_uri ()</title>
<indexterm zone="raptor-www-get-final-uri"><primary>raptor_www_get_final_uri</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_www_get_final_uri            (<link linkend="raptor-www">raptor_www</link> *www);</programlisting>
<para>
Get the WWW final resolved URI.
</para>
<para>
This returns the URI used after any protocol redirection.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-www"><type>raptor_www</type></link> object 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new URI or NULL if not known.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-set-final-uri-handler" role="function">
<title>raptor_www_set_final_uri_handler ()</title>
<indexterm zone="raptor-www-set-final-uri-handler"><primary>raptor_www_set_final_uri_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_set_final_uri_handler    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-www-final-uri-handler">raptor_www_final_uri_handler</link> handler,
                                                         <link linkend="void">void</link> *user_data);</programlisting>
<para>
Set the handler to receive the HTTP Content-Type header value.
</para>
<para>
This is called if or when the value is discovered during retrieval
by the raptor_www implementation.  Not all implementations provide
access to this.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> content type handler function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> content type handler data
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-fetch" role="function">
<title>raptor_www_fetch ()</title>
<indexterm zone="raptor-www-fetch"><primary>raptor_www_fetch</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_www_fetch                    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Start a WWW content retrieval for the given URI, returning data via the write_bytes handler.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI to read from
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-fetch-to-string" role="function">
<title>raptor_www_fetch_to_string ()</title>
<indexterm zone="raptor-www-fetch-to-string"><primary>raptor_www_fetch_to_string</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_www_fetch_to_string          (<link linkend="raptor-www">raptor_www</link> *www,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="void">void</link> **string_p,
                                                         <link linkend="size-t">size_t</link> *length_p,
                                                         <link linkend="void">void</link>* (malloc_handlersize_t size) ());</programlisting>
<para>
Start a WWW content retrieval for the given URI, returning the data in a new string.
</para>
<para>
If malloc_handler is null, raptor will allocate it using it's
own memory allocator.  *string_p is set to NULL on failure (and
*length_p to 0 if length_p is not NULL).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> raptor_www object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> raptor_uri to retrieve
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string_p</parameter>&nbsp;:</term>
<listitem><simpara> pointer to location to hold string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length_p</parameter>&nbsp;:</term>
<listitem><simpara> pointer to location to hold length of string (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>malloc_handler</parameter>&nbsp;:</term>
<listitem><simpara> pointer to malloc to use to make string (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-get-connection" role="function">
<title>raptor_www_get_connection ()</title>
<indexterm zone="raptor-www-get-connection"><primary>raptor_www_get_connection</primary></indexterm><programlisting><link linkend="void">void</link>*               raptor_www_get_connection           (<link linkend="raptor-www">raptor_www</link> *www);</programlisting>
<para>
Get WWW library connection object.
</para>
<para>
Return the internal WWW connection handle.  For libcurl, this
returns the CURL handle and for libxml the context.  Otherwise
it returns NULL.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-www"><type>raptor_www</type></link> object 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> connection pointer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-www-abort" role="function">
<title>raptor_www_abort ()</title>
<indexterm zone="raptor-www-abort"><primary>raptor_www_abort</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_www_abort                    (<link linkend="raptor-www">raptor_www</link> *www,
                                                         const <link linkend="char">char</link> *reason);</programlisting>
<para>
Abort an ongoing raptor WWW operation and pass back a reason.
</para>
<para>
This is typically used within one of the raptor WWW handlers
when retrieval need no longer continue due to another
processing issue or error.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>www</parameter>&nbsp;:</term>
<listitem><simpara> WWW object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reason</parameter>&nbsp;:</term>
<listitem><simpara> abort reason message
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
