mirror of
https://github.com/cookiengineer/audacity
synced 2025-06-22 07:10:06 +02:00
390 lines
20 KiB
XML
390 lines
20 KiB
XML
<?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> :</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> :</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> :</term>
|
|
<listitem><simpara> rasqal_world object
|
|
</simpara></listitem></varlistentry>
|
|
<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 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> :</term>
|
|
<listitem><simpara> rasqal_world object
|
|
</simpara></listitem></varlistentry>
|
|
<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 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> :</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 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> :</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 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> :</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> :</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 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> :</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 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> :</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 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> :</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>
|