## 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);
    raptor_world *      rasqal_world_get_raptor             (rasqal_world *world);
    void                rasqal_world_set_raptor             (rasqal_world *world,
                                                             raptor_world *raptor_world_ptr);
    int                 rasqal_world_set_generate_bnodeid_handler
                                                            (rasqal_world *world,
                                                             void *user_data,
                                                             rasqal_generate_bnodeid_handler2 handler);
    int                 rasqal_world_set_default_generate_bnodeid_parameters
                                                            (rasqal_world *world,
                                                             char *prefix,
                                                             int base);
    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;
    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,
                                                             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.

`world` : | rasqal_world object
`user_data` : | user data for log handler function
`handler` : | log handler function

### 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_set_generate_bnodeid_handler ()

    int                 rasqal_world_set_generate_bnodeid_handler
                                                            (rasqal_world *world,
                                                             void *user_data,
                                                             rasqal_generate_bnodeid_handler2 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

If set, this overrides any bnodeid handler set via `rasqal_query_set_generate_bnodeid_handler()`.

`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_version_decimal

    extern const unsigned int rasqal_version_decimal;

Library full version as a decimal integer.

See also rasqal_version_string.

### rasqal_version_major

    extern const unsigned int rasqal_version_major;

Library major version number as a decimal integer.

### rasqal_version_minor

    extern const unsigned int rasqal_version_minor;

Library minor version number as a decimal integer.

### rasqal_version_release

    extern const unsigned int rasqal_version_release;

Library release version number as a decimal integer.

### enum rasqal_feature

    typedef enum {
      RASQAL_FEATURE_NO_NET,
      RASQAL_FEATURE_LAST = RASQAL_FEATURE_NO_NET
    } rasqal_feature;

Query features.

None currently defined.

`RASQAL_FEATURE_NO_NET` | Deny network requests.
`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,
                                                             unsigned char **uri_string);

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

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 921

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 21

Rasqal library release

### RASQAL_VERSION_STRING

    #define RASQAL_VERSION_STRING "0.9.21"

Rasqal library version string

### RASQAL_RAPTOR_VERSION

    #define RASQAL_RAPTOR_VERSION 10901

Version of Raptor that Rasqal was configured against.