## section-world

section-world

## Functions

#define | raptor_new_world
int | raptor_world_open ()
void | raptor_free_world ()
int | raptor_world_set_flag ()
int | raptor_world_set_libxslt_security_preferences ()
int | raptor_world_set_log_handler ()
const raptor_syntax_description * | raptor_world_get_parser_description ()
int | raptor_world_is_parser_name ()
const char * | raptor_world_guess_parser_name ()
const raptor_syntax_description * | raptor_world_get_serializer_description ()
int | raptor_world_is_serializer_name ()
unsigned char * | raptor_world_generate_bnodeid ()
void | raptor_world_set_generate_bnodeid_handler ()
void | raptor_world_set_generate_bnodeid_parameters ()
int | raptor_world_get_parsers_count ()
int | raptor_world_get_serializers_count ()

## Types and Values

typedef | raptor_world
enum | raptor_world_flag

## Description

## Functions

### 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()`.

#### Parameters

version_decimal | raptor version as a decimal integer as defined by the macro RAPTOR_VERSION and static int raptor_version_decimal |

#### 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.

#### Parameters

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.

#### Parameters

world | raptor_world object |

### 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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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 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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

world | raptor_world 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

#### Parameters

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.

#### Parameters

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

### raptor_world_get_parsers_count ()

    int
    raptor_world_get_parsers_count (raptor_world *world);

Get number of parsers

#### Parameters

world | world object |

#### Returns

number of parsers or <0 on failure

### raptor_world_get_serializers_count ()

    int
    raptor_world_get_serializers_count (raptor_world *world);

Get number of serializers

#### Parameters

world | world object |

#### Returns

number of serializers or <0 on failure

## Types and Values

### raptor_world

    typedef struct raptor_world_s raptor_world;

Raptor world class.

### enum 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.

#### Members

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.