<?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="rasqal-section-general">
<refmeta>
<refentrytitle role="top_of_page" id="rasqal-section-general.top_of_page">General library facilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RASQAL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>General library facilities</refname>
<refpurpose>Startup and shutdown, memory handling, version checks and misc functions.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="rasqal-section-general.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
typedef             <link linkend="rasqal-world">rasqal_world</link>;
<link linkend="void">void</link>                <link linkend="rasqal-free-world">rasqal_free_world</link>                   (<link linkend="rasqal-world">rasqal_world</link> *world);
<link linkend="rasqal-world">rasqal_world</link>*       <link linkend="rasqal-new-world">rasqal_new_world</link>                    (void);
extern              const unsigned int <link linkend="rasqal-version-decimal">rasqal_version_decimal</link>;
extern              const unsigned int <link linkend="rasqal-version-major">rasqal_version_major</link>;
extern              const unsigned int <link linkend="rasqal-version-minor">rasqal_version_minor</link>;
extern              const unsigned int <link linkend="rasqal-version-release">rasqal_version_release</link>;
enum                <link linkend="rasqal-feature">rasqal_feature</link>;
<link linkend="int">int</link>                 <link linkend="rasqal-language-name-check">rasqal_language_name_check</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         const <link linkend="char">char</link> *name);
<link linkend="int">int</link>                 <link linkend="rasqal-languages-enumerate">rasqal_languages_enumerate</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="int">int</link> counter,
                                                         const <link linkend="char">char</link> **name,
                                                         const <link linkend="char">char</link> **label,
                                                         unsigned <link linkend="char">char</link> **uri_string);
<link linkend="void">void</link>*               <link linkend="rasqal-alloc-memory">rasqal_alloc_memory</link>                 (<link linkend="size-t">size_t</link> size);
<link linkend="void">void</link>*               <link linkend="rasqal-calloc-memory">rasqal_calloc_memory</link>                (<link linkend="size-t">size_t</link> nmemb,
                                                         <link linkend="size-t">size_t</link> size);
<link linkend="void">void</link>                <link linkend="rasqal-free-memory">rasqal_free_memory</link>                  (<link linkend="void">void</link> *ptr);
<link linkend="rasqal-feature">rasqal_feature</link>      <link linkend="rasqal-feature-from-uri">rasqal_feature_from_uri</link>             (<link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="int">int</link>                 <link linkend="rasqal-feature-value-type">rasqal_feature_value_type</link>           (const <link linkend="rasqal-feature">rasqal_feature</link> feature);
<link linkend="int">int</link>                 <link linkend="rasqal-features-enumerate">rasqal_features_enumerate</link>           (const <link linkend="rasqal-feature">rasqal_feature</link> feature,
                                                         const <link linkend="char">char</link> **name,
                                                         <link linkend="raptor-uri">raptor_uri</link> **uri,
                                                         const <link linkend="char">char</link> **label);
unsigned <link linkend="int">int</link>        <link linkend="rasqal-get-feature-count">rasqal_get_feature_count</link>            (void);
#define             <link linkend="RASQAL-DEPRECATED:CAPS">RASQAL_DEPRECATED</link>
</synopsis>
</refsynopsisdiv>









<refsect1 id="rasqal-section-general.description" role="desc">
<title role="desc.title">Description</title>
<para>
The functions in this section cover general library features such
as startup and shutdown, checking the current library version and
dealing with memory allocation and freeing.  It also provides
functions to enumerate and check the supported query languages,
their names, labels and URI.
</para>
</refsect1>

<refsect1 id="rasqal-section-general.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="rasqal-world" role="typedef">
<title>rasqal_world</title>
<indexterm zone="rasqal-world"><primary>rasqal_world</primary></indexterm><programlisting>rasqal_world* world;
</programlisting>
<para>
Rasqal world class.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-free-world" role="function">
<title>rasqal_free_world ()</title>
<indexterm zone="rasqal-free-world"><primary>rasqal_free_world</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_free_world                   (<link linkend="rasqal-world">rasqal_world</link> *world);</programlisting>
<para>
Terminate the rasqal library.
</para>
<para>
Destroys a rasqal_world object and all static information.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal_world object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-world" role="function">
<title>rasqal_new_world ()</title>
<indexterm zone="rasqal-new-world"><primary>rasqal_new_world</primary></indexterm><programlisting><link linkend="rasqal-world">rasqal_world</link>*       rasqal_new_world                    (void);</programlisting>
<para>
Initialise the rasqal library.
</para>
<para>
Creates a rasqal_world object and initializes it.
</para>
<para>
The returned world object is used with subsequent rasqal API calls.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> rasqal_world object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-version-decimal" role="variable">
<title>rasqal_version_decimal</title>
<indexterm zone="rasqal-version-decimal"><primary>rasqal_version_decimal</primary></indexterm><programlisting>extern const unsigned int rasqal_version_decimal;
</programlisting>
<para>
Library full version as a decimal integer.
</para>
<para>
See also <link linkend="rasqal-version-string"><type>rasqal_version_string</type></link>.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-version-major" role="variable">
<title>rasqal_version_major</title>
<indexterm zone="rasqal-version-major"><primary>rasqal_version_major</primary></indexterm><programlisting>extern const unsigned int rasqal_version_major;
</programlisting>
<para>
Library major version number as a decimal integer.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-version-minor" role="variable">
<title>rasqal_version_minor</title>
<indexterm zone="rasqal-version-minor"><primary>rasqal_version_minor</primary></indexterm><programlisting>extern const unsigned int rasqal_version_minor;
</programlisting>
<para>
Library minor version number as a decimal integer.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-version-release" role="variable">
<title>rasqal_version_release</title>
<indexterm zone="rasqal-version-release"><primary>rasqal_version_release</primary></indexterm><programlisting>extern const unsigned int rasqal_version_release;
</programlisting>
<para>
Library release version number as a decimal integer.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-feature" role="enum">
<title>enum rasqal_feature</title>
<indexterm zone="rasqal-feature"><primary>rasqal_feature</primary></indexterm><programlisting>typedef enum {
  RASQAL_FEATURE_NO_NET,
  RASQAL_FEATURE_LAST = RASQAL_FEATURE_NO_NET
} rasqal_feature;
</programlisting>
<para>
Query features.
</para>
<para>
None currently defined.</para>
<para>

</para><variablelist role="enum">
<varlistentry id="RASQAL-FEATURE-NO-NET:CAPS" role="constant">
<term><literal>RASQAL_FEATURE_NO_NET</literal></term>
<listitem><simpara> Deny network requests.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-FEATURE-LAST:CAPS" role="constant">
<term><literal>RASQAL_FEATURE_LAST</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-language-name-check" role="function">
<title>rasqal_language_name_check ()</title>
<indexterm zone="rasqal-language-name-check"><primary>rasqal_language_name_check</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_language_name_check          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         const <link linkend="char">char</link> *name);</programlisting>
<para>
Check name of a query language.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal_world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> the query language name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non 0 if name is a known query language
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-languages-enumerate" role="function">
<title>rasqal_languages_enumerate ()</title>
<indexterm zone="rasqal-languages-enumerate"><primary>rasqal_languages_enumerate</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_languages_enumerate          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="int">int</link> counter,
                                                         const <link linkend="char">char</link> **name,
                                                         const <link linkend="char">char</link> **label,
                                                         unsigned <link linkend="char">char</link> **uri_string);</programlisting>
<para>
Get information on query languages.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal_world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>counter</parameter>&nbsp;:</term>
<listitem><simpara> index into the list of syntaxes
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> pointer to store the name of the syntax (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>label</parameter>&nbsp;:</term>
<listitem><simpara> pointer to store syntax readable label (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri_string</parameter>&nbsp;:</term>
<listitem><simpara> pointer to store syntax URI string (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non 0 on failure of if counter is out of range
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-alloc-memory" role="function">
<title>rasqal_alloc_memory ()</title>
<indexterm zone="rasqal-alloc-memory"><primary>rasqal_alloc_memory</primary></indexterm><programlisting><link linkend="void">void</link>*               rasqal_alloc_memory                 (<link linkend="size-t">size_t</link> size);</programlisting>
<para>
Allocate memory inside rasqal.
</para>
<para>
Some systems require memory allocated in a library to
be deallocated in that library.  This function allows
memory to be allocated inside the rasqal shared library
that can be freed inside rasqal either internally or via
<link linkend="rasqal-free-memory"><function>rasqal_free_memory()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> size of memory to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the address of the allocated memory or NULL on failure

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-calloc-memory" role="function">
<title>rasqal_calloc_memory ()</title>
<indexterm zone="rasqal-calloc-memory"><primary>rasqal_calloc_memory</primary></indexterm><programlisting><link linkend="void">void</link>*               rasqal_calloc_memory                (<link linkend="size-t">size_t</link> nmemb,
                                                         <link linkend="size-t">size_t</link> size);</programlisting>
<para>
Allocate zeroed array of items inside rasqal.
</para>
<para>
Some systems require memory allocated in a library to
be deallocated in that library.  This function allows
memory to be allocated inside the rasqal shared library
that can be freed inside rasqal either internally or via
<link linkend="rasqal-free-memory"><function>rasqal_free_memory()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>nmemb</parameter>&nbsp;:</term>
<listitem><simpara> number of members
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> size of item
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the address of the allocated memory or NULL on failure

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-free-memory" role="function">
<title>rasqal_free_memory ()</title>
<indexterm zone="rasqal-free-memory"><primary>rasqal_free_memory</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_free_memory                  (<link linkend="void">void</link> *ptr);</programlisting>
<para>
Free memory allocated inside rasqal.
</para>
<para>
Some systems require memory allocated in a library to
be deallocated in that library.  This function allows
memory allocated by rasqal to be freed.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ptr</parameter>&nbsp;:</term>
<listitem><simpara> memory pointer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-feature-from-uri" role="function">
<title>rasqal_feature_from_uri ()</title>
<indexterm zone="rasqal-feature-from-uri"><primary>rasqal_feature_from_uri</primary></indexterm><programlisting><link linkend="rasqal-feature">rasqal_feature</link>      rasqal_feature_from_uri             (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Turn a feature URI into an feature enum.
</para>
<para>
The allowed feature URIs are available via <link linkend="rasqal-features-enumerate"><function>rasqal_features_enumerate()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> feature URI
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> &lt; 0 if the feature is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-feature-value-type" role="function">
<title>rasqal_feature_value_type ()</title>
<indexterm zone="rasqal-feature-value-type"><primary>rasqal_feature_value_type</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_feature_value_type           (const <link linkend="rasqal-feature">rasqal_feature</link> feature);</programlisting>
<para>
Get the type of a features.
</para>
<para>
The type of the <parameter>feature</parameter> is 0=integer , 1=string.  Other values are
undefined.  Most features are integer values and use
rasqal_query_set_feature <link linkend="rasqal-query-get-feature"><function>rasqal_query_get_feature()</function></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>feature</parameter>&nbsp;:</term>
<listitem><simpara> rasqal query feature
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the type of the feature or &lt;0 if <parameter>feature</parameter> is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-features-enumerate" role="function">
<title>rasqal_features_enumerate ()</title>
<indexterm zone="rasqal-features-enumerate"><primary>rasqal_features_enumerate</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_features_enumerate           (const <link linkend="rasqal-feature">rasqal_feature</link> feature,
                                                         const <link linkend="char">char</link> **name,
                                                         <link linkend="raptor-uri">raptor_uri</link> **uri,
                                                         const <link linkend="char">char</link> **label);</programlisting>
<para>
Get list of rasqal features.
</para>
<para>
If uri is not NULL, a pointer to a new raptor_uri is returned
that must be freed by the caller with <link linkend="raptor-free-uri"><function>raptor_free_uri()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>feature</parameter>&nbsp;:</term>
<listitem><simpara> feature enumeration (0+)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> pointer to store feature short name (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> pointer to store feature URI (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>label</parameter>&nbsp;:</term>
<listitem><simpara> pointer to feature label (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 on success, &lt;0 on failure, &gt;0 if feature is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-get-feature-count" role="function">
<title>rasqal_get_feature_count ()</title>
<indexterm zone="rasqal-get-feature-count"><primary>rasqal_get_feature_count</primary></indexterm><programlisting>unsigned <link linkend="int">int</link>        rasqal_get_feature_count            (void);</programlisting>
<para>
Get the count of features defined.
</para>
<para>
This is prefered to the compile time-only symbol <link linkend="RASQAL-FEATURE-LAST:CAPS"><type>RASQAL_FEATURE_LAST</type></link>
and returns a count of the number of features which is
<link linkend="RASQAL-FEATURE-LAST:CAPS"><type>RASQAL_FEATURE_LAST</type></link>+1.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> count of features in the <link linkend="rasqal-feature"><type>rasqal_feature</type></link> enumeration
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="RASQAL-DEPRECATED:CAPS" role="macro">
<title>RASQAL_DEPRECATED</title>
<indexterm zone="RASQAL-DEPRECATED:CAPS"><primary>RASQAL_DEPRECATED</primary></indexterm><programlisting>#define             RASQAL_DEPRECATED</programlisting>
<para>
When defined before a function, indicates that the function
has been deprecated and may be replaced in a future release.
With some versions of gcc this may give a compilation warning.
</para></refsect2>

</refsect1>




</refentry>
