<?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">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 role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
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>;
<link linkend="void">void</link> <link linkend="rasqal-init">rasqal_init</link> (void);
<link linkend="void">void</link> <link linkend="rasqal-finish">rasqal_finish</link> (void);
enum <link linkend="rasqal-feature">rasqal_feature</link>;
<link linkend="int">int</link> <link linkend="rasqal-language-name-check">rasqal_language_name_check</link> (const <link linkend="char">char</link> *name);
<link linkend="int">int</link> <link linkend="rasqal-languages-enumerate">rasqal_languages_enumerate</link> (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 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 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="rasqal-version-decimal" role="variable"/>rasqal_version_decimal</title>
<indexterm><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>
<title><anchor id="rasqal-version-major" role="variable"/>rasqal_version_major</title>
<indexterm><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>
<title><anchor id="rasqal-version-minor" role="variable"/>rasqal_version_minor</title>
<indexterm><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>
<title><anchor id="rasqal-version-release" role="variable"/>rasqal_version_release</title>
<indexterm><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>
<title><anchor id="rasqal-init" role="function"/>rasqal_init ()</title>
<indexterm><primary>rasqal_init</primary></indexterm><programlisting><link linkend="void">void</link> rasqal_init (void);</programlisting>
<para>
Initialise the rasqal library.
</para>
<para>
MUST be called before using any of the rasqal APIs.</para>
<para>
</para></refsect2>
<refsect2>
<title><anchor id="rasqal-finish" role="function"/>rasqal_finish ()</title>
<indexterm><primary>rasqal_finish</primary></indexterm><programlisting><link linkend="void">void</link> rasqal_finish (void);</programlisting>
<para>
Terminate the rasqal library.
</para>
<para>
Must be called to clean up any resources used by the library.</para>
<para>
</para></refsect2>
<refsect2>
<title><anchor id="rasqal-feature" role="enum"/>enum rasqal_feature</title>
<indexterm><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>
<term><anchor id="RASQAL-FEATURE-NO-NET:CAPS" role="constant"/><literal>RASQAL_FEATURE_NO_NET</literal></term>
<listitem><simpara> Deny network requests.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="RASQAL-FEATURE-LAST:CAPS" role="constant"/><literal>RASQAL_FEATURE_LAST</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-language-name-check" role="function"/>rasqal_language_name_check ()</title>
<indexterm><primary>rasqal_language_name_check</primary></indexterm><programlisting><link linkend="int">int</link> rasqal_language_name_check (const <link linkend="char">char</link> *name);</programlisting>
<para>
Check name of a query language.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter> :</term>
<listitem><simpara> the query language name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non 0 if name is a known query language
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-languages-enumerate" role="function"/>rasqal_languages_enumerate ()</title>
<indexterm><primary>rasqal_languages_enumerate</primary></indexterm><programlisting><link linkend="int">int</link> rasqal_languages_enumerate (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>counter</parameter> :</term>
<listitem><simpara> index into the list of syntaxes
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter> :</term>
<listitem><simpara> pointer to store the name of the syntax (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>label</parameter> :</term>
<listitem><simpara> pointer to store syntax readable label (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri_string</parameter> :</term>
<listitem><simpara> pointer to store syntax URI string (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non 0 on failure of if counter is out of range
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-alloc-memory" role="function"/>rasqal_alloc_memory ()</title>
<indexterm><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> :</term>
<listitem><simpara> size of memory to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the address of the allocated memory or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-calloc-memory" role="function"/>rasqal_calloc_memory ()</title>
<indexterm><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> :</term>
<listitem><simpara> number of members
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter> :</term>
<listitem><simpara> size of item
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the address of the allocated memory or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-free-memory" role="function"/>rasqal_free_memory ()</title>
<indexterm><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> :</term>
<listitem><simpara> memory pointer
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-feature-from-uri" role="function"/>rasqal_feature_from_uri ()</title>
<indexterm><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> :</term>
<listitem><simpara> feature URI
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> < 0 if the feature is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-feature-value-type" role="function"/>rasqal_feature_value_type ()</title>
<indexterm><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> :</term>
<listitem><simpara> rasqal query feature
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the type of the feature or <0 if <parameter>feature</parameter> is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-features-enumerate" role="function"/>rasqal_features_enumerate ()</title>
<indexterm><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> :</term>
<listitem><simpara> feature enumeration (0+)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter> :</term>
<listitem><simpara> pointer to store feature short name (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter> :</term>
<listitem><simpara> pointer to store feature URI (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>label</parameter> :</term>
<listitem><simpara> pointer to feature label (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on success, <0 on failure, >0 if feature is unknown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rasqal-get-feature-count" role="function"/>rasqal_get_feature_count ()</title>
<indexterm><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> :</term><listitem><simpara> count of features in the <link linkend="rasqal-feature"><type>rasqal_feature</type></link> enumeration
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="RASQAL-DEPRECATED:CAPS" role="macro"/>RASQAL_DEPRECATED</title>
<indexterm><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>