BufferedFile_t Class Reference

Buffered file implementation.

#include <UTBufferedFile.h>

Inheritance diagram for BufferedFile_t:

Public Member Functions
	BufferedFile_t (int buffer_size=8192)
virtual	~BufferedFile_t ()
virtual Status_t	Open (const Path_t &path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > *open_dest=NULL)
Status_t	Open (const utf8 path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > open_dest=NULL)
Status_t	Open (stringliteral path, int flags, mode_t permissions=0, MessageDestination_t< FileReadCompleteMessage_t > read_dest=NULL, MessageDestination_t< FileWriteCompleteMessage_t > write_dest=NULL, MessageDestination_t< FileOpenCompleteMessage_t > open_dest=NULL)
virtual Status_t	Read (byte *buffer, int bytes_to_read, bool force_read_all=true)
virtual Status_t	ReadLine (out String_t *line)
virtual Status_t	Write (const byte *buffer, int bytes_to_write, bool force_write_all=true)
virtual Status_t	WriteLine (const String_t &line, line_ending_type_t line_ending=eLINEENDING_native)
virtual Status_t	WriteLine (const utf8 *line, line_ending_type_t line_ending=eLINEENDING_native)
virtual Status_t	WriteLine (stringliteral *line, line_ending_type_t line_ending=eLINEENDING_native)
virtual Status_t	Size (out fileoff_t *size)
virtual Status_t	Position (out fileoff_t *position)
virtual Status_t	Seek (fileoff_t position)
virtual Status_t	Flush ()
virtual Status_t	Close ()
Protected Member Functions
virtual Status_t	AsyncOpenComplete ()
virtual void	AppendStateInfo (String_t *state) const

Detailed Description

Definition at line 64 of file UTBufferedFile.h.

Constructor & Destructor Documentation

BufferedFile_t::BufferedFile_t ( int buffer_size = 8192 )

Buffered file constructor. The file must be opened using the Open function. Except at boundary cases (beginning or end of the file) the BufferedFile_t object will maintain two buffers of the specified size if the file is being accessed linearally, or three buffers if Seeks are being performed to locations out of range of the two cached buffers.

virtual BufferedFile_t::~BufferedFile_t ( ) [virtual]

Buffered file destructor. Unless an error had occurred previously, a file must be closed before deleting it.

Member Function Documentation

virtual Status_t BufferedFile_t::Open	(	const Path_t &	path,
		int	flags,
		mode_t	permissions = `0`,
		MessageDestination_t< FileReadCompleteMessage_t > *	read_dest = `NULL`,
		MessageDestination_t< FileWriteCompleteMessage_t > *	write_dest = `NULL`,
		MessageDestination_t< FileOpenCompleteMessage_t > *	open_dest = `NULL`
	)			`[virtual]`

Opens a buffered file. See File_t::Open for complete documentation on the flags, permissions, and operation complete message usage.

The O_NONBLOCK flag can be used to cause BufferedFile_t to use nonblocking I/O when accessing the underlying File_t for pre-loading data which is expected to be read next. In that case, nonblocking I/O can also be performed on the caller's buffer, so the caller must be prepared for eERR_async_io_in_progress if force_read_all or force_write_all are false when calling Read or Write.

Reimplemented from File_t.

Status_t BufferedFile_t::Open	(	const utf8 *	path,
		int	flags,
		mode_t	permissions = `0`,
		MessageDestination_t< FileReadCompleteMessage_t > *	read_dest = `NULL`,
		MessageDestination_t< FileWriteCompleteMessage_t > *	write_dest = `NULL`,
		MessageDestination_t< FileOpenCompleteMessage_t > *	open_dest = `NULL`
	)			`[inline]`

Variant of Open( const Path_t& path, ... ) which takes a const utf8* for the file path instead of a const Path_t&

Reimplemented from File_t.

Status_t BufferedFile_t::Open	(	stringliteral *	path,
		int	flags,
		mode_t	permissions = `0`,
		MessageDestination_t< FileReadCompleteMessage_t > *	read_dest = `NULL`,
		MessageDestination_t< FileWriteCompleteMessage_t > *	write_dest = `NULL`,
		MessageDestination_t< FileOpenCompleteMessage_t > *	open_dest = `NULL`
	)			`[inline]`

Variant of Open( const Path_t& path, ... ) which takes a const stringliteral* for the file path instead of a const Path_t&

Reimplemented from File_t.

virtual Status_t BufferedFile_t::Read	(	byte *	buffer,
		int	bytes_to_read,
		bool	force_read_all = `true`
	)			`[virtual]`

Reads up to bytes_to_read bytes into buffer, and returns the number of bytes read as a success status indication, or an error status.

For nonblocking files, if force_read_all is true, Read will block until all data is read.

If force_read_all is true, a returned byte count less than bytes_to_read indicates that the end of the file was reached.

If the end of the file is reached with no data having been read, the returned status will be eERR_end_of_file.

If O_NONBLOCK was specified when the file was opened, force_read_all is false, and the read was unable to complete immediately, the request will proceed to completion asynchronously. In that case the returned status is eERR_async_io_in_progress to indicate that data is not currently available, the next call to Read must exactly match the one which returned eERR_async_io_in_progress, and the buffer must remain valid until the next call. Also in that case, no other file operations are permissible until the previous request has been repeated and succeeded.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::ReadLine ( out String_t * line ) [virtual]

Reads a line from the file. The line will end when "\r", "\n", "\r\n", "\0", or end of file is encountered. The returned line string will not contain the terminator. If the end of the file is reached with no line having been read, ReadLine returns eERR_end_of_file.

Reimplemented from InputStream_t.

virtual Status_t BufferedFile_t::Write	(	const byte *	buffer,
		int	bytes_to_write,
		bool	force_write_all = `true`
	)			`[virtual]`

Writes up to bytes_to_write bytes from buffer, and returns the number of bytes written as a success status indication, or an error status. If an error status is returned, some data may have been written, and it is not possible to determine how much data was written.

For nonblocking files, if force_write_all is true, Write will block until all data has been written.

If force_write_all is true, either all data will be written or an error will be returned. An end of file condition for write is not expected for regular files, but if reaching end-of-file without writing all of the specified data is not to be considered an error, force_write_all must be set to false.

If force_write_all is false, in the absence of any other error, the returned status will be the number of bytes written, which may be less than what was requested. An end of file condition for write is not expected for regular files, but if end of the file is reached with no data having been written, the returned status will be eERR_end_of_file.

If O_NONBLOCK was specified when the file was opened, force_write_all is false, and the write was unable to complete immediately, the request will proceed to completion asynchronously. In that case the returned status is eERR_async_io_in_progress to indicate that the write is proceeding asynchronously, the next call to Write must exactly match the one which returned eERR_async_io_in_progress, and the buffer must remain valid until the next call. Also in that case, no other file operations are permissible until the previous request has been repeated and succeeded.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::WriteLine	(	const String_t &	line,
		line_ending_type_t	line_ending = `eLINEENDING_native`
	)			`[virtual]`

Writes a line of text, converting line endings if necessary to the specified format. If the string contains line endings, they will be converted to the specified format. If the string ends with a line ending, an additional one will not be added to the end.

Reimplemented from OutputStream_t.

virtual Status_t BufferedFile_t::WriteLine	(	const utf8 *	line,
		line_ending_type_t	line_ending = `eLINEENDING_native`
	)			`[virtual]`

Writes a line of text, converting line endings if necessary to the specified format. If the string contains line endings, they will be converted to the specified format. If the string ends with a line ending, an additional one will not be added to the end.

Reimplemented from OutputStream_t.

virtual Status_t BufferedFile_t::WriteLine	(	stringliteral *	line,
		line_ending_type_t	line_ending = `eLINEENDING_native`
	)			`[virtual]`

Writes a line of text, converting line endings if necessary to the specified format. If the string contains line endings, they will be converted to the specified format. If the string ends with a line ending, an additional one will not be added to the end.

Reimplemented from OutputStream_t.

virtual Status_t BufferedFile_t::Size ( out fileoff_t * size ) [virtual]

Returns the size of the file through the size parameter, or an error status if an error occurs.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::Position ( out fileoff_t * position ) [virtual]

Returns the position in the file through the position output parameter unless an error occurs, in which case an error status is returned in the Status_t return value.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::Seek ( fileoff_t position ) [virtual]

Repositions the input/output position to the requested offset in the file. Seek will block until completed even if the Open flags included O_NONBLOCK.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::Flush ( ) [virtual]

Flushes any data buffered but not written to whatever physical layer the file represents. If an error occurs, an error status will be returned. Flush will block until completed even if the Open flags included O_NONBLOCK.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::Close ( ) [virtual]

Closes the file. Close will block until completed even if the Open flags included O_NONBLOCK. In the event of a prior error or error closing the file, Close will return an error, but the file will nonetheless be closed. If all prior operations had succeeded since the file was opened, then an error returned by Close indicates that an error occurred while writing buffered, unwritten data, or during the close. When a file had been written to, an error indicates that and all data may not have been written.

Reimplemented from File_t.

virtual Status_t BufferedFile_t::AsyncOpenComplete ( ) [protected, virtual]

See File_t::Open and File_t::AsyncOpenComplete for documentation.

Reimplemented from File_t.

virtual void BufferedFile_t::AppendStateInfo ( String_t * state ) const [protected, virtual]

Allows an IOStream_t subclass to output state information for file operation logging on function exit

Reimplemented from File_t.

The documentation for this class was generated from the following file:

D:/develop/svn/utlib/utlib/trunk/UT/src_UT/UTBufferedFile.h

BufferedFile_t Class Reference

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation