Class RFile

RFile

Support

Supported from 5.0

Description

Creates and opens a file, and performs all operations on a single open file. These operations include:

• reading from and writing to the file

• seeking to a position within the file

• locking and unlocking within the file

• setting file attributes

Before using any of these services, a connection to a file server session must have been made and the file must be open.

Opening Files:

• use Open() to open an existing file for reading or writing — an error is returned if it does not already exist. To open an existing file for reading only, use Open() with an access mode of EFileRead and a share mode of EFileShareReadersOnly.

• use Create() to create and open a new file for writing — an error is returned if it already exists.

• use Replace() to open a file for writing, replacing any existing file of the same name if one exists or creating a new file if one does not exist,

• use Temp() to create and open a temporary file with a unique name, for writing and reading.

When opening a file, you must specify the file server session to use for operations with that file. If you do not close the file explicitly, it is closed when the server session associated with it is closed.

Reading and Writing:

There are several variants of both Read() and Write(). The basic Read(TDes8& aDes) and Write(const TDesC8& aDes) are supplemented by variants allowing the descriptor length to be overridden, or the seek position of the first byte to be specified, or asynchronous completion, or any combination.

Reading transfers data from a file to a descriptor, and writing transfers data from a descriptor to a file. In all cases, the file data is treated as binary and byte descriptors are used (TDes8, TDesC8).

Derivation

RFile Creates and opens a file, and performs all operations on a single open file RFsBase Base class that provides a Close() function for file related clean-up RSubSessionBase Client-side handle to a sub-session

Defined in RFile:
Att(), ChangeMode(), Create(), Flush(), Lock(), Modified(), Open(), Read(), Rename(), Replace(), Seek(), Set(), SetAtt(), SetModified(), SetSize(), Size(), Temp(), UnLock(), Write()

Inherited from RFsBase:
Close()

Inherited from RSubSessionBase:
CloseSubSession(), CreateSubSession(), Send(), SendReceive(), SubSessionHandle(), operator=()

TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode);

Description

Opens an existing file for reading or writing. If the file does not already exist, an error is returned.

Notes:

• To close the file, use Close(), defined in the base class RFsBase.

• Attempting to open a file with the read-only attribute using EFileWrite access mode results in an error.

• After a file has been opened, the current write position is set to the start of the file. If necessary, use RFile::Seek() to move to a different position within the file.

Parameters

RFs& aFs The file server session const TDesC& aName The name of the file. Any path components (i.e. drive letter or directory), which are not specified are taken from the session path. TUint aFileMode The mode in which the file is opened. For more information see the TFileMode enumeration.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• Using Open()

TInt Create(RFs& aFs,const TDesC& aName,TUint aFileMode);

Description

Creates and opens a new file for writing. If the file already exists, an error is returned.

Notes:

• To close the file, use Close(), defined in the base class RFsBase.

• Automatically sets the file's archive attribute.

Parameters

RFs& aFs The file server session const TDesC& aName The name of the file. Any path components which are not specified here are taken from the session path. TUint aFileMode The mode in which the file is opened. For more information see the TFileMode enumeration. The access mode is automatically set to EFileWrite.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Replace(RFs& aFs,const TDesC& aName,TUint aFileMode);

Description

Replaces a file. If there is an existing file with the same name, this function overwrites it. If the file does not already exist, it is created.

Notes:

• To close the file, use Close(), defined in the base class RFsBase.

• Automatically sets the file's archive attribute.

Parameters

RFs& aFs The file server session. const TDesC& aName The name of the file. Any path components which are not specified here are taken from the session path. TUint aFileMode The mode in which the file is opened. For more information see the TFileMode enumeration. The access mode is automatically set to EFileWrite.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Temp(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode);

Description

Creates and opens a temporary file with a unique name for writing and reading.

Note:

• To close the file, use Close(), defined in the base class RFsBase.

Parameters

RFs& aFs The file server session. const TDesC& aPath The directory in which the file is created. TFileName& aName On return, contains the full path and file name of the file. The filename is guaranteed to be unique within the directory specified by aPath. TUint aFileMode The mode in which the file is opened. For more information see the TFileMode enumeration. The access mode is automatically set to EFileWrite.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Read(TDes8& aDes) const;

Description

Reads from file — synchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero.

Parameters

TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Read(TDes8& aDes,TRequestStatus& aStatus) const;

Description

Reads from file — asynchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero.

Parameters

TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TRequestStatus& aStatus Request status. On completion contains an error code. KErrNone if successful, otherwise another of the system-wide error codes.

TInt Read(TDes8& aDes,TInt aLength) const;

Description

Reads specified number of bytes of binary data from file — synchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero. Assuming aLength is less than the maximum length of the descriptor, the only circumstances in which Read() can return fewer bytes than requested are when the end of file is reached or if an error has occurred.

Parameters

TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TInt aLength The number of bytes to read from the file into the descriptor. If an attempt is made to read more bytes than the descriptor's maximum length, the function returns KErrOverflow. Must not be negative or the function returns KErrGeneral.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Read(TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const;

Description

Reads a specified number of bytes of binary data from file — asynchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero. Assuming aLength is less than the maximum length of the descriptor, the only circumstances in which Read() can return fewer bytes than requested are when the end of file is reached or if an error has occurred.

Parameters

TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TInt aLength The number of bytes to read from the file into the descriptor. If an attempt is made to read more bytes than the descriptor's maximum length, the function returns KErrOverflow. Must not be negative or the function returns KErrGeneral. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Read(TInt aPos,TDes8& aDes) const;

Description

Reads from file at a specified offset — synchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero.

Parameters

TInt aPos Position of first byte to read — an offset from the start of the file. Must be positive or a panic occurs. If no position is specified, the read begins at the current file position. If aPos is beyond the end of the file, Read() returns a zero length descriptor. TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Read(TInt aPos,TDes8& aDes,TRequestStatus& aStatus) const;

Description

Reads from file at a specified offset — asynchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero.

Parameters

TInt aPos Position of first byte to read — an offset from the start of the file. Must be positive or a panic occurs. If no position is specified, the read begins at the current file position. If aPos is beyond the end of the file, Read() returns a zero length descriptor. TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TRequestStatus& aStatus Request status. On completion, contains an error code of KErrNone if successful, otherwise another of the system-wide error codes.

TInt Read(TInt aPos,TDes8& aDes,TInt aLength) const;

Description

Reads a specified number of bytes of binary data from the file at a specified offset — synchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length (given by TDesC::Length()) is zero. Assuming aLength is less than the maximum length of the descriptor, the only circumstances in which Read() can return fewer bytes than requested are when the end of the file is reached or if an error has occurred.

Parameters

TInt aPos The position of the first byte to read — an offset from the start of the file. Must be positive or a panic occurs. If no position is specified, the read begins at the current file position. If aPos is beyond the end of the file, Read() returns a zero length descriptor. TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TInt aLength The number of bytes to read from the file into the descriptor. If an attempt is made to read more bytes than the descriptor's maximum length, the function returns KErrOverflow. Must not be negative or the function returns KErrGeneral.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Read(TInt aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const;

Description

Reads a specified number of bytes of binary data from a file at a specified offset — asynchronous overload.

Note:

• When an attempt is made to read beyond the end of the file, no error is returned. The descriptor’s length is set to the number of bytes which were read into it. Therefore, when reading through a file, the end of the file has been reached when the descriptor length (given by TDesC::Length()) is zero. Assuming aLength is less than the maximum length of the descriptor, the only circumstances in which Read() can return fewer bytes than requested are when the end of file is reached or if an error has occurred.

Parameters

TInt aPos The position of the first byte to read — an offset from the start of the file. Must be positive or a panic occurs. If no position is specified, the read begins at the current file position. If aPos is beyond the end of the file, Read() returns a zero length descriptor. TDes8& aDes Descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. TInt aLength The number of bytes to read from the file into the descriptor. If an attempt is made to read more bytes than the descriptor's maximum length, the function returns KErrOverflow. Must not be negative or the function returns KErrGeneral. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Write(const TDesC8& aDes);

Description

Writes to file — synchronous overload.

Parameters

const TDesC8& aDes Descriptor from which binary data is written. The function writes to the file the entire contents of aDes.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Write(const TDesC8& aDes,TRequestStatus& aStatus);

Description

Writes to file — asynchronous overload.

Parameters

const TDesC8& aDes Descriptor from which binary data is written. The function writes to the file the entire contents of aDes. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Write(const TDesC8& aDes,TInt aLength);

Description

Writes a portion of a descriptor to the file — synchronous overload.

Note:

The aLength value is used when writing a portion of the descriptor aDes to the file, rather than the whole length of the descriptor. aLength should be less than the value returned by aDes.Length(), otherwise garbage is written to the file.

Parameters

const TDesC8& aDes Descriptor from which binary data is written. The function writes the portion of the descriptor specified by aLength to the file. TInt aLength The number of bytes to be written from aDes — overrides the descriptor length, so that a portion of the descriptor may be written to the file. Writing beyond the end of a file increases the file’s length.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Write(const TDesC8& aDes,TInt aLength,TRequestStatus& aStatus);

Description

Writes a portion of a descriptor to the file — asynchronous overload.

Note:

The aLength value is used when writing a portion of the descriptor aDes to the file, rather than the whole length of the descriptor. aLength should be less than the value returned by aDes.Length(), otherwise garbage is written to the file.

Parameters

const TDesC8& aDes Descriptor from which binary data is written. The function writes the portion of the descriptor specified by aLength to the file. TInt aLength The number of bytes to be written from aDes — overrides the descriptor length, so that a portion of the descriptor may be written to the file. Writing beyond the end of a file increases the file’s length. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Write(TInt aPos,const TDesC8& aDes);

Description

Writes to file at a specified offset — synchronous overload.

Parameters

TInt aPos The position into which the first byte is written — offset from the start of the file. Must be positive or a panic occurs. If no position is specified, the write begins at the current file position. If a position beyond the end of the file is specified, the write begins at the end of the file. If the position has been locked by another program, the write fails. const TDesC8& aDes Descriptor from which binary data is written. The function writes the entire contents of aDes to the file.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Write(TInt aPos,const TDesC8& aDes,TRequestStatus& aStatus);

Description

Writes to file at a specified offset — asynchronous overload.

Parameters

TInt aPos The position into which the first byte is written — offset from start of file. Must be positive or a panic occurs. If no position is specified, the write begins at the current file position. If a position beyond the end of the file is specified, the write begins at the end of the file. If the position has been locked by another program, the write fails. const TDesC8& aDes Descriptor from which binary data is written. The function writes to the file the entire contents of aDes. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Write(TInt aPos,const TDesC8& aDes,TInt aLength);

Description

Writes a specified number of bytes to a file at a specified offset — synchronous overload

Note:

The aLength value is used when writing a portion of the descriptor aDes to the file, rather than the whole length of the descriptor. aLength should be less than the value returned by aDes.Length(), otherwise garbage is written to the file.

Parameters

TInt aPos The position into which the first byte is written — offset from start of file. Must be positive or a panic occurs. If no position is specified, the write begins at the current file position. If a position beyond the end of the file is specified, the write begins at the end of the file. If the position has been locked by another program, the write fails. const TDesC8& aDes Descriptor from which binary data is written. TInt aLength The number of bytes to be written from aDes — overrides the descriptor length, so that a portion of the descriptor may be written to the file. Writing beyond the end of a file increases the file’s length.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Write(TInt aPos,const TDesC8& aDes,TInt aLength,TRequestStatus& aStatus);

Description

Writes a specified number of bytes to a file at a specified offset — asynchronous overload.

Note:

The aLength value is used when writing a portion of the descriptor aDes to the file, rather than the whole length of the descriptor. aLength should be less than the value returned by aDes.Length(), otherwise, garbage is written to the file.

Parameters

TInt aPos The position into which first byte is written — offset from start of file. Must be positive or a panic occurs. If no position is specified, the write begins at the current file position. If a position beyond the end of the file is specified, the write begins at the end of the file. If the position has been locked by another program, the write fails. const TDesC8& aDes Descriptor from which binary data is written. TInt aLength The number of bytes to be written from aDes — overrides the descriptor length, so that a portion of the descriptor may be written to the file. Writing beyond the end of a file increases the file’s length. TRequestStatus& aStatus Request status. On completion contains KErrNone if successful, otherwise another of the system-wide error codes.

TInt Lock(TInt aPos,TInt aLength) const;

Description

Locks a range of bytes within a file. This ensures that those bytes are accessible only through the RFile object which claimed the lock. To re-allow access by other programs to the locked region, it must either be unlocked or the file closed. Locking can be used to synchronize operations on a file when more than one program has access to the file in EFileShareAny mode.

Note:

• More than one distinct region of a file can be locked, but an error is returned if more than one lock is placed on the same region. Different RFile objects can lock different parts of the same file as long as the file is opened in EFileShareAny mode. The locked region may extend beyond the end of a file — this prevents the file from being extended by other programs.

Parameters

TInt aPos Position in file from which to lock — offset from the beginning of file. TInt aLength Number of bytes to lock. Must be greater than zero, or a panic occurs.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt UnLock(TInt aPos,TInt aLength) const;

Description

Unlocks a range of bytes within a file. A lock can only be removed by the RFile object which claimed the lock.

Note:

• A portion of a locked region cannot be unlocked — the entire locked region must be unlocked or an error is returned. If any byte within the specified range of bytes to unlock is not locked, an error is returned.

Parameters

TInt aPos Position in file from which to unlock — offset from beginning of file. TInt aLength Number of bytes to unlock — must be greater than zero, or a panic occurs.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Seek(TSeek aMode,TInt& aPos) const;

Description

Changes the current file position. It can also be used to get the current file position without changing it. The file position is the position at which reading and writing takes place. The start of the file is position zero.

Notes:

To retrieve the current file position without changing it, specify ESeekCurrent for the seek mode and zero for the offset.

If the seek mode is ESeekStart,

• the function does not modify the aPos argument,

• the function returns an error if the offset specified is negative.

If the seek mode is ESeekAddress, an error is returned if:

• the file is not in ROM,

• the offset specified is greater than the size of the file.

Parameters

TSeek aMode Seek mode — controls the destination of the seek operation. TInt& aPos Offset from location specified in aMode. Can be negative. On return contains the new file position. If the seek mode is either ESeekCurrent or ESeekEnd and the offset specifies a position before the start of the file or beyond the end of the file, on return, aPos is set to the new file position (either the start or the end of the file). If the seek mode is ESeekAddress, aPos returns the address of the byte at the specified offset within the file.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Flush();

Description

Commits data to the storage device and flushes internal buffers without closing the file.

Note:

• Although RFile::Close() also flushes internal buffers, it is often useful to call Flush() before a file is closed. This is because Close() returns no error information, so there is no way of telling whether the final data was written to the file successfully or not. Once data has been flushed, Close() is effectively a no-operation.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Size(TInt& aSize) const;

Description

Returns file size in bytes.

Parameters

TInt& aSize On return, the size of the file in bytes.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt SetSize(TInt aSize);

Description

Changes file size. If the size of the file is reduced, data may be lost from the end of the file.

Notes:

• The current file position remains unchanged unless SetSize() reduces the size of the file so that the current file position is now beyond the end of the file. In this case, the current file position is set to the end of file.

• If the file was not opened for writing, an error is returned.

Parameters

TInt aSize The new size of the file in bytes

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Att(TUint& aAttValue) const;

Description

Returns the file attributes.

Parameters

TUint& aAttValue A bitmask which on return contains the file’s attributes. For more information see KEntryAttNormal or the other file/directory attributes.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt SetAtt(TUint aSetAttMask,TUint aClearAttMask);

Description

Sets or clears file attributes using two bitmasks. The first mask controls which attributes are set. The second controls which attributes are cleared.

Notes:

• The file must have been opened for writing, or an error is returned.

• A panic occurs if any attribute is specified in both bitmasks.

• An attempt to set or clear either the KEntryAttDir or KEntryAttVolume attribute has no effect.

• The new attribute values take effect when the file is flushed or closed (which implies a flush).

Parameters

TUint aSetAttMask A bitmask indicating the file attributes to be set TUint aClearAttMask A bitmask indicating the attributes to be cleared. For more information see KEntryAttNormal or the other file/directory attributes

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• Using SetAtt()

TInt Modified(TTime& aTime) const;

Description

Gets the date and time the file was last modified.

Parameters

TTime& aTime On return, contains the date and time the file was last modified

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt SetModified(const TTime& aTime);

Description

Sets the date and time the file was last modified.

Notes:

• The file must have been opened for writing, or an error is returned.

• The new modified time takes effect when the file is flushed or closed (which implies a flush).

Parameters

const TTime& aTime The new date and time the file was last modified.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Set(const TTime& aTime,TUint aSetAttMask,TUint aClearAttMask);

Description

Sets the file’s attributes and the date and time it was last modified. It combines the SetAtt() and SetModified() functions. The function uses two bitmasks, the first of which controls which attributes should be set, and the second controls which attributes should be cleared.

Notes:

• A panic occurs if any attribute is specified in both bitmasks.

• The new attribute values and modified time take effect when the file is flushed or closed (which implies a flush).

• The file must not be read-only or an error is returned.

• An attempt to set or clear either the KEntryAttDir or KEntryAttVolume attribute has no effect.

Parameters

const TTime& aTime The new date and time the file was last modified. TUint aSetAttMask Bitmask indicating the attributes to set. TUint aClearAttMask Bitmask indicating the attributes to clear. For more information see KEntryAttNormal or the other file/directory attributes.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt ChangeMode(TFileMode aNewMode);

Description

Switches an open file’s access mode between EFileShareExclusive and EFileShareReadersOnly (allowing or disallowing read-only access by other files without having to close and re-open the file).

Notes:

This function returns an error in the following circumstances:

• If aNewMode has any value other than the two specified (KErrArgument).

• If the function is called when the current file share mode is EFileShareAny (KErrAccessDenied).

• If a file has multiple readers, and an attempt is made to change the share mode to EFileShareExclusive (KErrAccessDenied).

• If the file has been opened for writing in EFileShareExclusive mode, and an attempt is made to change the access mode to EFileShareReadersOnly (KErrAccessDenied).

Parameters

TFileMode aNewMode The new access mode.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt Rename(const TDesC& aNewName);

Description

Renames a file. If aNewName specifies a different directory to the one in which the file is currently located, then the file is moved.

No other process may have access to the file, that is, the file must have been opened in EFileShareExclusive share mode, or an error is returned. The file must have been opened for writing (using EFileWrite access mode). An error is returned if a file with the new filename already exists in the target directory.

The file or directory may not be moved to another device by this means, either explicitly (by another drive specified in the name) or implicitly (because the directory has been mapped to another device with RFs::SetSubst()).

Note:

The function builds up the new file specification by using all of the path components specified in aNewName (directory path, filename and extension), then adding any missing components from the current file specification, and finally adding any missing components from the session path. A consequence of this is that you cannot rename a file to remove its extension. An alternative to this function is RFs::Rename() which renames the file using the new name as provided.

Parameters

const TDesC& aNewName The new file name and/or directory path. No part may contain wildcard characters or an error is returned.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.