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

Write data to different destinations: files, memory, etc. More...

Modules

 Memory
 Write data to memory buffers.
 
 Files
 Write data to files.
 

Files

file  writer.h
 SCEW writer common functions.
 

Data Structures

struct  scew_writer_hooks
 This is the set of functions that are implemented by all SCEW writers. More...
 

Typedefs

typedef struct scew_writer scew_writer
 This is the type delcaration for SCEW writers.
 

Functions

SCEW_API scew_writerscew_writer_create (scew_writer_hooks const *hooks, void *data)
 Creates a new SCEW writer with the given scew_writer_hooks implementation. More...
 
SCEW_API void * scew_writer_data (scew_writer *writer)
 Returns the reference to the internal data structure being used by the given writer. More...
 
SCEW_API size_t scew_writer_write (scew_writer *writer, XML_Char const *buffer, size_t char_no)
 Writes data from the given memory buffer to the specified writer. More...
 
SCEW_API scew_bool scew_writer_end (scew_writer *writer)
 Tells whether the given writer has reached its end. More...
 
SCEW_API scew_bool scew_writer_error (scew_writer *writer)
 Tells whether an error was found while sending data to the given writer. More...
 
SCEW_API scew_bool scew_writer_close (scew_writer *writer)
 Closes the given writer. More...
 
SCEW_API void scew_writer_free (scew_writer *writer)
 Frees the memory allocated by the given writer. More...
 

Detailed Description

Write data to different destinations: files, memory, etc.

SCEW writers provide a common mechanism to write data to different destinations. This is done by implementing the set of functions declared in scew_writer_hooks. A user might create new SCEW writers by implementing those functions.

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

Function Documentation

SCEW_API scew_writer* scew_writer_create ( scew_writer_hooks const *  hooks,
void *  data 
)

Creates a new SCEW writer with the given scew_writer_hooks implementation.

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

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

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

Precondition
writer != NULL
Parameters
writerthe writer to obtain its internal data for.
Returns
a refrence to the writer's internal data, or NULL if no data was set at creation time.
SCEW_API size_t scew_writer_write ( scew_writer writer,
XML_Char const *  buffer,
size_t  char_no 
)

Writes data from the given memory buffer to the specified writer.

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

This function will call the actual write function provided by the SCEW writer hooks (scew_writer_hooks).

Precondition
writer != NULL
buffer != NULL
Parameters
writerthe writer where to send the data.
bufferthe memory buffer from where to read data from.
char_nothe number of characters to write.
Returns
the number of characters successfully written.
SCEW_API scew_bool scew_writer_end ( scew_writer writer)

Tells whether the given writer has reached its end.

That is, no more data can be written to the .

This function will call the actual end function provided by the SCEW writer hooks (scew_writer_hooks).

Precondition
writer != NULL
Parameters
writerthe writer to check its end status for.
Returns
true if we are at the end of the writer, false otherwise.
SCEW_API scew_bool scew_writer_error ( scew_writer writer)

Tells whether an error was found while sending data to the given writer.

This function will call the actual error function provided by the SCEW writer hooks (scew_writer_hooks).

Precondition
writer != NULL
Parameters
writerthe writer to check its status for.
Returns
true if we an error was found while sending data to the writer, false otherwise.
SCEW_API scew_bool scew_writer_close ( scew_writer writer)

Closes the given writer.

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

This function will call the actual close function provided by the SCEW writer hooks (scew_writer_hooks).

Precondition
writer != NULL
Parameters
writerthe writer to close.
Returns
true if the writer was successfully closed, false otherwise.
SCEW_API void scew_writer_free ( scew_writer writer)

Frees the memory allocated by the given writer.

This function will call the actual free function provided by the SCEW writer hooks (scew_writer_hooks).

Precondition
writer != NULL
Parameters
writerthe writer to free.