I/O Stream

I/O Stream — Providing streaming I/O writing to files, strings or user code.

Synopsis

typedef             raptor_iostream;
int                 (*raptor_iostream_init_func)        (void *context);
void                (*raptor_iostream_finish_func)      (void *context);
int                 (*raptor_iostream_write_byte_func)  (void *context,
                                                         const int byte);
int                 (*raptor_iostream_write_bytes_func) (void *context,
                                                         const void *ptr,
                                                         size_t size,
                                                         size_t nmemb);
int                 (*raptor_iostream_write_end_func)   (void *context);
int                 (*raptor_iostream_read_bytes_func)  (void *context,
                                                         void *ptr,
                                                         size_t size,
                                                         size_t nmemb);
int                 (*raptor_iostream_read_eof_func)    (void *context);
                    raptor_iostream_handler;
raptor_iostream *   raptor_new_iostream_from_handler    (raptor_world *world,
                                                         void *user_data,
                                                         const raptor_iostream_handler * const handler);
raptor_iostream *   raptor_new_iostream_from_sink       (raptor_world *world);
raptor_iostream *   raptor_new_iostream_from_filename   (raptor_world *world,
                                                         const char *filename);
raptor_iostream *   raptor_new_iostream_from_file_handle
                                                        (raptor_world *world,
                                                         FILE *handle);
raptor_iostream *   raptor_new_iostream_from_string     (raptor_world *world,
                                                         void *string,
                                                         size_t length);
raptor_iostream *   raptor_new_iostream_to_sink         (raptor_world *world);
raptor_iostream *   raptor_new_iostream_to_filename     (raptor_world *world,
                                                         const char *filename);
raptor_iostream *   raptor_new_iostream_to_file_handle  (raptor_world *world,
                                                         FILE *handle);
raptor_iostream *   raptor_new_iostream_to_string       (raptor_world *world,
                                                         void **string_p,
                                                         size_t *length_p,
                                                         raptor_data_malloc_handler const malloc_handler);
void                raptor_free_iostream                (raptor_iostream *iostr);
int                 raptor_iostream_hexadecimal_write   (unsigned int integer,
                                                         int width,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_read_bytes          (void *ptr,
                                                         size_t size,
                                                         size_t nmemb,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_read_eof            (raptor_iostream *iostr);
unsigned long       raptor_iostream_tell                (raptor_iostream *iostr);
int                 raptor_iostream_counted_string_write
                                                        (const void *string,
                                                         size_t len,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_decimal_write       (int integer,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_string_write        (const void *string,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_write_byte          (const int byte,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_write_bytes         (const void *ptr,
                                                         size_t size,
                                                         size_t nmemb,
                                                         raptor_iostream *iostr);
int                 raptor_iostream_write_end           (raptor_iostream *iostr);
int                 raptor_bnodeid_ntriples_write       (const unsigned char *bnodeid,
                                                         size_t len,
                                                         raptor_iostream *iostr);
enum                raptor_escaped_write_bitflags;
int                 raptor_string_escaped_write         (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);
int                 raptor_term_escaped_write           (const raptor_term *term,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);
int                 raptor_uri_escaped_write            (raptor_uri *uri,
                                                         raptor_uri *base_uri,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);
int                 raptor_string_ntriples_write        (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         raptor_iostream *iostr);
int                 raptor_string_python_write          (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         unsigned int mode,
                                                         raptor_iostream *iostr);

Description

An class providing an I/O writer abstraction that allows generating output that can be stored or passed on to system files, strings allocated in memory (usually via raptor_stringbuffer), system file handles (FILE*) or to a user function.

Details

raptor_iostream

raptor_iostream* raptor_iostream;

Raptor I/O Stream class


raptor_iostream_init_func ()

int                 (*raptor_iostream_init_func)        (void *context);

Handler function for raptor_iostream initialising.

context :

stream context data

Returns :

non-0 on failure.

raptor_iostream_finish_func ()

void                (*raptor_iostream_finish_func)      (void *context);

Handler function for raptor_iostream terminating.

context :

stream context data

raptor_iostream_write_byte_func ()

int                 (*raptor_iostream_write_byte_func)  (void *context,
                                                         const int byte);

Handler function for implementing raptor_iostream_write_byte().

context :

stream context data

byte :

byte to write

Returns :

non-0 on failure.

raptor_iostream_write_bytes_func ()

int                 (*raptor_iostream_write_bytes_func) (void *context,
                                                         const void *ptr,
                                                         size_t size,
                                                         size_t nmemb);

Handler function for implementing raptor_iostream_write_bytes().

context :

stream context data

ptr :

pointer to bytes to write

size :

size of item

nmemb :

number of items

Returns :

non-0 on failure.

raptor_iostream_write_end_func ()

int                 (*raptor_iostream_write_end_func)   (void *context);

Handler function for implementing raptor_iostream_write_end().

context :

stream context data

Returns :

non-0 on failure.

raptor_iostream_read_bytes_func ()

int                 (*raptor_iostream_read_bytes_func)  (void *context,
                                                         void *ptr,
                                                         size_t size,
                                                         size_t nmemb);

Handler function for implementing raptor_iostream_read_bytes().

context :

stream context data

ptr :

pointer to buffer to read into

size :

size of buffer

nmemb :

number of items

Returns :

number of items read, 0 or < size on EOF, <0 on failure

raptor_iostream_read_eof_func ()

int                 (*raptor_iostream_read_eof_func)    (void *context);

Handler function for implementing raptor_iostream_read_eof().

context :

stream context data

Returns :

non-0 if EOF

raptor_iostream_handler

typedef struct {
  int version;

  /* V1 functions */
  raptor_iostream_init_func         init;
  raptor_iostream_finish_func       finish;
  raptor_iostream_write_byte_func   write_byte;
  raptor_iostream_write_bytes_func  write_bytes;
  raptor_iostream_write_end_func    write_end;

  /* V2 functions */
  raptor_iostream_read_bytes_func   read_bytes;
  raptor_iostream_read_eof_func     read_eof;
} raptor_iostream_handler;

I/O stream implementation handler structure.

int version;

interface version. Presently 1 or 2.

raptor_iostream_init_func init;

initialisation handler - optional, called at most once (V1)

raptor_iostream_finish_func finish;

finishing handler - optional, called at most once (V1)

raptor_iostream_write_byte_func write_byte;

write byte handler - required (for writing) (V1)

raptor_iostream_write_bytes_func write_bytes;

write bytes handler - required (for writing) (V1)

raptor_iostream_write_end_func write_end;

write end handler - optional (for writing), called at most once (V1)

raptor_iostream_read_bytes_func read_bytes;

read bytes handler - required (for reading) (V2)

raptor_iostream_read_eof_func read_eof;

read EOF handler - required (for reading) (V2)

raptor_new_iostream_from_handler ()

raptor_iostream *   raptor_new_iostream_from_handler    (raptor_world *world,
                                                         void *user_data,
                                                         const raptor_iostream_handler * const handler);

Create a new iostream over a user-defined handler

world :

raptor_world object

user_data :

pointer to context information to pass in to calls

handler :

pointer to handler methods

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_from_sink ()

raptor_iostream *   raptor_new_iostream_from_sink       (raptor_world *world);

Create a new read iostream from a sink, returning no data.

Provides an I/O source that returns end of input immediately on reads, and throw away all writes. Same as raptor_new_iostream_to_sink()

world :

raptor world

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_from_filename ()

raptor_iostream *   raptor_new_iostream_from_filename   (raptor_world *world,
                                                         const char *filename);

Constructor - create a new iostream reading from a filename.

world :

raptor world

filename :

Input filename to open and read from

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_from_file_handle ()

raptor_iostream *   raptor_new_iostream_from_file_handle
                                                        (raptor_world *world,
                                                         FILE *handle);

Constructor - create a new iostream reading from a file_handle.

The handle must already be open for reading. NOTE: This does not fclose the handle when it is finished.

world :

raptor world

handle :

Input file_handle to open and read from

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_from_string ()

raptor_iostream *   raptor_new_iostream_from_string     (raptor_world *world,
                                                         void *string,
                                                         size_t length);

Constructor - create a new iostream reading from a string.

world :

raptor world

string :

pointer to string

length :

length of string

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_to_sink ()

raptor_iostream *   raptor_new_iostream_to_sink         (raptor_world *world);

Create a new write iostream to a sink, throwing away all data.

Provides an that throw away all writes and returns end of input immediately on reads. Same as raptor_new_iostream_from_sink()

world :

raptor_world object

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_to_filename ()

raptor_iostream *   raptor_new_iostream_to_filename     (raptor_world *world,
                                                         const char *filename);

Constructor - create a new iostream writing to a filename.

world :

raptor world

filename :

Output filename to open and write to

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_to_file_handle ()

raptor_iostream *   raptor_new_iostream_to_file_handle  (raptor_world *world,
                                                         FILE *handle);

Constructor - create a new iostream writing to a FILE*.

The handle must already be open for writing. NOTE: This does not fclose the handle when it is finished.

world :

raptor world

handle :

FILE* handle to write to

Returns :

new raptor_iostream object or NULL on failure

raptor_new_iostream_to_string ()

raptor_iostream *   raptor_new_iostream_to_string       (raptor_world *world,
                                                         void **string_p,
                                                         size_t *length_p,
                                                         raptor_data_malloc_handler const malloc_handler);

Constructor - create a new iostream writing to a string.

If malloc_handler is null, raptor will allocate it using it's own memory allocator. *string_p is set to NULL on failure (and *length_p to 0 if length_p is not NULL).

world :

raptor world

string_p :

pointer to location to hold string

length_p :

pointer to location to hold length of string (or NULL)

malloc_handler :

pointer to malloc() to use to make string (or NULL)

Returns :

new raptor_iostream object or NULL on failure

raptor_free_iostream ()

void                raptor_free_iostream                (raptor_iostream *iostr);

Destructor - destroy an iostream.

iostr :

iostream object

raptor_iostream_hexadecimal_write ()

int                 raptor_iostream_hexadecimal_write   (unsigned int integer,
                                                         int width,
                                                         raptor_iostream *iostr);

Write an integer in hexadecimal to the iostream.

Always 0-fills the entire field and writes in uppercase A-F

integer :

unsigned integer to format as hexadecimal

width :

field width

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_iostream_read_bytes ()

int                 raptor_iostream_read_bytes          (void *ptr,
                                                         size_t size,
                                                         size_t nmemb,
                                                         raptor_iostream *iostr);

Read bytes to the iostream.

ptr :

start of buffer to read objects into

size :

size of object

nmemb :

number of objects to read

iostr :

raptor iostream

Returns :

number of objects read, 0 or less than nmemb on EOF, <0 on failure

raptor_iostream_read_eof ()

int                 raptor_iostream_read_eof            (raptor_iostream *iostr);

Check if an read iostream has ended

iostr :

raptor read iostream

Returns :

non-0 if EOF (or not a read iostream)

raptor_iostream_tell ()

unsigned long       raptor_iostream_tell                (raptor_iostream *iostr);

Get the offset in the iostream.

iostr :

raptor iostream

Returns :

offset in iostream

raptor_iostream_counted_string_write ()

int                 raptor_iostream_counted_string_write
                                                        (const void *string,
                                                         size_t len,
                                                         raptor_iostream *iostr);

Write a counted string to the iostream.

string :

string

len :

string length

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_iostream_decimal_write ()

int                 raptor_iostream_decimal_write       (int integer,
                                                         raptor_iostream *iostr);

Write an integer in decimal to the iostream.

integer :

integer to format as decimal

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_iostream_string_write ()

int                 raptor_iostream_string_write        (const void *string,
                                                         raptor_iostream *iostr);

Write a NULL-terminated string to the iostream.

string :

string

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_iostream_write_byte ()

int                 raptor_iostream_write_byte          (const int byte,
                                                         raptor_iostream *iostr);

Write a byte to the iostream.

byte :

byte to write

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_iostream_write_bytes ()

int                 raptor_iostream_write_bytes         (const void *ptr,
                                                         size_t size,
                                                         size_t nmemb,
                                                         raptor_iostream *iostr);

Write bytes to the iostream.

ptr :

start of objects to write

size :

size of object

nmemb :

number of objects

iostr :

raptor iostream

Returns :

number of objects actually written, which may be less than nmemb. <0 on failure

raptor_iostream_write_end ()

int                 raptor_iostream_write_end           (raptor_iostream *iostr);

End writing to the iostream.

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_bnodeid_ntriples_write ()

int                 raptor_bnodeid_ntriples_write       (const unsigned char *bnodeid,
                                                         size_t len,
                                                         raptor_iostream *iostr);

Write a blank node ID in a form legal for N-Triples with _: prefix

bnodeid :

bnode ID to write

len :

length of bnode ID

iostr :

raptor_iostream to write to

Returns :

non-0 on failure

enum raptor_escaped_write_bitflags

typedef enum {
  RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF      = 1,
  RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU    = 2,
  RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8               = 4,
  RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES = 8,

  /* N-Triples - favour writing \u, \U over UTF8 */
  RAPTOR_ESCAPED_WRITE_NTRIPLES_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU | RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF,
  RAPTOR_ESCAPED_WRITE_NTRIPLES_URI     = RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES,

  /* SPARQL literal: allows raw UTF8 for printable literals */
  RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8,

  /* SPARQL long literal: no BS-escapes allowed */
  RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8,

  /* SPARQL uri: have to escape certain characters */
  RAPTOR_ESCAPED_WRITE_SPARQL_URI     = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8 | RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES,

  /* Turtle (2013) escapes are like SPARQL */
  RAPTOR_ESCAPED_WRITE_TURTLE_URI     = RAPTOR_ESCAPED_WRITE_SPARQL_URI,
  RAPTOR_ESCAPED_WRITE_TURTLE_LITERAL = RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL,
  RAPTOR_ESCAPED_WRITE_TURTLE_LONG_LITERAL = RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL,

  /* JSON literals: \b \f \t \r \n and \u \U */
  RAPTOR_ESCAPED_WRITE_JSON_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU | RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF
} raptor_escaped_write_bitflags;

Bit flags for raptor_string_escaped_write() and friends.

RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF

Allow \b \f,

RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU

ALlow \t \n \r \u

RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8

Allow UTF-8 for printable U *

RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES

Must escape x00-x20<>\"{}|^` in URIs

RAPTOR_ESCAPED_WRITE_NTRIPLES_LITERAL

N-Triples literal

RAPTOR_ESCAPED_WRITE_NTRIPLES_URI

N-Triples URI

RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL

SPARQL literal: allows raw UTF8 for printable literals

RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL

SPARQL long literal: no BS-escapes allowed

RAPTOR_ESCAPED_WRITE_SPARQL_URI

SPARQL uri: have to escape certain characters

RAPTOR_ESCAPED_WRITE_TURTLE_URI

Turtle 2013 URIs (like SPARQL)

RAPTOR_ESCAPED_WRITE_TURTLE_LITERAL

Turtle 2013 literals (like SPARQL)

RAPTOR_ESCAPED_WRITE_TURTLE_LONG_LITERAL

Turtle 2013 long literals (like SPARQL)

RAPTOR_ESCAPED_WRITE_JSON_LITERAL

JSON literals: \b \f \t \r \n and \u \U

raptor_string_escaped_write ()

int                 raptor_string_escaped_write         (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);

Write a UTF-8 string formatted using different escapes to a raptor_iostream

Supports writing escapes in the Python, N-Triples, Turtle, JSON, mKR, SPARQL styles to an iostream.

string :

UTF-8 string to write

len :

length of UTF-8 string

delim :

Terminating delimiter character for string (such as " or >) or \0 for no escaping.

flags :

bit flags - see raptor_escaped_write_bitflags

iostr :

raptor_iostream to write to

Returns :

non-0 on failure such as bad UTF-8 encoding.

raptor_term_escaped_write ()

int                 raptor_term_escaped_write           (const raptor_term *term,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);

Write a raptor_term formatted with escapes to a raptor_iostream

term :

term to write

flags :

bit flags - see raptor_escaped_write_bitflags

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_uri_escaped_write ()

int                 raptor_uri_escaped_write            (raptor_uri *uri,
                                                         raptor_uri *base_uri,
                                                         unsigned int flags,
                                                         raptor_iostream *iostr);

Write a raptor_uri formatted with escapes to a raptor_iostream

uri :

uri to write

base_uri :

base uri to write relative to (or NULL)

flags :

bit flags - see raptor_escaped_write_bitflags

iostr :

raptor iostream

Returns :

non-0 on failure

raptor_string_ntriples_write ()

int                 raptor_string_ntriples_write        (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         raptor_iostream *iostr);

Write an UTF-8 string using N-Triples escapes to an iostream.

string :

UTF-8 string to write

len :

length of UTF-8 string

delim :

Terminating delimiter character for string (such as " or >) or \0 for no escaping.

iostr :

raptor_iostream to write to

Returns :

non-0 on failure such as bad UTF-8 encoding.

raptor_string_python_write ()

int                 raptor_string_python_write          (const unsigned char *string,
                                                         size_t len,
                                                         const char delim,
                                                         unsigned int mode,
                                                         raptor_iostream *iostr);

Write a UTF-8 string using Python-style escapes (N-Triples, Turtle, JSON, mKR) to a raptor_iostream

Deprecated: use raptor_string_escaped_write() where the features requested are bits that can be individually chosen.

string :

UTF-8 string to write

len :

length of UTF-8 string

delim :

Terminating delimiter character for string (such as " or >) or \0 for no escaping.

mode :

mode 0=N-Triples mode, 1=Turtle (allow raw UTF-8), 2=Turtle long string (allow raw UTF-8), 3=JSON

iostr :

raptor_iostream to write to

Returns :

non-0 on failure such as bad UTF-8 encoding.


Navigation: Redland Home Page

Copyright 2000-2014 Dave Beckett