Initialisation

## Initialisation Initialisation — Library startup, shutdown and configuration. |

## Synopsis

    typedef             raptor_world;
    #define             raptor_new_world
    int                 raptor_world_open                   (raptor_world *world);
    void                raptor_free_world                   (raptor_world *world);
    enum                raptor_world_flag;
    int                 raptor_world_set_flag               (raptor_world *world,
                                                             raptor_world_flag flag,
                                                             int value);
    int                 raptor_world_set_libxslt_security_preferences
                                                            (raptor_world *world,
                                                             void *security_preferences);
    int                 raptor_world_set_log_handler        (raptor_world *world,
                                                             void *user_data,
                                                             raptor_log_handler handler);
    const raptor_syntax_description * raptor_world_get_parser_description
                                                            (raptor_world *world,
                                                             unsigned int counter);
    int                 raptor_world_is_parser_name         (raptor_world *world,
                                                             const char *name);
    const char *        raptor_world_guess_parser_name      (raptor_world *world,
                                                             raptor_uri *uri,
                                                             const char *mime_type,
                                                             const unsigned char *buffer,
                                                             size_t len,
                                                             const unsigned char *identifier);
    const raptor_syntax_description * raptor_world_get_serializer_description
                                                            (raptor_world *world,
                                                             unsigned int counter);
    int                 raptor_world_is_serializer_name     (raptor_world *world,
                                                             const char *name);
    unsigned char *     raptor_world_generate_bnodeid       (raptor_world *world);
    void                raptor_world_set_generate_bnodeid_handler
                                                            (raptor_world *world,
                                                             void *user_data,
                                                             raptor_generate_bnodeid_handler handler);
    void                raptor_world_set_generate_bnodeid_parameters
                                                            (raptor_world *world,
                                                             char *prefix,
                                                             int base);

## Description

How to initialise and terminate the library, set library-wide configuration flags and options.

## Details

### raptor_world

    typedef struct raptor_world_s raptor_world;

Raptor world class.

### raptor_new_world

    #define raptor_new_world() raptor_new_world_internal(RAPTOR_VERSION)

Allocate a new raptor_world object.

Allocation of the world and initialization are decoupled to allow changing settings on the world object before init.

Settings and configuration of the world may be made after creating the object and before the world is initialized using methods such as `raptor_world_set_flag()`, `raptor_world_set_log_handler()`, `raptor_world_set_generate_bnodeid_handler()`. Some configuration may not be changed after initialization.

The raptor_world is initialized with `raptor_world_open()`.

Returns : | uninitialized raptor_world object or NULL on failure

### raptor_world_open ()

    int                 raptor_world_open                   (raptor_world *world);

Initialise the raptor library.

Initializes a raptor_world object created by `raptor_new_world()`. Allocation and initialization are decoupled to allow changing settings on the world object before init.

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

`world` : | raptor_world object
Returns : | non-0 on failure

### raptor_free_world ()

    void                raptor_free_world                   (raptor_world *world);

Terminate the raptor library.

Destroys the raptor_world object and all related information.

`world` : | raptor_world object

### enum raptor_world_flag

    typedef enum {
      RAPTOR_WORLD_FLAG_LIBXML_GENERIC_ERROR_SAVE = 1,
      RAPTOR_WORLD_FLAG_LIBXML_STRUCTURED_ERROR_SAVE = 2,
      RAPTOR_WORLD_FLAG_URI_INTERNING = 3,
      RAPTOR_WORLD_FLAG_WWW_SKIP_INIT_FINISH = 4
    } raptor_world_flag;

Raptor world flags

These are used by `raptor_world_set_flags()` to control raptor-wide options across classes. These must be set before `raptor_world_open()` is called explicitly or implicitly (by creating a raptor object). There is no enumeration function for these flags because they are not user options and must be set before the library is initialised. For similar reasons, there is no get function.

If any libxml handler saving/restoring is enabled, any existing handler and context is saved before parsing and restored afterwards. Otherwise, no saving/restoring is performed.

`RAPTOR_WORLD_FLAG_LIBXML_GENERIC_ERROR_SAVE` | if set (non-0 value) - save/restore the libxml generic error handler when raptor library initializes (default set)
`RAPTOR_WORLD_FLAG_LIBXML_STRUCTURED_ERROR_SAVE` | if set (non-0 value) - save/restore the libxml structured error handler when raptor library terminates (default set)
`RAPTOR_WORLD_FLAG_URI_INTERNING` | if set (non-0 value) - each URI is saved interned in-memory and reused (default set)
`RAPTOR_WORLD_FLAG_WWW_SKIP_INIT_FINISH` | if set (non-0 value) the raptor will neither initialise or terminate the lower level WWW library. Usually in raptor initialising either curl_global_init (for libcurl) are called and in raptor cleanup, curl_global_cleanup is called. This flag allows the application finer control over these libraries such as setting other global options or potentially calling and terminating raptor several times. It does mean that applications which use this call must do their own extra work in order to allocate and free all resources to the system.

### raptor_world_set_flag ()

    int                 raptor_world_set_flag               (raptor_world *world,
                                                             raptor_world_flag flag,
                                                             int value);

Set library-wide configuration

This function is used to control raptor-wide options across classes. These options must be set before `raptor_world_open()` is called explicitly or implicitly (by creating a raptor object). There is no enumeration function for these flags because they are not user options and must be set before the library is initialised. For similar reasons, there is no get function.

See the raptor_world_flags documentation for full details of what the flags mean.

`world` : | world
`flag` : | flag
`value` : | value
Returns : | 0 on success, non-0 on failure: <0 on errors (-1 if flag is unknown, -2 if value is illegal) and >0 if world is already opened

### raptor_world_set_libxslt_security_preferences ()

    int                 raptor_world_set_libxslt_security_preferences
                                                            (raptor_world *world,
                                                             void *security_preferences);

Set libxslt security preferences policy object

The `security_preferences` object will NOT become owned by raptor_world.

If libxslt is compiled into the library, `security_preferences` should be an xsltSecurityPrefsPtr and will be used to call `xsltSetCtxtSecurityPrefs()` when an XSLT engine is initialised. If `security_preferences` is NULL, this will disable all raptor's calls to `xsltSetCtxtSecurityPrefs()`.

If libxslt is not compiled in, the object set here is not used.

`world` : | world
`security_preferences` : | security preferences (an xsltSecurityPrefsPtr) or NULL
Returns : | 0 on success, non-0 on failure: <0 on errors and >0 if world is already opened

### raptor_world_set_log_handler ()

    int                 raptor_world_set_log_handler        (raptor_world *world,
                                                             void *user_data,
                                                             raptor_log_handler handler);

Set the message (error, warning, info) handling function.

The function will receive callbacks when messages are generated

`world` : | world object
`user_data` : | user data to pass to function
`handler` : | pointer to the function
Returns : | non-0 on failure

### raptor_world_get_parser_description ()

    const raptor_syntax_description * raptor_world_get_parser_description
                                                            (raptor_world *world,
                                                             unsigned int counter);

Get parser descriptive syntax information

`world` : | world object
`counter` : | index into the list of parsers
Returns : | description or NULL if counter is out of range

### raptor_world_is_parser_name ()

    int                 raptor_world_is_parser_name         (raptor_world *world,
                                                             const char *name);

Check the name of a parser is known.

`world` : | world object
`name` : | the syntax name
Returns : | non 0 if name is a known syntax name

### raptor_world_guess_parser_name ()

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

Guess a parser name for content.

Find a parser 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.

If the guessing finds only low scores, NULL will be returned.

`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 parser name or NULL if no guess could be made

### raptor_world_get_serializer_description ()

    const raptor_syntax_description * raptor_world_get_serializer_description
                                                            (raptor_world *world,
                                                             unsigned int counter);

Get serializer descriptive syntax information

`world` : | world object
`counter` : | index into the list of serializers
Returns : | description or NULL if counter is out of range

### raptor_world_is_serializer_name ()

    int                 raptor_world_is_serializer_name     (raptor_world *world,
                                                             const char *name);

Check name of a serializer.

`world` : | raptor_world object
`name` : | the syntax name
Returns : | non 0 if name is a known syntax name

### raptor_world_generate_bnodeid ()

    unsigned char *     raptor_world_generate_bnodeid       (raptor_world *world);

Generate an new blank node ID

`world` : | raptor_parser parser object
Returns : | newly allocated generated ID or NULL on failure

### raptor_world_set_generate_bnodeid_handler ()

    void                raptor_world_set_generate_bnodeid_handler
                                                            (raptor_world *world,
                                                             void *user_data,
                                                             raptor_generate_bnodeid_handler handler);

Set the generate ID handler function.

Sets the function to generate IDs for the library. The handler is called with the `user_data` parameter.

The final argument of the callback method is user_bnodeid, the value of the rdf:nodeID attribute that the user provided if any (or 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` : | raptor_world world object
`user_data` : | user data pointer for callback
`handler` : | generate ID callback function

### raptor_world_set_generate_bnodeid_parameters ()

    void                raptor_world_set_generate_bnodeid_parameters
                                                            (raptor_world *world,
                                                             char *prefix,
                                                             int base);

Set default ID generation parameters.

Sets the parameters for the default algorithm used to generate 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. The `prefix` parameter is copied to generate an ID.

For finer control of the generated identifiers, use `raptor_world_set_generate_bnodeid_handler()`.

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

`world` : | raptor_world object
`prefix` : | prefix string
`base` : | integer base identifier