<?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-uri">
<refmeta>
<refentrytitle role="top_of_page" id="raptor-section-uri.top_of_page">URI</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RAPTOR Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>URI</refname>
<refpurpose>URI class and relative URI computation</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>
typedef             <link linkend="raptor-uri">raptor_uri</link>;
                    <link linkend="raptor-uri-handler">raptor_uri_handler</link>;
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri">raptor_new_uri</link>                      (unsigned <link linkend="char">char</link> *uri_string);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-from-uri-local-name">raptor_new_uri_from_uri_local_name</link>  (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         unsigned <link linkend="char">char</link> *local_name);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-relative-to-base">raptor_new_uri_relative_to_base</link>     (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *uri_string);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-from-id">raptor_new_uri_from_id</link>              (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *id);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-for-rdf-concept">raptor_new_uri_for_rdf_concept</link>      (const <link linkend="char">char</link> *name);
<link linkend="void">void</link>                <link linkend="raptor-free-uri">raptor_free_uri</link>                     (<link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="int">int</link>                 <link linkend="raptor-uri-compare">raptor_uri_compare</link>                  (<link linkend="raptor-uri">raptor_uri</link> *uri1,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri2);
<link linkend="int">int</link>                 <link linkend="raptor-uri-equals">raptor_uri_equals</link>                   (<link linkend="raptor-uri">raptor_uri</link> *uri1,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri2);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-uri-copy">raptor_uri_copy</link>                     (<link linkend="raptor-uri">raptor_uri</link> *uri);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-as-string">raptor_uri_as_string</link>                (<link linkend="raptor-uri">raptor_uri</link> *uri);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-as-counted-string">raptor_uri_as_counted_string</link>        (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="size-t">size_t</link> *len_p);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-for-xmlbase">raptor_new_uri_for_xmlbase</link>          (<link linkend="raptor-uri">raptor_uri</link> *old_uri);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="raptor-new-uri-for-retrieval">raptor_new_uri_for_retrieval</link>        (<link linkend="raptor-uri">raptor_uri</link> *old_uri);
<link linkend="void">void</link>                <link linkend="raptor-uri-resolve-uri-reference">raptor_uri_resolve_uri_reference</link>    (unsigned <link linkend="char">char</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *reference_uri,
                                                         unsigned <link linkend="char">char</link> *buffer,
                                                         <link linkend="size-t">size_t</link> length);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-filename-to-uri-string">raptor_uri_filename_to_uri_string</link>   (const <link linkend="char">char</link> *filename);
<link linkend="char">char</link>*               <link linkend="raptor-uri-uri-string-to-filename">raptor_uri_uri_string_to_filename</link>   (unsigned <link linkend="char">char</link> *uri_string);
<link linkend="char">char</link>*               <link linkend="raptor-uri-uri-string-to-filename-fragment">raptor_uri_uri_string_to_filename_fragment</link>
                                                        (unsigned <link linkend="char">char</link> *uri_string,
                                                         unsigned <link linkend="char">char</link> **fragment_p);
<link linkend="int">int</link>                 <link linkend="raptor-uri-uri-string-is-file-uri">raptor_uri_uri_string_is_file_uri</link>   (unsigned <link linkend="char">char</link> *uri_string);
<link linkend="int">int</link>                 <link linkend="raptor-uri-is-file-uri">raptor_uri_is_file_uri</link>              (unsigned <link linkend="char">char</link> *uri_string);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-to-relative-counted-uri-string">raptor_uri_to_relative_counted_uri_string</link>
                                                        (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         <link linkend="raptor-uri">raptor_uri</link> *reference_uri,
                                                         <link linkend="size-t">size_t</link> *length_p);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-to-relative-uri-string">raptor_uri_to_relative_uri_string</link>   (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         <link linkend="raptor-uri">raptor_uri</link> *reference_uri);
<link linkend="void">void</link>                <link linkend="raptor-uri-print">raptor_uri_print</link>                    (const <link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="FILE:CAPS">FILE</link> *stream);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-to-counted-string">raptor_uri_to_counted_string</link>        (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="size-t">size_t</link> *len_p);
unsigned <link linkend="char">char</link>*      <link linkend="raptor-uri-to-string">raptor_uri_to_string</link>                (<link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="void">void</link>                <link linkend="raptor-uri-set-handler">raptor_uri_set_handler</link>              (const <link linkend="raptor-uri-handler">raptor_uri_handler</link> *handler,
                                                         <link linkend="void">void</link> *context);
<link linkend="void">void</link>                <link linkend="raptor-uri-get-handler">raptor_uri_get_handler</link>              (const <link linkend="raptor-uri-handler">raptor_uri_handler</link> **handler,
                                                         <link linkend="void">void</link> **context);
<link linkend="int">int</link>                 <link linkend="raptor-iostream-write-uri">raptor_iostream_write_uri</link>           (<link linkend="raptor-iostream">raptor_iostream</link> *iostr,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);
</synopsis>
</refsynopsisdiv>









<refsect1 id="raptor-section-uri.description" role="desc">
<title role="desc.title">Description</title>
<para>
A class for absolute URIs used inside raptor and relative URI
computation utility functions used inside the main Redland
<link linkend="librdf-uri"><type>librdf_uri</type></link> class.  Only absolute URIs are provided, with no
current access to internals of URIs such as URI scheme, path, authority.
</para>
</refsect1>

<refsect1 id="raptor-section-uri.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="raptor-uri" role="typedef">
<title>raptor_uri</title>
<indexterm zone="raptor-uri"><primary>raptor_uri</primary></indexterm><programlisting>raptor_uri* raptor_uri;
</programlisting>
<para>
Raptor URI Class.</para>
<para>

</para></refsect2>
<refsect2 id="raptor-uri-handler" role="struct">
<title>raptor_uri_handler</title>
<indexterm zone="raptor-uri-handler"><primary>raptor_uri_handler</primary></indexterm><programlisting>typedef struct {
  /* constructors - URI Interface V1 */
  raptor_new_uri_func                     new_uri;
  raptor_new_uri_from_uri_local_name_func new_uri_from_uri_local_name;
  raptor_new_uri_relative_to_base_func    new_uri_relative_to_base;
  raptor_new_uri_for_rdf_concept_func     new_uri_for_rdf_concept;
  /* destructor - URI Interface V1 */
  raptor_free_uri_func                    free_uri;
  /* methods - URI Interface V1 */
  raptor_uri_equals_func                  uri_equals;
  raptor_uri_copy_func                    uri_copy; /* well, copy constructor */
  raptor_uri_as_string_func               uri_as_string;
  raptor_uri_as_counted_string_func       uri_as_counted_string;
  int initialised;
  /* methods - URI Interface V2 */
  raptor_uri_compare_func                 uri_compare;
} raptor_uri_handler;
</programlisting>
<para>
URI implementation handler structure.</para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="raptor-new-uri-func">raptor_new_uri_func</link>&nbsp;<structfield>new_uri</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-new-uri"><function>raptor_new_uri()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-new-uri-from-uri-local-name-func">raptor_new_uri_from_uri_local_name_func</link>&nbsp;<structfield>new_uri_from_uri_local_name</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-new-uri-from-uri-local-name"><function>raptor_new_uri_from_uri_local_name()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-new-uri-relative-to-base-func">raptor_new_uri_relative_to_base_func</link>&nbsp;<structfield>new_uri_relative_to_base</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-new-uri-relative-to-base"><function>raptor_new_uri_relative_to_base()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-new-uri-for-rdf-concept-func">raptor_new_uri_for_rdf_concept_func</link>&nbsp;<structfield>new_uri_for_rdf_concept</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-new-uri-for-rdf-concept"><function>raptor_new_uri_for_rdf_concept()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-free-uri-func">raptor_free_uri_func</link>&nbsp;<structfield>free_uri</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-free-uri"><function>raptor_free_uri()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-uri-equals-func">raptor_uri_equals_func</link>&nbsp;<structfield>uri_equals</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-uri-equals"><function>raptor_uri_equals()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-uri-copy-func">raptor_uri_copy_func</link>&nbsp;<structfield>uri_copy</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-uri-copy"><function>raptor_uri_copy()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-uri-as-string-func">raptor_uri_as_string_func</link>&nbsp;<structfield>uri_as_string</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-uri-as-string"><function>raptor_uri_as_string()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-uri-as-counted-string-func">raptor_uri_as_counted_string_func</link>&nbsp;<structfield>uri_as_counted_string</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-uri-as-counted-string"><function>raptor_uri_as_counted_string()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="int">int</link>&nbsp;<structfield>initialised</structfield>;</term>
<listitem><simpara> API version - set to API version implemented: 1..2
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="raptor-uri-compare-func">raptor_uri_compare_func</link>&nbsp;<structfield>uri_compare</structfield>;</term>
<listitem><simpara> function for <link linkend="raptor-uri-compare"><function>raptor_uri_compare()</function></link>
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri" role="function">
<title>raptor_new_uri ()</title>
<indexterm zone="raptor-new-uri"><primary>raptor_new_uri</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri                      (unsigned <link linkend="char">char</link> *uri_string);</programlisting>
<para>
Constructor - create a raptor URI from a UTF-8 encoded Unicode string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> URI string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-from-uri-local-name" role="function">
<title>raptor_new_uri_from_uri_local_name ()</title>
<indexterm zone="raptor-new-uri-from-uri-local-name"><primary>raptor_new_uri_from_uri_local_name</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_from_uri_local_name  (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         unsigned <link linkend="char">char</link> *local_name);</programlisting>
<para>
Constructor - create a raptor URI from an existing URI and a local name.
</para>
<para>
Creates a new URI from the concatenation of the <parameter>local_name</parameter> to the
<parameter>uri</parameter>.  This is NOT relative URI resolution, which is done by the
<link linkend="raptor-new-uri-relative-to-base"><function>raptor_new_uri_relative_to_base()</function></link> constructor.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> existing <link linkend="raptor-uri"><type>raptor_uri</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>local_name</parameter>&nbsp;:</term>
<listitem><simpara> local name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-relative-to-base" role="function">
<title>raptor_new_uri_relative_to_base ()</title>
<indexterm zone="raptor-new-uri-relative-to-base"><primary>raptor_new_uri_relative_to_base</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_relative_to_base     (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *uri_string);</programlisting>
<para>
Constructor - create a raptor URI from a base URI and a relative URI string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> existing base URI
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> relative URI string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-from-id" role="function">
<title>raptor_new_uri_from_id ()</title>
<indexterm zone="raptor-new-uri-from-id"><primary>raptor_new_uri_from_id</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_from_id              (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *id);</programlisting>
<para>
Constructor - create a new URI from a base URI and RDF ID.
</para>
<para>
This creates a URI equivalent to concatenating <parameter>base_uri</parameter> with
## and <parameter>id</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> existing base URI
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>id</parameter>&nbsp;:</term>
<listitem><simpara> RDF ID
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-for-rdf-concept" role="function">
<title>raptor_new_uri_for_rdf_concept ()</title>
<indexterm zone="raptor-new-uri-for-rdf-concept"><primary>raptor_new_uri_for_rdf_concept</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_for_rdf_concept      (const <link linkend="char">char</link> *name);</programlisting>
<para>
Constructor - create a raptor URI for the RDF namespace concept name.
</para>
<para>
Example: u=raptor_new_uri_for_rdf_concept("value") creates a new
URI for the rdf:value term.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> RDF namespace concept
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-free-uri" role="function">
<title>raptor_free_uri ()</title>
<indexterm zone="raptor-free-uri"><primary>raptor_free_uri</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_free_uri                     (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Destructor - destroy a <link linkend="raptor-uri"><type>raptor_uri</type></link> object</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI to destroy
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-compare" role="function">
<title>raptor_uri_compare ()</title>
<indexterm zone="raptor-uri-compare"><primary>raptor_uri_compare</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_uri_compare                  (<link linkend="raptor-uri">raptor_uri</link> *uri1,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri2);</programlisting>
<para>
Compare two URIs, ala strcmp.
</para>
<para>
A NULL URI is always less than (never equal to) a non-NULL URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri1</parameter>&nbsp;:</term>
<listitem><simpara> URI 1 (may be NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri2</parameter>&nbsp;:</term>
<listitem><simpara> URI 2 (may be NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> -1 if uri1 &lt; uri2, 0 if equal, 1 if uri1 &gt; uri2
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-equals" role="function">
<title>raptor_uri_equals ()</title>
<indexterm zone="raptor-uri-equals"><primary>raptor_uri_equals</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_uri_equals                   (<link linkend="raptor-uri">raptor_uri</link> *uri1,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri2);</programlisting>
<para>
Check if two URIs are equal.
</para>
<para>
A NULL URI is not equal to a non-NULL URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri1</parameter>&nbsp;:</term>
<listitem><simpara> URI 1 (may be NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri2</parameter>&nbsp;:</term>
<listitem><simpara> URI 2 (may be NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 if the URIs are equal
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-copy" role="function">
<title>raptor_uri_copy ()</title>
<indexterm zone="raptor-uri-copy"><primary>raptor_uri_copy</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_uri_copy                     (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Constructor - get a copy of a URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-as-string" role="function">
<title>raptor_uri_as_string ()</title>
<indexterm zone="raptor-uri-as-string"><primary>raptor_uri_as_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_as_string                (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Get a string representation of a URI.
</para>
<para>
Returns a shared pointer to a string representation of <parameter>uri</parameter>.  This
string is shared and must not be freed, otherwise see use the
<link linkend="raptor-uri-to-string"><function>raptor_uri_to_string()</function></link> or <link linkend="raptor-uri-to-counted-string"><function>raptor_uri_to_counted_string()</function></link> methods.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-uri"><type>raptor_uri</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> shared string representation of URI
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-as-counted-string" role="function">
<title>raptor_uri_as_counted_string ()</title>
<indexterm zone="raptor-uri-as-counted-string"><primary>raptor_uri_as_counted_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_as_counted_string        (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="size-t">size_t</link> *len_p);</programlisting>
<para>
Get a string representation of a URI with count.
</para>
<para>
Returns a shared pointer to a string representation of <parameter>uri</parameter> along
with the length of the string in <parameter>len_p</parameter>, if not NULL.  This
string is shared and must not be freed, otherwise see use the
<link linkend="raptor-uri-to-string"><function>raptor_uri_to_string()</function></link> or <link linkend="raptor-uri-to-counted-string"><function>raptor_uri_to_counted_string()</function></link> methods.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len_p</parameter>&nbsp;:</term>
<listitem><simpara> address of length variable or NULL
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> shared string representation of URI
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-for-xmlbase" role="function">
<title>raptor_new_uri_for_xmlbase ()</title>
<indexterm zone="raptor-new-uri-for-xmlbase"><primary>raptor_new_uri_for_xmlbase</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_for_xmlbase          (<link linkend="raptor-uri">raptor_uri</link> *old_uri);</programlisting>
<para>
Constructor - create a URI suitable for use as an XML Base.
</para>
<para>
Takes an existing URI and ensures it has a path (default /) and has
no fragment or query arguments - XML base does not use these.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>old_uri</parameter>&nbsp;:</term>
<listitem><simpara> URI to transform
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-new-uri-for-retrieval" role="function">
<title>raptor_new_uri_for_retrieval ()</title>
<indexterm zone="raptor-new-uri-for-retrieval"><primary>raptor_new_uri_for_retrieval</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         raptor_new_uri_for_retrieval        (<link linkend="raptor-uri">raptor_uri</link> *old_uri);</programlisting>
<para>
Constructor - create a URI suitable for retrieval.
</para>
<para>
Takes an existing URI and ensures it has a path (default /) and has
no fragment - URI retrieval does not use the fragment part.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>old_uri</parameter>&nbsp;:</term>
<listitem><simpara> URI to transform
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new <link linkend="raptor-uri"><type>raptor_uri</type></link> object or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-resolve-uri-reference" role="function">
<title>raptor_uri_resolve_uri_reference ()</title>
<indexterm zone="raptor-uri-resolve-uri-reference"><primary>raptor_uri_resolve_uri_reference</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_uri_resolve_uri_reference    (unsigned <link linkend="char">char</link> *base_uri,
                                                         unsigned <link linkend="char">char</link> *reference_uri,
                                                         unsigned <link linkend="char">char</link> *buffer,
                                                         <link linkend="size-t">size_t</link> length);</programlisting>
<para>
Resolve a URI to a base URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> Base URI string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reference_uri</parameter>&nbsp;:</term>
<listitem><simpara> Reference URI string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara> Destination buffer URI
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> Length of destination buffer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-filename-to-uri-string" role="function">
<title>raptor_uri_filename_to_uri_string ()</title>
<indexterm zone="raptor-uri-filename-to-uri-string"><primary>raptor_uri_filename_to_uri_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_filename_to_uri_string   (const <link linkend="char">char</link> *filename);</programlisting>
<para>
Converts a filename to a file: URI.
</para>
<para>
Handles the OS-specific escaping on turning filenames into URIs
and returns a new buffer that the caller must <link linkend="free"><function>free()</function></link>.  Turns
a space in the filname into <link linkend="20:CAPS"><literal>20</literal></link> and '%' into <link linkend="25:CAPS"><literal>25</literal></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
<listitem><simpara> The filename to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated string with the URI or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-uri-string-to-filename" role="function">
<title>raptor_uri_uri_string_to_filename ()</title>
<indexterm zone="raptor-uri-uri-string-to-filename"><primary>raptor_uri_uri_string_to_filename</primary></indexterm><programlisting><link linkend="char">char</link>*               raptor_uri_uri_string_to_filename   (unsigned <link linkend="char">char</link> *uri_string);</programlisting>
<para>
Convert a file: URI to a filename.
</para>
<para>
Handles the OS-specific file: URIs to filename mappings.  Returns
a new buffer containing the filename that the caller must free.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> The file: URI to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated string with the filename or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-uri-string-to-filename-fragment" role="function">
<title>raptor_uri_uri_string_to_filename_fragment ()</title>
<indexterm zone="raptor-uri-uri-string-to-filename-fragment"><primary>raptor_uri_uri_string_to_filename_fragment</primary></indexterm><programlisting><link linkend="char">char</link>*               raptor_uri_uri_string_to_filename_fragment
                                                        (unsigned <link linkend="char">char</link> *uri_string,
                                                         unsigned <link linkend="char">char</link> **fragment_p);</programlisting>
<para>
Convert a file: URI to a filename and fragment.
</para>
<para>
Handles the OS-specific file: URIs to filename mappings.  Returns
a new buffer containing the filename that the caller must free.
</para>
<para>
If <parameter>fragment_p</parameter> is given, a new string containing the URI fragment
is returned, or NULL if none is present</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> The file: URI to convert
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fragment_p</parameter>&nbsp;:</term>
<listitem><simpara> Address of pointer to store any URI fragment or NULL
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated string with the filename or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-uri-string-is-file-uri" role="function">
<title>raptor_uri_uri_string_is_file_uri ()</title>
<indexterm zone="raptor-uri-uri-string-is-file-uri"><primary>raptor_uri_uri_string_is_file_uri</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_uri_uri_string_is_file_uri   (unsigned <link linkend="char">char</link> *uri_string);</programlisting>
<para>
Check if a URI string is a file: URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> The URI string to check
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> Non zero if URI string is a file: URI
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-is-file-uri" role="function">
<title>raptor_uri_is_file_uri ()</title>
<indexterm zone="raptor-uri-is-file-uri"><primary>raptor_uri_is_file_uri</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_uri_is_file_uri              (unsigned <link linkend="char">char</link> *uri_string);</programlisting>
<para>
<parameter>Deprecated</parameter>: use raptor_uri_uri_string_is_file_uri
</para>
<para>
Check if a URI string is a file: URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> The URI string to check
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> Non zero if URI string is a file: URI
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-to-relative-counted-uri-string" role="function">
<title>raptor_uri_to_relative_counted_uri_string ()</title>
<indexterm zone="raptor-uri-to-relative-counted-uri-string"><primary>raptor_uri_to_relative_counted_uri_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_to_relative_counted_uri_string
                                                        (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         <link linkend="raptor-uri">raptor_uri</link> *reference_uri,
                                                         <link linkend="size-t">size_t</link> *length_p);</programlisting>
<para>
Get the counted relative URI string of a URI against a base URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> The base absolute URI to resolve against (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reference_uri</parameter>&nbsp;:</term>
<listitem><simpara> The reference absolute URI to use
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length_p</parameter>&nbsp;:</term>
<listitem><simpara> Location to store the length of the relative URI string or NULL
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated relative URI string or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-to-relative-uri-string" role="function">
<title>raptor_uri_to_relative_uri_string ()</title>
<indexterm zone="raptor-uri-to-relative-uri-string"><primary>raptor_uri_to_relative_uri_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_to_relative_uri_string   (<link linkend="raptor-uri">raptor_uri</link> *base_uri,
                                                         <link linkend="raptor-uri">raptor_uri</link> *reference_uri);</programlisting>
<para>
Get the relative URI string of a URI against a base URI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>base_uri</parameter>&nbsp;:</term>
<listitem><simpara> The base absolute URI to resolve against
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reference_uri</parameter>&nbsp;:</term>
<listitem><simpara> The reference absolute URI to use
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated relative URI string or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-print" role="function">
<title>raptor_uri_print ()</title>
<indexterm zone="raptor-uri-print"><primary>raptor_uri_print</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_uri_print                    (const <link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="FILE:CAPS">FILE</link> *stream);</programlisting>
<para>
Print a URI to a file handle.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI to print
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>stream</parameter>&nbsp;:</term>
<listitem><simpara> The file handle to print to
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-to-counted-string" role="function">
<title>raptor_uri_to_counted_string ()</title>
<indexterm zone="raptor-uri-to-counted-string"><primary>raptor_uri_to_counted_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_to_counted_string        (<link linkend="raptor-uri">raptor_uri</link> *uri,
                                                         <link linkend="size-t">size_t</link> *len_p);</programlisting>
<para>
Get a new counted string for a URI.
</para>
<para>
If <parameter>len_p</parameter> is not NULL, the length of the string is stored in it.
</para>
<para>
The memory allocated must be freed by the caller and
<link linkend="raptor-free-memory"><function>raptor_free_memory()</function></link> should be used for best portability.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-uri"><type>raptor_uri</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len_p</parameter>&nbsp;:</term>
<listitem><simpara> Pointer to length (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new string or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-to-string" role="function">
<title>raptor_uri_to_string ()</title>
<indexterm zone="raptor-uri-to-string"><primary>raptor_uri_to_string</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      raptor_uri_to_string                (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Get a new string for a URI.
</para>
<para>
The memory allocated must be freed by the caller and
<link linkend="raptor-free-memory"><function>raptor_free_memory()</function></link> should be used for best portability.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-uri"><type>raptor_uri</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new string or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-set-handler" role="function">
<title>raptor_uri_set_handler ()</title>
<indexterm zone="raptor-uri-set-handler"><primary>raptor_uri_set_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_uri_set_handler              (const <link linkend="raptor-uri-handler">raptor_uri_handler</link> *handler,
                                                         <link linkend="void">void</link> *context);</programlisting>
<para>
Change the URI class implementation to the functions provided by the
</para>
<para>
The URI interface in <parameter>handler->initialised</parameter> should be either 1
or 2 (if raptor_uri_compare_func is implemented).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> URI handler structure
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> URI handler context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-uri-get-handler" role="function">
<title>raptor_uri_get_handler ()</title>
<indexterm zone="raptor-uri-get-handler"><primary>raptor_uri_get_handler</primary></indexterm><programlisting><link linkend="void">void</link>                raptor_uri_get_handler              (const <link linkend="raptor-uri-handler">raptor_uri_handler</link> **handler,
                                                         <link linkend="void">void</link> **context);</programlisting>
<para>
Return the current raptor URI class implementation <parameter>handler</parameter> and <parameter>context</parameter></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> URI handler to return
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
<listitem><simpara> URI context to return
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="raptor-iostream-write-uri" role="function">
<title>raptor_iostream_write_uri ()</title>
<indexterm zone="raptor-iostream-write-uri"><primary>raptor_iostream_write_uri</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_iostream_write_uri           (<link linkend="raptor-iostream">raptor_iostream</link> *iostr,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Write a raptor URI to the iostream.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>iostr</parameter>&nbsp;:</term>
<listitem><simpara> raptor iostream
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> URI
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
