General library facilities

General library facilities — Startup and shutdown, memory handling, version checks and misc functions.

Synopsis

typedef             rasqal_world;
void                rasqal_free_world                   (rasqal_world *world);
rasqal_world *      rasqal_new_world                    (void);
int                 rasqal_world_open                   (rasqal_world *world);
void                rasqal_world_set_log_handler        (rasqal_world *world,
                                                         void *user_data,
                                                         raptor_log_handler handler);
int                 rasqal_world_set_warning_level      (rasqal_world *world,
                                                         unsigned int warning_level);
raptor_world *      rasqal_world_get_raptor             (rasqal_world *world);
void                rasqal_world_set_raptor             (rasqal_world *world,
                                                         raptor_world *raptor_world_ptr);
const raptor_syntax_description * rasqal_world_get_query_language_description
                                                        (rasqal_world *world,
                                                         unsigned int counter);
const raptor_syntax_description * rasqal_world_get_query_results_format_description
                                                        (rasqal_world *world,
                                                         unsigned int counter);
char *              (*rasqal_generate_bnodeid_handler)  (rasqal_world *world,
                                                         void *user_data,
                                                         unsigned char *user_bnodeid);
int                 rasqal_world_set_generate_bnodeid_handler
                                                        (rasqal_world *world,
                                                         void *user_data,
                                                         rasqal_generate_bnodeid_handler handler);
int                 rasqal_world_set_default_generate_bnodeid_parameters
                                                        (rasqal_world *world,
                                                         char *prefix,
                                                         int base);
const char *        rasqal_world_guess_query_results_format_name
                                                        (rasqal_world *world,
                                                         raptor_uri *uri,
                                                         const char *mime_type,
                                                         const char *buffer,
                                                         size_t len,
                                                         const unsigned char *identifier);
extern const unsigned int rasqal_version_decimal;
extern const unsigned int rasqal_version_major;
extern const unsigned int rasqal_version_minor;
extern const unsigned int rasqal_version_release;
extern const char * const rasqal_version_string;
extern const char * const rasqal_copyright_string;
extern const char * const rasqal_short_copyright_string;
extern const char * const rasqal_home_url_string;
extern const char * const rasqal_license_string;
enum                rasqal_feature;
int                 rasqal_language_name_check          (rasqal_world *world,
                                                         const char *name);
int                 rasqal_languages_enumerate          (rasqal_world *world,
                                                         unsigned int counter,
                                                         const char **name,
                                                         const char **label,
                                                         const unsigned char **uri_string);
void *              rasqal_alloc_memory                 (size_t size);
void *              rasqal_calloc_memory                (size_t nmemb,
                                                         size_t size);
void                rasqal_free_memory                  (void *ptr);
rasqal_feature      rasqal_feature_from_uri             (rasqal_world *world,
                                                         raptor_uri *uri);
int                 rasqal_feature_value_type           (const rasqal_feature feature);
int                 rasqal_features_enumerate           (rasqal_world *world,
                                                         const rasqal_feature feature,
                                                         const char **name,
                                                         raptor_uri **uri,
                                                         const char **label);
unsigned int        rasqal_get_feature_count            (void);
#define             RASQAL_DEPRECATED
#define             RASQAL_VERSION
#define             RASQAL_VERSION_MAJOR
#define             RASQAL_VERSION_MINOR
#define             RASQAL_VERSION_RELEASE
#define             RASQAL_VERSION_STRING
#define             RASQAL_RAPTOR_VERSION

Description

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.

Details

rasqal_world

rasqal_world* world;

Rasqal world class.


rasqal_free_world ()

void                rasqal_free_world                   (rasqal_world *world);

Terminate the rasqal library.

Destroys a rasqal_world object and all static information.

world :

rasqal_world object

rasqal_new_world ()

rasqal_world *      rasqal_new_world                    (void);

Allocate a new rasqal_world object.

The rasqal_world is initialized with rasqal_world_open(). Allocation and initialization are decoupled to allow changing settings on the world object before init.

Returns :

rasqal_world object or NULL on failure

rasqal_world_open ()

int                 rasqal_world_open                   (rasqal_world *world);

Initialise the rasqal library.

Initializes a rasqal_world object created by rasqal_new_world(). Allocation and initialization are decoupled to allow changing settings on the world object before init. These settings include e.g. the raptor library instance set with rasqal_world_set_raptor().

The initialized world object is used with subsequent rasqal API calls.

world :

rasqal_world object

Returns :

non-0 on failure

rasqal_world_set_log_handler ()

void                rasqal_world_set_log_handler        (rasqal_world *world,
                                                         void *user_data,
                                                         raptor_log_handler handler);

Set the log handler for this rasqal_world.

Also sets the raptor log handler to the same user_data and handler via raptor_world_set_log_handler(). (Rasqal 0.9.26+)

world :

rasqal_world object

user_data :

user data for log handler function

handler :

log handler function

rasqal_world_set_warning_level ()

int                 rasqal_world_set_warning_level      (rasqal_world *world,
                                                         unsigned int warning_level);

Set the rasqal warning reporting level

The warning levels used are as follows:

  1. Level 10 is used for serious warnings that may be errors.

  2. Level 30 is used for moderate style warnings.

  3. Level 90 is used for strict conformance warnings.

When this method is called to set a warning level, only warnings of less than warning_level are reported. The default warning level is 50.

world :

world

warning_level :

warning level 0..100

Returns :

non-0 on failure

rasqal_world_get_raptor ()

raptor_world *      rasqal_world_get_raptor             (rasqal_world *world);

Get the raptor_world instance used by this rasqal_world.

world :

rasqal_world object

Returns :

raptor_world object or NULL on failure (e.g. not initialized)

rasqal_world_set_raptor ()

void                rasqal_world_set_raptor             (rasqal_world *world,
                                                         raptor_world *raptor_world_ptr);

Set the raptor_world instance to be used with this rasqal_world.

If no raptor_world instance is set with this function, rasqal_world_open() creates a new instance.

Ownership of the raptor_world is not taken. If the raptor library instance is set with this function, rasqal_free_world() will not free it.

world :

rasqal_world object

raptor_world_ptr :

raptor_world object

rasqal_world_get_query_language_description ()

const raptor_syntax_description * rasqal_world_get_query_language_description
                                                        (rasqal_world *world,
                                                         unsigned int counter);

Get query language descriptive information

world :

world object

counter :

index into the list of query languages

Returns :

description or NULL if counter is out of range

rasqal_world_get_query_results_format_description ()

const raptor_syntax_description * rasqal_world_get_query_results_format_description
                                                        (rasqal_world *world,
                                                         unsigned int counter);

Get query result format descriptive syntax information

world :

world object

counter :

index into the list of query result formats

Returns :

description or NULL if counter is out of range

rasqal_generate_bnodeid_handler ()

char *              (*rasqal_generate_bnodeid_handler)  (rasqal_world *world,
                                                         void *user_data,
                                                         unsigned char *user_bnodeid);

User handler used with rasqal_world_set_generate_bnodeid_handler() to set method for generating a blank node ID.

world :

world arg

user_data :

user data given to

user_bnodeid :

user blank node ID string passed in

Returns :

blank node ID string or NULL on failure.

rasqal_world_set_generate_bnodeid_handler ()

int                 rasqal_world_set_generate_bnodeid_handler
                                                        (rasqal_world *world,
                                                         void *user_data,
                                                         rasqal_generate_bnodeid_handler handler);

Set the generate blank node ID handler function

Sets the function to generate blank node IDs. The handler is called with a pointer to the rasqal_world, the user_data pointer and a user_bnodeid which is the value of a user-provided blank node identifier (may be NULL). It can either be returned directly as the generated value when present or modified. The passed in value must be free()d if it is not used.

If handler is NULL, the default method is used

world :

rasqal_world object

user_data :

user data pointer for callback

handler :

generate blank ID callback function

Returns :

non-0 on failure

rasqal_world_set_default_generate_bnodeid_parameters ()

int                 rasqal_world_set_default_generate_bnodeid_parameters
                                                        (rasqal_world *world,
                                                         char *prefix,
                                                         int base);

Set default bnodeid generation parameters

Sets the parameters for the default algorithm used to generate blank node IDs. The default algorithm uses both prefix and base to generate a new identifier. The exact identifier generated is not guaranteed to be a strict concatenation of prefix and base but will use both parts.

For finer control of the generated identifiers, use rasqal_world_set_generate_bnodeid_handler()

If prefix is NULL, the default prefix is used (currently "bnodeid") If base is less than 1, it is initialised to 1.

world :

rasqal_world object

prefix :

prefix string

base :

integer base identifier

Returns :

non-0 on failure

rasqal_world_guess_query_results_format_name ()

const char *        rasqal_world_guess_query_results_format_name
                                                        (rasqal_world *world,
                                                         raptor_uri *uri,
                                                         const char *mime_type,
                                                         const char *buffer,
                                                         size_t len,
                                                         const unsigned char *identifier);

Guess a query results format name for content.

Find a query results format by scoring recognition of the syntax by a block of characters, the content identifier or a mime type. The content identifier is typically a filename or URI or some other identifier.

world :

world object

uri :

URI identifying the syntax (or NULL)

mime_type :

mime type identifying the content (or NULL)

buffer :

buffer of content to guess (or NULL)

len :

length of buffer

identifier :

identifier of content (or NULL)

Returns :

a query results format name or NULL if no guess could be made

rasqal_version_decimal

extern const unsigned int rasqal_version_decimal;

Rasqal version as a decimal number.

Format: major * 10000 + minor * 100 + release


rasqal_version_major

extern const unsigned int rasqal_version_major;

Rasqal major version number.


rasqal_version_minor

extern const unsigned int rasqal_version_minor;

Rasqal minor version number.


rasqal_version_release

extern const unsigned int rasqal_version_release;

Rasqal release version number.


rasqal_version_string

extern const char * const rasqal_version_string;

Rasqal version as a string.


rasqal_copyright_string

extern const char * const rasqal_copyright_string;

Copyright string (multiple lines).


rasqal_short_copyright_string

extern const char * const rasqal_short_copyright_string;

Short copyright string (one line).


rasqal_home_url_string

extern const char * const rasqal_home_url_string;

Rasqal home page URL.


rasqal_license_string

extern const char * const rasqal_license_string;

Rasqal license string.


enum rasqal_feature

typedef enum {
  RASQAL_FEATURE_NO_NET,
  RASQAL_FEATURE_RAND_SEED,
  RASQAL_FEATURE_LAST = RASQAL_FEATURE_RAND_SEED
} rasqal_feature;

Query features.

None currently defined.

RASQAL_FEATURE_NO_NET

Deny network requests.

RASQAL_FEATURE_RAND_SEED

Set rand() / rand_r() seed

RASQAL_FEATURE_LAST

Internal.

rasqal_language_name_check ()

int                 rasqal_language_name_check          (rasqal_world *world,
                                                         const char *name);

Check name of a query language.

world :

rasqal_world object

name :

the query language name

Returns :

non 0 if name is a known query language

rasqal_languages_enumerate ()

int                 rasqal_languages_enumerate          (rasqal_world *world,
                                                         unsigned int counter,
                                                         const char **name,
                                                         const char **label,
                                                         const unsigned char **uri_string);

deprecated: Use rasqal_world_get_query_language_description() instead.

Get information on query languages.

world :

rasqal_world object

counter :

index into the list of syntaxes

name :

pointer to store the name of the syntax (or NULL)

label :

pointer to store syntax readable label (or NULL)

uri_string :

pointer to store syntax URI string (or NULL)

Returns :

non 0 on failure of if counter is out of range

rasqal_alloc_memory ()

void *              rasqal_alloc_memory                 (size_t size);

Allocate memory inside rasqal.

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 rasqal_free_memory().

size :

size of memory to allocate

Returns :

the address of the allocated memory or NULL on failure

rasqal_calloc_memory ()

void *              rasqal_calloc_memory                (size_t nmemb,
                                                         size_t size);

Allocate zeroed array of items inside rasqal.

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 rasqal_free_memory().

nmemb :

number of members

size :

size of item

Returns :

the address of the allocated memory or NULL on failure

rasqal_free_memory ()

void                rasqal_free_memory                  (void *ptr);

Free memory allocated inside rasqal.

Some systems require memory allocated in a library to be deallocated in that library. This function allows memory allocated by rasqal to be freed.

ptr :

memory pointer

rasqal_feature_from_uri ()

rasqal_feature      rasqal_feature_from_uri             (rasqal_world *world,
                                                         raptor_uri *uri);

Turn a feature URI into an feature enum.

The allowed feature URIs are available via rasqal_features_enumerate().

world :

rasqal_world object

uri :

feature URI

Returns :

< 0 if the feature is unknown

rasqal_feature_value_type ()

int                 rasqal_feature_value_type           (const rasqal_feature feature);

Get the type of a features.

The type of the feature is 0=integer , 1=string. Other values are undefined. Most features are integer values and use rasqal_query_set_feature rasqal_query_get_feature()

feature :

rasqal query feature

Returns :

the type of the feature or <0 if feature is unknown

rasqal_features_enumerate ()

int                 rasqal_features_enumerate           (rasqal_world *world,
                                                         const rasqal_feature feature,
                                                         const char **name,
                                                         raptor_uri **uri,
                                                         const char **label);

Get list of rasqal features.

If uri is not NULL, a pointer to a new raptor_uri is returned that must be freed by the caller with raptor_free_uri().

world :

rasqal_world object

feature :

feature enumeration (0+)

name :

pointer to store feature short name (or NULL)

uri :

pointer to store feature URI (or NULL)

label :

pointer to feature label (or NULL)

Returns :

0 on success, <0 on failure, >0 if feature is unknown

rasqal_get_feature_count ()

unsigned int        rasqal_get_feature_count            (void);

Get the count of features defined.

This is prefered to the compile time-only symbol RASQAL_FEATURE_LAST and returns a count of the number of features which is RASQAL_FEATURE_LAST+1.

Returns :

count of features in the rasqal_feature enumeration

RASQAL_DEPRECATED

#define RASQAL_DEPRECATED __attribute__((deprecated))

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.


RASQAL_VERSION

#define RASQAL_VERSION 934

Rasqal library version number

Format: major * 10000 + minor * 100 + release


RASQAL_VERSION_MAJOR

#define RASQAL_VERSION_MAJOR 0

Rasqal library major version


RASQAL_VERSION_MINOR

#define RASQAL_VERSION_MINOR 9

Rasqal library minor version


RASQAL_VERSION_RELEASE

#define RASQAL_VERSION_RELEASE 34

Rasqal library release


RASQAL_VERSION_STRING

#define RASQAL_VERSION_STRING "0.9.34"

Rasqal library version string


RASQAL_RAPTOR_VERSION

#define RASQAL_RAPTOR_VERSION 20015

Version of Raptor that Rasqal was configured against.



Navigation: Redland Home Page

Copyright 2000-2014 Dave Beckett