cgul_block_reader.h File Reference

block reader abstraction More...

#include "cgul_common.h"
#include "cgul_exception.h"

Include dependency graph for cgul_block_reader.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_block_reader *	cgul_block_reader_t

Functions
CGUL_EXPORT void	cgul_block_reader__delete (cgul_block_reader_t br)
CGUL_EXPORT size_t	cgul_block_reader__read_next_block (cgul_exception_t *cex, cgul_block_reader_t br, void *block, size_t block_size)
CGUL_EXPORT const char *	cgul_block_reader__get_presentation_name (cgul_exception_t *cex, cgul_block_reader_t br)
CGUL_EXPORT void	cgul_block_reader__set_presentation_name (cgul_exception_t *cex, cgul_block_reader_t br, const char *presentation_name)

Detailed Description

Interface that defines the ability to read blocks of data from an external source. The main reason for this interface is to abstract reading blocks from a file or from memory.

Because this is an abstract base class, instances cannot be created directly. Instead, concrete instances can be created using the following classes:

    cgul_block_reader_file
    cgul_block_reader_memory

Perhaps a better solution would be to use the standard C FILE class along with fopen() and fmemopen(), but fmemopen() is not widely available at the time of writing.

A similar class is cgul_crlf_file which returns lines of text instead of blocks of data.

Author

Paul Serice

See also

cgul_crlf_file

cgul_stream_reader

Typedef Documentation

cgul_block_reader_t

typedef typedefCGUL_BEGIN_C struct cgul_block_reader* cgul_block_reader_t

Opaque pointer to a cgul_block_reader instance.

Function Documentation

cgul_block_reader__delete()

CGUL_EXPORT void cgul_block_reader__delete

(

cgul_block_reader_t

br

)

Virtual destructor. Derived classes should override to deallocate resources as necessary. Classes that implement this interface must correctly chain their destructor with their parent class's destructor. Remember that cgul_block_reader is conceptually an interface, not a class, so do not chain with it; otherwise, you'll get infinite recursion because the methods defined for the interface do nothing other than dispatch based on the vtable.

Parameters

[in]

br

cgul_block_reader instance

cgul_block_reader__read_next_block()

CGUL_EXPORT size_t cgul_block_reader__read_next_block	(	cgul_exception_t *	cex,
		cgul_block_reader_t	br,
		void *	block,
		size_t	block_size
	)

Virtual method that reads one block of data block of size block_size bytes from an external data source. The user is responsible for making sure block points to at least block_size contiguous bytes of memory. This method returns the number of bytes read or 0 if EOF is reached without error. If an error occurs, 0 is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	br	cgul_block_reader instance
[in]	block	block
[in]	block_size	block size in bytes

Returns

number of bytes read

cgul_block_reader__get_presentation_name()

CGUL_EXPORT const char* cgul_block_reader__get_presentation_name	(	cgul_exception_t *	cex,
		cgul_block_reader_t	br
	)

Virtual method that returns the presentation name.

Parameters

[in,out]	cex	c-style exception
[in]	br	cgul_block_reader instance

Returns

presentation name

cgul_block_reader__set_presentation_name()

CGUL_EXPORT void cgul_block_reader__set_presentation_name	(	cgul_exception_t *	cex,
		cgul_block_reader_t	br,
		const char *	presentation_name
	)

Virtual method that sets the presentation name. The presentation name is primarily used for error reporting and can be set to anything, but it does need to be set again if the input source changes. An exception is thrown if an attempt is made to set the presentation name without first setting the input source.

Parameters

[in,out]	cex	c-style exception
[in]	br	cgul_block_reader instance
[in]	presentation_name	presentation name