General
3
RAPTOR Library

# General

General library startup, shutdown 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_init                         (void);
    void                raptor_finish                       (void);
    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);

## Description

How to initialise and terminate the library, 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_init ()

    void                raptor_init                         (void);

Initialise the raptor library.

This function MUST be called before using any of the raptor APIs.

### raptor_finish ()

    void                raptor_finish                       (void);

Terminate the raptor library.

Cleans up state of the library. If called, must be used after all other objects are destroyed with their destructor.

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

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

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

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

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

`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);

`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);

`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_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_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_error_handlers_init ()

    void                raptor_error_handlers_init          (raptor_error_handlers *error_handlers);

Initialize raptor_error_handlers object statically.

`error_handlers` :

  error handlers object