General

## General General — General library constants and utility functions |

## Synopsis

    extern              const unsigned int raptor_version_major;
    extern              const unsigned int raptor_version_minor;
    extern              const unsigned int raptor_version_release;
    extern              const unsigned int raptor_version_decimal;
    void                (*raptor_simple_message_handler)    (void *user_data,
                                                             const char *message,
                                                             ...);
    void                (*raptor_message_handler)           (void *user_data,
                                                             raptor_locator *locator,
                                                             const char *message);
    void                (*raptor_statement_handler)         (void *user_data,
                                                             const raptor_statement *statement);
    int                 raptor_parsers_enumerate            (unsigned int counter,
                                                             const char **name,
                                                             const char **label);
    int                 raptor_syntaxes_enumerate           (unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const char **mime_type,
                                                             unsigned char **uri_string);
    int                 raptor_syntax_name_check            (const char *name);
    const char*         raptor_guess_parser_name            (raptor_uri *uri,
                                                             const char *mime_type,
                                                             unsigned char *buffer,
                                                             size_t len,
                                                             unsigned char *identifier);
    int                 raptor_serializers_enumerate        (unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const char **mime_type,
                                                             unsigned char **uri_string);
    int                 raptor_serializer_syntax_name_check (const char *name);
    int                 raptor_print_ntriples_string        (FILE *stream,
                                                             unsigned char *string,
                                                             const char delim);
    unsigned char*      raptor_ntriples_string_as_utf8_string
                                                            (raptor_parser *rdf_parser,
                                                             unsigned char *src,
                                                             int len,
                                                             size_t *dest_lenp);
    const char*         raptor_ntriples_term_as_string      (raptor_ntriples_term_type term);
    char*               raptor_vsnprintf                    (const char *message);
    enum                raptor_log_level;
                        raptor_message_handler_closure;
                        raptor_error_handlers;
    void                raptor_error_handlers_init          (raptor_error_handlers *error_handlers);
    void                raptor_set_libxml_flags             (int flags);
    void                raptor_set_libxslt_security_preferences
                                                            (void *security_preferences);

## Description

How to get access to version numbers, set message and error handlers, list the parsed and serialized syntaxes provided in the library and various other utility functions.

## Details

### raptor_version_major

    extern const unsigned int raptor_version_major;

Library major version number as a decimal integer.

### raptor_version_minor

    extern const unsigned int raptor_version_minor;

Library minor version number as a decimal integer.

### raptor_version_release

    extern const unsigned int raptor_version_release;

Library release version number as a decimal integer.

### raptor_version_decimal

    extern const unsigned int raptor_version_decimal;

Library full version as a decimal integer.

See also raptor_version_string.

### raptor_simple_message_handler ()

    void                (*raptor_simple_message_handler)    (void *user_data,
                                                             const char *message,
                                                             ...);

Simple message handler function.

Used by multiple functions including `raptor_xml_escape_string()`, `raptor_iostream_write_xml_escaped_string()`, `raptor_new_qname()`, `raptor_qname_string_to_uri()`, `raptor_new_namespaces()`, `raptor_namespaces_init()`, `raptor_iostream_write_xml_element()`, `raptor_new_xml_writer()`.

`user_data` : | user data
`message` : | message to report
`...` : | arguments for message

### raptor_message_handler ()

    void                (*raptor_message_handler)           (void *user_data,
                                                             raptor_locator *locator,
                                                             const char *message);

Message with location handler function.

Used during parsing and serializing for errors and warnings that may include location information. Multiple handlers may be set for parsers and serializers by `raptor_set_fatal_error_handler()`, `raptor_set_error_handler()`, `raptor_set_warning_handler()`, `raptor_serializer_set_error_handler()` and `raptor_serializer_set_warning_handler()`.

Also used by `raptor_www_set_error_handler()` for location-based errors in WWW retrieval.

`user_data` : | user data
`locator` : | location associated with message or NULL
`message` : | message to report

### raptor_statement_handler ()

    void                (*raptor_statement_handler)         (void *user_data,
                                                             const raptor_statement *statement);

Statement (triple) reporting handler function.

`user_data` : | user data
`statement` : | statement to report

### raptor_parsers_enumerate ()

    int                 raptor_parsers_enumerate            (unsigned int counter,
                                                             const char **name,
                                                             const char **label);

Get list of syntax parsers.

`counter` : | index to list of parsers
`name` : | pointer to store syntax name (or NULL)
`label` : | pointer to store syntax label (or NULL)
Returns : | non 0 on failure of if counter is out of range

### raptor_syntaxes_enumerate ()

    int                 raptor_syntaxes_enumerate           (unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const char **mime_type,
                                                             unsigned char **uri_string);

Get information on syntaxes.

`raptor_init()` MUST have been called before calling this function. Use `raptor_syntaxes_enumerate_v2()` if using raptor_world APIs.

`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)
`mime_type` : | pointer to store syntax MIME Type (or NULL)
`uri_string` : | pointer to store syntax URI string (or NULL)
Returns : | non 0 on failure of if counter is out of range

### raptor_syntax_name_check ()

    int                 raptor_syntax_name_check            (const char *name);

Check name of a parser.

`raptor_init()` MUST have been called before calling this function. Use `raptor_syntax_name_check_v2()` if using raptor_world APIs.

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

### raptor_guess_parser_name ()

    const char*         raptor_guess_parser_name            (raptor_uri *uri,
                                                             const char *mime_type,
                                                             unsigned char *buffer,
                                                             size_t len,
                                                             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.

`raptor_init()` MUST have been called before calling this function. Use `raptor_guess_parser_name_v2()` if using raptor_world APIs.

`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_serializers_enumerate ()

    int                 raptor_serializers_enumerate        (unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const char **mime_type,
                                                             unsigned char **uri_string);

Get information on syntax serializers.

`raptor_init()` MUST have been called before calling this function. Use `raptor_serializers_enumerate_v2()` if using raptor_world APIs.

`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)
`mime_type` : | pointer to store syntax MIME Type (or NULL)
`uri_string` : | pointer to store syntax URI string (or NULL)
Returns : | non 0 on failure of if counter is out of range

### raptor_serializer_syntax_name_check ()

    int                 raptor_serializer_syntax_name_check (const char *name);

Check name of a serializer.

`raptor_init()` MUST have been called before calling this function. Use `raptor_serializer_syntax_name_check_v2()` if using raptor_world APIs.

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

### raptor_print_ntriples_string ()

    int                 raptor_print_ntriples_string        (FILE *stream,
                                                             unsigned char *string,
                                                             const char delim);

Print an UTF-8 string using N-Triples escapes.

`stream` : | FILE* stream to print to
`string` : | UTF-8 string to print
`delim` : | Delimiter character for string (such as ") or \0 for no delim escaping.
Returns : | non-0 on failure such as bad UTF-8 encoding.

### raptor_ntriples_string_as_utf8_string ()

    unsigned char*      raptor_ntriples_string_as_utf8_string
                                                            (raptor_parser *rdf_parser,
                                                             unsigned char *src,
                                                             int len,
                                                             size_t *dest_lenp);

### Warning

`raptor_ntriples_string_as_utf8_string` is deprecated and should not be used in newly-written code.

Turn an N-Triples string with escapes into a UTF-8 string.

`deprecated`: This requires use of parser internals and was never in the public API header.

`rdf_parser` : | parser object
`src` : | data to read from
`len` : | size of data
`dest_lenp` : | pointer to length of destination (out) or NULL
Returns : | a new UTF-8 string

### raptor_ntriples_term_as_string ()

    const char*         raptor_ntriples_term_as_string      (raptor_ntriples_term_type term);

### Warning

`raptor_ntriples_term_as_string` is deprecated and should not be used in newly-written code.

Get a label for a raptor_ntriples_term_type.

`deprecated`: an internal debug function, do not use.

`term` : | N-Triples term.
Returns : | a pointer to a constant string.

### raptor_vsnprintf ()

    char*               raptor_vsnprintf                    (const char *message);

Format output for a variable arguments list.

This is a wrapper around system versions of vsnprintf with different call and return conventions.

`message` : | printf-style format string
Returns : | a newly allocated string as the format result or NULL on failure

### enum raptor_log_level

    typedef enum {
      RAPTOR_LOG_LEVEL_NONE,
      RAPTOR_LOG_LEVEL_FATAL,
      RAPTOR_LOG_LEVEL_ERROR,
      RAPTOR_LOG_LEVEL_WARNING,
      /* RAPTOR V2 FIXME - this enum list cannot be extended before V2
       * API is released else binary compatibility will be broken in the
       * #raptor_error_handlers structure - it causes an array to grow.
       */
      RAPTOR_LOG_LEVEL_LAST=RAPTOR_LOG_LEVEL_WARNING
    } raptor_log_level;

Log levels

`RAPTOR_LOG_LEVEL_NONE` | Internal
`RAPTOR_LOG_LEVEL_FATAL` | Fatal error message
`RAPTOR_LOG_LEVEL_ERROR` | Error message
`RAPTOR_LOG_LEVEL_WARNING` | Warning message
`RAPTOR_LOG_LEVEL_LAST` | Internal

### raptor_message_handler_closure

    typedef struct {
      void *user_data;
      raptor_message_handler handler;
    } raptor_message_handler_closure;

The combination of a message handler and the user data to send to it.

void *`user_data`; | user data for handler invocation
raptor_message_handler `handler`; | handler function

### raptor_error_handlers

    typedef struct {
      unsigned int magic;

      raptor_locator* locator;

      /* size of handlers array */
      raptor_log_level last_log_level;

      raptor_message_handler_closure handlers[RAPTOR_LOG_LEVEL_LAST+1];

      /* Raptor V2 FIXME - this should NOT be at the end of the structure
       * since it prevents increasing the size of the @handlers array but
       * it it is here to preserve Raptor V1 ABI.
       */
      raptor_world *world;
    } raptor_error_handlers;

Error handlers structure

unsigned int `magic`; | magic value - must use `raptor_error_handlers_init()` to set this
raptor_locator *`locator`; | raptor locator of the error
raptor_log_level `last_log_level`; | number of log levels; size of `handlers` arrays
raptor_message_handler_closure `handlers`[RAPTOR_LOG_LEVEL_LAST+1]; | user handlers per log level
raptor_world *`world`; | raptor_world object

### raptor_error_handlers_init ()

    void                raptor_error_handlers_init          (raptor_error_handlers *error_handlers);

Initialize raptor_error_handlers object statically.

`raptor_init()` MUST have been called before calling this function. Use `raptor_error_handlers_init_v2()` if using raptor_world APIs.

`error_handlers` : | error handlers object

### raptor_set_libxml_flags ()

    void                raptor_set_libxml_flags             (int flags);

Set common libxml library flags

If libxml is compiled into the library, `flags` is a bitmask taking an OR of values defined in raptor_libxml_flags

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

`flags` : | flags

### raptor_set_libxslt_security_preferences ()

    void                raptor_set_libxslt_security_preferences
                                                            (void *security_preferences);

Set libxslt security preferences policy object

The `security_preferences` object will NOT become owned by Raptor

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 libxslt is not compiled in, the object set here is not used.

`security_preferences` : | security preferences (an xsltSecurityPrefsPtr)