Oscl_File Class Reference
[OSCL IO]

#include <oscl_file_io.h>

Inheritance diagram for Oscl_File:

Data Structures
class	OsclCacheObserver
class	OsclFixedCacheParam
Public Types
enum	seek_type { SEEKSET, SEEKCUR, SEEKEND }
enum	mode_type { MODE_READ = 0x0001, MODE_READWRITE = 0x0002, MODE_APPEND = 0x0004, MODE_BINARY = 0x0008, MODE_TEXT = 0x0010, MODE_READ_PLUS = 0x0020 }
enum	TSymbianAccessMode { ESymbianAccessMode_Rfile = 0, ESymbianAccessMode_RfileBuf = 1 }
Public Member Functions
OSCL_IMPORT_REF	Oscl_File ()
OSCL_IMPORT_REF	Oscl_File (uint32 aCacheSize)
OSCL_IMPORT_REF	Oscl_File (uint32 aCacheSize, OsclFileHandle *aFileHandle)
OSCL_IMPORT_REF	~Oscl_File ()
OSCL_IMPORT_REF void	SetPVCacheSize (uint32 aSize)
void	AddFixedCache (const OsclFixedCacheParam &aParam)
void	RemoveFixedCache (const TOsclFileOffset &aPos)
void	SetCacheObserver (OsclCacheObserver *aObs)
OSCL_IMPORT_REF void	SetNativeAccessMode (uint32 aMode)
OSCL_IMPORT_REF void	SetNativeBufferSize (int32 aSize)
OSCL_IMPORT_REF void	SetAsyncReadBufferSize (uint32 aSize)
OSCL_IMPORT_REF int32	SetFileHandle (OsclFileHandle *aHandle)
OSCL_IMPORT_REF int32	Open (const char *filename, uint32 mode, Oscl_FileServer &fileserv)
OSCL_IMPORT_REF int32	Open (const oscl_wchar *filename, uint32 mode, Oscl_FileServer &fileserv)
OSCL_IMPORT_REF uint32	Read (OsclAny *buffer, uint32 size, uint32 numelements)
OSCL_IMPORT_REF uint32	Write (const OsclAny *buffer, uint32 size, uint32 numelements)
OSCL_IMPORT_REF int32	Seek (TOsclFileOffset offset, seek_type origin)
OSCL_IMPORT_REF TOsclFileOffset	Tell ()
OSCL_IMPORT_REF int32	Close ()
OSCL_IMPORT_REF int32	Flush ()
OSCL_IMPORT_REF int32	SetSize (uint32 size)
OSCL_IMPORT_REF int32	EndOfFile ()
OSCL_IMPORT_REF int32	GetError ()
OsclFileHandle *	Handle ()
OSCL_IMPORT_REF TOsclFileOffset	Size ()
OSCL_IMPORT_REF void	SetLoggingEnable (bool aEnable)
OSCL_IMPORT_REF void	SetSummaryStatsLoggingEnable (bool aEnable)
Friends
class	OsclFileCache
class	OsclFileCacheBuffer
class	asyncfilereadwrite_test
class	largeasyncfilereadwrite_test
class	asyncfilereadcancel_test

Member Enumeration Documentation

enum Oscl_File::mode_type

Enumerator:

MODE_READ	Opens a file for reading. The file must exist.
MODE_READWRITE	Opens the file for reading and writing. If the file exists, its contents will be overwritten unless APPEND mode is specified. If the file does not exist, it will be created.
MODE_APPEND	Specifies all write operations to occur at the end of the file. The file pointer can be moved with the Seek command, but will always be moved to the end of the file for write commands.
MODE_BINARY	Opens the file in 'binary' mode. This is the default.
MODE_TEXT	Opens the file in 'text' mode. The default mode is 'binary'.
MODE_READ_PLUS	Open a file for reading and writing. The file must exist. The default mode is 'binary'.

enum Oscl_File::seek_type

Enumerator:

SEEKSET	Beginning of file
SEEKCUR	Current position of file pointer
SEEKEND	End of file

enum Oscl_File::TSymbianAccessMode

Defines mode options for SetNativeAccessMode on Symbian.

Enumerator:

ESymbianAccessMode_Rfile
ESymbianAccessMode_RfileBuf

Constructor & Destructor Documentation

OSCL_IMPORT_REF Oscl_File::Oscl_File ( )

Constructor

OSCL_IMPORT_REF Oscl_File::Oscl_File ( uint32 aCacheSize )

Deprecated Constructor, present for back-compatibility.

Parameters:

aCacheSize,:

sets native buffer size, and when pv cache is enabled, also sets pv cache size.

OSCL_IMPORT_REF Oscl_File::Oscl_File	(	uint32	aCacheSize,
		OsclFileHandle *	aFileHandle
	)

Deprecated Constructor, present for back-compatibility.

Parameters:

	aCacheSize,:	sets native buffer size, and when pv cache is enabled, also sets pv cache size.
	aFileHandle,:	open file handle.

OSCL_IMPORT_REF Oscl_File::~Oscl_File ( )

Destructor

Member Function Documentation

void Oscl_File::AddFixedCache ( const OsclFixedCacheParam & aParam ) [inline]

AddFixedCache adds a fixed cache. The fixed cache will be used on the next opportunity. The fixed cache must not overlap with any other fixed cache.

Parameters:

aParam,:

Cache location and size.

References Oscl_Vector< T, Alloc >::push_back().

OSCL_IMPORT_REF int32 Oscl_File::Close ( )

The File Close operation Closes the file after flushing any remaining data in the buffers.

Note: If the file object was opened with an external file handle, then Close will simply flush the file. The file will remain open.

Returns:: returns 0 if successful, and a non-zero value otherwise

OSCL_IMPORT_REF int32 Oscl_File::EndOfFile ( )

The File EOF(end of file) operation returns a nonzero value after the first read operation that attempts to read past the end of the file

Returns:

OSCL_IMPORT_REF int32 Oscl_File::Flush ( )

The File Flush operation On an output stream OSCL_FileFlush causes any buffered but unwritten data to be written to the file. Flush is meant for writable files. The behavior when calling it on read-only files is OS-dependent.

Returns:: returns 0 if successful, and a non-zero value otherwise

OSCL_IMPORT_REF int32 Oscl_File::GetError ( )

The File Error operation If no error has occurred on stream, returns 0. Otherwise, it returns a nonzero value

Returns:

OsclFileHandle* Oscl_File::Handle ( ) [inline]

Retrieve the file handle.

Returns:: file handle

OSCL_IMPORT_REF int32 Oscl_File::Open	(	const oscl_wchar *	filename,
		uint32	mode,
		Oscl_FileServer &	fileserv
	)

Opens a file.

Note: when an external file handle is used, Open will attach to the file handle and initialize cacheing features, but will not do a native file open.

Parameters:

	filename	name of file to open (Unicode)
	mode	combination of open mode flags
	fileserv	fileserver to use

Returns:: returns 0 if successful and a non-zero value otherwise

OSCL_IMPORT_REF int32 Oscl_File::Open	(	const char *	filename,
		uint32	mode,
		Oscl_FileServer &	fileserv
	)

Opens a file.

Note: when an external file handle is used, Open will attach to the file handle and initialize cacheing features, but will not do a native file open.

Parameters:

	filename	name of file to open (Utf8)
	mode	combination of open mode flags
	fileserv	fileserver to use

Returns:: returns 0 if successful and a non-zero value otherwise

OSCL_IMPORT_REF uint32 Oscl_File::Read	(	OsclAny *	buffer,
		uint32	size,
		uint32	numelements
	)

The File Read operation Reads from the file into the buffer a maximum of 'numelements' of size 'size'.

Parameters:

	buffer	pointer to buffer of type void
	size	element size in bytes
	numelements	max number of elements to read

Returns:: returns the number of full elements actually read, which may be less than count if an error occurs or if the end of the file is encountered before reaching count. Use the CheckEndOfFile or GetError function to distinguish a read error from an end-of-file condition.

void Oscl_File::RemoveFixedCache ( const TOsclFileOffset & aPos ) [inline]

RemoveFixedCache removes a fixed cache.

Parameters:

aPos,:

Cache location and size.

References Oscl_Vector< T, Alloc >::push_back().

OSCL_IMPORT_REF int32 Oscl_File::Seek	(	TOsclFileOffset	offset,
		seek_type	origin
	)

The File Seek operation Sets the position for file pointer

Parameters:

	offset	offset from the specified origin.
	origin	starting point

Returns:: returns 0 on success, and a non-zero value otherwise

OSCL_IMPORT_REF void Oscl_File::SetAsyncReadBufferSize ( uint32 aSize )

SetAsyncReadBufferSize configures the asynchronous background read function. May not be available on all platforms.

This should be called before opening the file. If used when the file is open, the option will not take effect until the next Open.

Note: if asynchronous read is not available on the platform, this call will have no effect.

Parameters:

aSize,:

buffer size in bytes. Zero disables the feature.

void Oscl_File::SetCacheObserver ( OsclCacheObserver * aObs ) [inline]

OSCL_IMPORT_REF int32 Oscl_File::SetFileHandle ( OsclFileHandle * aHandle )

SetFileHandle adds an open file handle to the Oscl_File object. The Oscl_File object will use that handle to access the file.

This call is not available when the Oscl_File object is already open.

Note: This feature is used in Symbian with the MMF framework. The MMF framework provides an open RFile handle to access content. When using RFileBuf access mode with an RFile handle, the RFileBuf will be attached to the open RFile handle.

To use the external file handle, the caller starts with a native file handle to an open file. The caller must wrap the native file handle in an OsclFileHandle object, pass the OsclFileHandle pointer to SetFileHandle, call Oscl_File::Open, then proceed to use the Oscl_File object, finally calling Oscl_File::Close. In this usage mode, Oscl_File::Open and Oscl_File::Close do not actually call native file open and close. It is assumed that the caller will close the original native file handle after usage is complete.

Parameters:

aHandle,:

container for an open file handle.

Returns:: returns 0 if successful, non-zero if error.

OSCL_IMPORT_REF void Oscl_File::SetLoggingEnable ( bool aEnable )

SetLoggingEnable configures the PVLogger output for this file. This will enable full logging of each API entry and exit using the logger object "Oscl_File", plus full logging of native operation entry & exit using logger object "OsclNativeFile".

Parameters:

aEnable,:

true to enable, false to disable logging.

OSCL_IMPORT_REF void Oscl_File::SetNativeAccessMode ( uint32 aMode )

SetNativeAccessMode allows switching between different native file access modes, when available.

Note: for For Symbian, use the TSymbianAccessMode values to choose the mode. If multiple access modes are not available on the platform, this call will have no effect.

Parameters:

aMode,:

access mode.

OSCL_IMPORT_REF void Oscl_File::SetNativeBufferSize ( int32 aSize )

SetNativeBufferSize configures the native file buffering feature, when available.

This should be called before opening the file. If used when the file is open, the option will not take effect until the next Open.

Note: For Symbian, this sets the RFileBuf cache size. If native buffing is not available on the platform, this call will have no effect.

Parameters:

aSize,:

native buffer size in bytes. Zero disables the feature.

OSCL_IMPORT_REF void Oscl_File::SetPVCacheSize ( uint32 aSize )

SetPVCacheSize configures the read/write cache.

This should be called before opening the file. If used when the file is open, the option will not take effect until the next Open.

Parameters:

aSize,:

cache size in bytes. Zero disables the cache.

OSCL_IMPORT_REF int32 Oscl_File::SetSize ( uint32 size )

The File SetSize operation If the file has been opened for writing this will set the size of the file. The file pointer position is undefined after calling SetSize. If file size is increased the contents of the new section are undefined.

Returns:: returns 0 if successful, and a non-zero value otherwise

OSCL_IMPORT_REF void Oscl_File::SetSummaryStatsLoggingEnable ( bool aEnable )

SetSummaryStatsLoggingEnable configures the PVLogger output for this file. This will enable summary statistics logging only, using the logger object "OsclFileStats".

Parameters:

aEnable,:

true to enable, false to disable stats logging.

OSCL_IMPORT_REF TOsclFileOffset Oscl_File::Size ( )

Get the file size in bytes.

Returns:: - The size of the file, or -1 on error.

OSCL_IMPORT_REF TOsclFileOffset Oscl_File::Tell ( )

The File Tell operation Returns the current file position for file specified by fp

OSCL_IMPORT_REF uint32 Oscl_File::Write	(	const OsclAny *	buffer,
		uint32	size,
		uint32	numelements
	)

The File Write operation Writes from the buffer 'numelements' objects of size 'size'

Parameters:

	buffer	pointer to buffer of type void
	size	element size in bytes
	numelements	number of elements to write

Returns:: The number of elements written

Friends And Related Function Documentation

friend class asyncfilereadcancel_test [friend]

friend class asyncfilereadwrite_test [friend]

friend class largeasyncfilereadwrite_test [friend]

friend class OsclFileCache [friend]

friend class OsclFileCacheBuffer [friend]

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

oscl_file_io.h

Oscl_File Class Reference [OSCL IO]

Data Structures

Public Types

Public Member Functions

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Oscl_File Class Reference
[OSCL IO]