Simple C Expat Wrapper (SCEW)  1.1.7
Modules | Files | Data Structures | Typedefs | Functions

Read data from different sources: files, memory, etc. More...

Modules

 Memory
 Read data from memory buffers.
 
 Files
 Read data from files.
 

Files

file  reader.h
 SCEW reader common functions.
 

Data Structures

struct  scew_reader_hooks
 This is the set of functions that are implemented by all SCEW reader sources. More...
 

Typedefs

typedef struct scew_reader scew_reader
 This is the type delcaration for SCEW readers.
 

Functions

SCEW_API scew_readerscew_reader_create (scew_reader_hooks const *hooks, void *data)
 Creates a new SCEW reader with the given scew_reader_hooks implementation. More...
 
SCEW_API void * scew_reader_data (scew_reader *reader)
 Returns the reference to the internal data structure being used by the given reader. More...
 
SCEW_API size_t scew_reader_read (scew_reader *reader, XML_Char *buffer, size_t char_no)
 Reads data from the given reader in store it in the specified buffer. More...
 
SCEW_API scew_bool scew_reader_end (scew_reader *reader)
 Tells whether the given reader has reached its end. More...
 
SCEW_API scew_bool scew_reader_error (scew_reader *reader)
 Tells whether an error was found while reading from the given reader. More...
 
SCEW_API scew_bool scew_reader_close (scew_reader *reader)
 Closes the given reader. More...
 
SCEW_API void scew_reader_free (scew_reader *reader)
 Frees the memory allocated by the given reader. More...
 

Detailed Description

Read data from different sources: files, memory, etc.

SCEW readers provide a common mechanism to read data from different sources. This is done by implementing the set of functions declared in scew_reader_hooks. A user might create new SCEW readers by implementing those functions.

Once a SCEW reader is created, functions in this section should be used no matter the reader type.

Function Documentation

SCEW_API scew_reader* scew_reader_create ( scew_reader_hooks const *  hooks,
void *  data 
)

Creates a new SCEW reader with the given scew_reader_hooks implementation.

This function should be called internally when implementing a new SCEW reader source. The data argument is a reference to some internal data used by the SCEW reader (file stream pointer, current memory buffer pointer, etc.). This data might be later obtained, by the SCEW reader implementation, via scew_reader_data.

Precondition
hooks != NULL
Parameters
hooksthe implementation of the new SCEW reader source.
datadata to be used by the new SCEW reader. This is usually a reference to a file stream (in case of files) or a memory buffer pointer, etc.
Returns
a new SCEW reader, or NULL if the reader could not be created.
SCEW_API void* scew_reader_data ( scew_reader reader)

Returns the reference to the internal data structure being used by the given reader.

Precondition
reader != NULL
Parameters
readerthe reader to obtain its internal data for.
Returns
a refrence to the reader's internal data, or NULL if no data was set at creation time.
SCEW_API size_t scew_reader_read ( scew_reader reader,
XML_Char *  buffer,
size_t  char_no 
)

Reads data from the given reader in store it in the specified buffer.

This function will read as many characters (of size XML_Char) as specified by char_no. scew_reader_error and scew_reader_end need to be consulted to check whether an error is found or the end of the reader is reached, respectively.

This function will call the actual read function provided by the SCEW reader hooks (scew_reader_hooks).

Precondition
reader != NULL
buffer != NULL
Parameters
readerthe reader from where to read data from.
bufferthe memory buffer where to store data.
char_nothe number of characters to read.
Returns
the number of characters successfully read.
SCEW_API scew_bool scew_reader_end ( scew_reader reader)

Tells whether the given reader has reached its end.

That is, no more data is available for reading.

This function will call the actual end function provided by the SCEW reader hooks (scew_reader_hooks).

Precondition
reader != NULL
Parameters
readerthe reader to check its end status for.
Returns
true if we are at the end of the reader, false otherwise.
SCEW_API scew_bool scew_reader_error ( scew_reader reader)

Tells whether an error was found while reading from the given reader.

This function will call the actual error function provided by the SCEW reader hooks (scew_reader_hooks).

Precondition
reader != NULL
Parameters
readerthe reader to check its status for.
Returns
true if we an error was found while reading data from the reader, false otherwise.
SCEW_API scew_bool scew_reader_close ( scew_reader reader)

Closes the given reader.

This function will have different effects depending on the SCEW reader type (e.g. it will close the file for file streams). After calling this function, none of the SCEW reader functions should be used, otherwise undefined behavior is expected.

This function will call the actual close function provided by the SCEW reader hooks (scew_reader_hooks).

Precondition
reader != NULL
Parameters
readerthe reader to close.
Returns
true if the reader was successfully closed, false otherwise.
SCEW_API void scew_reader_free ( scew_reader reader)

Frees the memory allocated by the given reader.

This function will call the actual free function provided by the SCEW reader hooks (scew_reader_hooks).

Parameters
readerthe reader to free.