Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: f32file.h
Link against: efsrv.lib

Class RFile

class RFile : public RSubSessionBase;

Description

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

These include:

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:

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

Members

Defined in RFile:
Adopt(), AdoptFromClient(), AdoptFromCreator(), AdoptFromServer(), Att(), BlockMap(), ChangeMode(), Close(), Create(), Drive(), Duplicate(), Flush(), Flush(), FullName(), Lock(), Modified(), Name(), Open(), Read(), Read(), Read(), Read(), Read(), Read(), Read(), Read(), ReadCancel(), ReadCancel(), Rename(), Replace(), Seek(), Set(), SetAtt(), SetModified(), SetSize(), Size(), Temp(), TransferToClient(), TransferToProcess(), TransferToServer(), UnLock(), Write(), Write(), Write(), Write(), Write(), Write(), Write(), Write()

Inherited from RSubSessionBase:
CloseSubSession(), CreateAutoCloseSubSession(), CreateSubSession(), Send(), SendReceive(), Session(), SubSessionHandle()

See also

See also:


Member functions


Open()

Capability: Dependent If the path for aName is /Sys and aMode is neither EFileShareReadersOnly nor EFileRead then Tcb capability is required. If the path for aName is /Sys and aMode is either EFileShareReadersOnly or EFileRead then Allfiles capability is required. If the path for aName begins with /Private and does not match this process' SID then AllFiles capability is required. If the path for aName begins with /Resource and aMode is neither EFileShareReadersOrWriters|EFileRead nor EFileShareReadersOnly nor EFileRead then Tcb capability is required.

IMPORT_C 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:

1. To close the file, use Close()

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

3. Attempting to open a file which is greater than or equal to 2GByte (2,147,483,648 bytes) will fail with KErrTooBig

4. 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. See TFileMode.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

See also:


Close()

IMPORT_C void Close();

Description

Closes the file.

Any open files are closed when the file server session is closed.

Close() is guaranteed to return, and provides no indication whether it completed successfully or not. When closing a file you have written to, you should ensure that data is committed to the file by invoking RFile::Flush() before closing. If Flush() completes successfully, Close() is essentially a no-operation.


Create()

Capability: Dependent If the path in aName starts with /Sys then capability Tcb is required If the path in aName starts with /Resource then capability Tcb is required If the path in aName starts with /Private and does not match this process' SID then AllFiles capability is required.

IMPORT_C 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.

If the resulting path does not exist, then the operation cannot proceed and the function returns an error code.

Notes:

1. To close the file, use Close()

2. It 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 (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. The access mode is automatically set to EFileWrite. See TFileMode.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

See also:


Replace()

Capability: Dependent If the path in aName starts with /Sys then capability Tcb is required If the path in aName starts with /Resource then capability Tcb is required If the path in aName starts with /Private and does not match this process' SID then AllFiles capability is required.

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

Description

Opens a file for writing, replacing the content of any existing file of the same name if it exists, or creating a new file if it does not exist.

If the resulting path exists, then:

If the resulting path does not exist, then the operation cannot proceed and the function returns an error code.

Notes:

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. The access mode is automatically set to EFileWrite. See TFileMode.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

See also:


Temp()

Capability: Dependent If aPath starts with /Sys then capability Tcb is required If aPath starts with /Resource then capability Tcb is required If aPath starts with /Private and does not match this process' SID then AllFiles capability is required.

IMPORT_C 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.

Notes:

1. To close the file, use Close()

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. The access mode is automatically set to EFileWrite. See TFileMode.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

See also:


Read()

IMPORT_C TInt Read(TDes8 &aDes) const;

Description

Reads from the file at the current position.

This is a synchronous function.

Note that 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 read into it. Therefore, when reading through a file,the end of file has been reached when the descriptor length, as returned by TDesC8::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 one of the other system-wide error codes.


Read()

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

Description

Reads from the file at the current position.

This is an asynchronous function.

Note that 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 read into it. Therefore, when reading through a file,the end of file has been reached when the descriptor length, as returned by TDesC8::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. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TRequestStatus &aStatus

Request status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes.


Read()

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

Description

Reads the specified number of bytes of binary data from the file at the current position.

This is a synchronous function.

Note that 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 read into it. Therefore, when reading through a file,the end of file has been reached when the descriptor length, as returned by TDesC8::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, is when the end of file is reached or if an error occurs.

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 be 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. This value must not be negative, otherwise the function returns KErrArgument.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


Read()

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

Description

Reads a specified number of bytes of binary data from the file at the current position.

This is an asynchronous function.

Note that 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 read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length, as returned by TDesC8::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 is 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. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TInt aLength

The number of bytes to be read from the file into the descriptor. If an attempt is made to read more bytes than the descriptor's maximum length, then the function updates aStatus parameter with KErrOverflow. It must not be negative otherwise the function updates aStatus with KErrArgument.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.


Read()

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

Description

Reads from the file at the specified offset within the file

This is a synchronous function.

Note that 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 read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length, as returned by TDesC8::Length(), is zero.

Parameters

TInt aPos

Position of first byte to be read. This is an offset from the start of the file. If no position is specified, reading begins at the current file position. If aPos is beyond the end of the file, the function returns a zero length descriptor. Specify KCurrentPosition to read from the current file position.

TDes8 &aDes

The descriptor into which binary data is read. Any existing content is overwritten. On return, its length is set to the number of bytes read.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Read()

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

Description

Reads from the file at the specified offset within the file.

This is an asynchronous function.

Note that 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 read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length, as returned by TDesC8::Length(), is zero.

Parameters

TInt aPos

Position of first byte to be read. This is an offset from the start of the file. If no position is specified, reading begins at the current file position. If aPos is beyond the end of the file, the function returns a zero length descriptor. Specify KCurrentPosition to read from the current file position.

TDes8 &aDes

The descriptor into which binary data is read. Any existing content is overwritten. On return, its length is set to the number of bytes read. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TRequestStatus &aStatus

The request status. On completion, contains an error code of KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Read()

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

Description

Reads the specified number of bytes of binary data from the file at a specified offset within the file.

This is a synchronous function.

Note that 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 read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length, as returned by TDesC8::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 is when the end of file is reached or if an error has occurred.

Parameters

TInt aPos

Position of first byte to be read. This is an offset from the start of the file. If no position is specified, reading begins at the current file position. If aPos is beyond the end of the file, the function returns a zero length descriptor. Specify KCurrentPosition to read from the current file position.

TDes8 &aDes

The 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, then the function updates aStatus parameter with KErrOverflow. It must not be negative otherwise the function updates aStatus with KErrArgument.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Read()

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

Description

Reads the specified number of bytes of binary data from the file at a specified offset within the file.

This is an asynchronous function.

Note that 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 read into it. Therefore, when reading through a file, the end of file has been reached when the descriptor length, as returned by TDesC8::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 is when the end of file is reached or if an error has occurred.

Parameters

TInt aPos

Position of first byte to be read. This is an offset from the start of the file. If no position is specified, reading begins at the current file position. If aPos is beyond the end of the file, the function returns a zero length descriptor. Specify KCurrentPosition to read from the current file position.

TDes8 &aDes

The descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

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, then the function returns KErrOverflow. It must not be negative otherwise the function returns KErrArgument.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


ReadCancel()

IMPORT_C void ReadCancel(TRequestStatus &aStatus) const;

Description

Cancels a specific outstanding asynchronous read request.

The outstanding request completes with KErrCancel.

Parameters

TRequestStatus &aStatus


ReadCancel()

IMPORT_C void ReadCancel() const;

Description

Cancels all outstanding asynchronous read requests for this subsession.

All outstanding requests complete with KErrCancel.


Write()

IMPORT_C TInt Write(const TDesC8 &aDes);

Description

Writes to the file at the current offset within the file.

This is a synchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

const TDesC8 &aDes

The 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 one of the other system-wide error codes.


Write()

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

Description

Writes to the file at the current offset within the file.

This is an asynchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

const TDesC8 &aDes

The descriptor from which binary data is written. The function writes the entire contents of aDes to the file. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.


Write()

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

Description

Writes a portion of a descriptor to the file at the current offset within the file.

This is a synchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

const TDesC8 &aDes

The descriptor from which binary data is written.

TInt aLength

The number of bytes to be written from the descriptor. This must not be greater than the length of the descriptor. It must not be negative.

Return value

TInt

KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

27 in debug mode, if aLength is greater than the length of the descriptor aDes.


Write()

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

Description

Writes a portion of a descriptor to the file at the current offset within the file.

This is an asynchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

const TDesC8 &aDes

The descriptor from which binary data is written. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TInt aLength

The number of bytes to be written from the descriptor. This must not be greater than the length of the descriptor. It must not be negative.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.


Write()

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

Description

Writes to the file at the specified offset within the file

This is a synchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

TInt aPos

The offset from the start of the file at which the first byte is written. If a position beyond the end of the file is specified, then the write operation begins at the end of the file. If the position has been locked, then the write fails. Specify KCurrentPosition to write to the current file position.

const TDesC8 &aDes

The 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 one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Write()

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

Description

Writes to the file at the specified offset within the file

This is an asynchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

TInt aPos

The offset from the start of the file at which the first byte is written. If a position beyond the end of the file is specified, then the write operation begins at the end of the file. If the position has been locked, then the write fails. Specify KCurrentPosition to write to the current file position.

const TDesC8 &aDes

The descriptor from which binary data is written. The function writes the entire contents of aDes to the file. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Write()

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

Description

Writes the specified number of bytes to the file at the specified offset within the file.

This is a synchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

TInt aPos

The offset from the start of the file at which the first byte is written. If a position beyond the end of the file is specified, then the write operation begins at the end of the file. If the position has been locked, then the write fails. Specify KCurrentPosition to write to the current file position.

const TDesC8 &aDes

The descriptor from which binary data is written.

TInt aLength

The number of bytes to be written from aDes . It must not be negative.

Return value

TInt

KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Write()

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

Description

Writes the specified number of bytes to the file at the specified offset within the file.

This is an asynchronous function.

NB Attempting to extend the file to 2 GByte or greater will fail with KErrTooBig

Parameters

TInt aPos

The offset from the start of the file at which the first byte is written. If a position beyond the end of the file is specified, then the write operation begins at the end of the file. If the position has been locked, then the write fails. Specify KCurrentPosition to write to the current file position.

const TDesC8 &aDes

The descriptor from which binary data is written. NB: this function is asynchronous and the request that it represents may not complete until some time after the call to the function has returned. It is important, therefore, that this descriptor remain valid, or remain in scope, until you have been notified that the request is complete.

TInt aLength

The number of bytes to be written from aDes. It must not be negative.

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

19 if aPos is negative.


Lock()

IMPORT_C TInt Lock(TInt aPos, TInt aLength) const;

Description

Locks a region within the file as defined by a range of bytes.

This ensures that those bytes are accessible only through the RFile object which claims 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.

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; this is the offset from the beginning of the file.

TInt aLength

Number of bytes to lock.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

17 if aLength is not greater than zero,


UnLock()

IMPORT_C TInt UnLock(TInt aPos, TInt aLength) const;

Description

Unlocks a region within the file as defined by a range of bytes.

A lock can only be removed by the RFile object which claimed the lock.

A portion of a locked region cannot be unlocked. The entire locked region must be unlocked otherwise 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; this is the offset from the beginning of the file.

TInt aLength

Number of bytes to unlock.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

18 if aLength is not greater than zero,


Seek()

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

Description

Sets the the current file position.

The function 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.

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, then:

1. the function does not modify the aPos argument,

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

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

1. the file is not in ROM,

2. 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, then 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 one of the other system-wide error codes.


Flush()

IMPORT_C TInt Flush();

Description

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

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 one of the other system-wide error codes.


Flush()

IMPORT_C void Flush(TRequestStatus &aStatus);

Description

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

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.

Parameters

TRequestStatus &aStatus

Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.


Size()

IMPORT_C TInt Size(TInt &aSize) const;

Description

Gets the current file size.

Parameters

TInt &aSize

On return, the size of the file in bytes.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


SetSize()

IMPORT_C TInt SetSize(TInt aSize);

Description

Sets the file size.

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

Note:

1. The current file position remains unchanged unless SetSize() reduces the size of the file in such a way 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.

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

Parameters

TInt aSize

The new size of the file, in bytes. This value must not be negative, otherwise the function raises a panic.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

20 If aSize is negative.


Att()

IMPORT_C TInt Att(TUint &aAttValue) const;

Description

Gets the file's attributes.

Parameters

TUint &aAttValue

A bitmask which, on return, contains the file’s attributes. For more information, see KEntryAttNormal and the other file/directory attributes.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

See also:


SetAtt()

IMPORT_C 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:

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

2. A panic is raised if any attribute is specified in both bitmasks.

3. An attempt to set or clear the KEntryAttDir, KEntryAttVolume or KEntryAttRemote attributes have no effect.

4. 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, and the other file/directory attributes.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

21 if the same attribute bit is set in both bitmasks.


Modified()

IMPORT_C TInt Modified(TTime &aTime) const;

Description

Gets local date and time the file was last modified, in universal time.

Parameters

TTime &aTime

On return, contains the date and time the file was last modified in UTC.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


SetModified()

IMPORT_C TInt SetModified(const TTime &aTime);

Description

Sets the date and time the file was last modified. UTC date and time should be used.

Notes:

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

2. 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, in universal time.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


Set()

IMPORT_C 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 functionality of SetAtt() and SetModified()

Parameters

const TTime &aTime

The new date and time the file was last modified. UTC date and time should be used.

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, and the other file/directory attributes.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

21 if the same attribute bit is set in both bitmasks.


ChangeMode()

Capability: Dependent If the path starts with /Resource then capability DiskAdmin is required

IMPORT_C TInt ChangeMode(TFileMode aNewMode);

Description

Switches an open file's access mode between EFileShareExclusive and EFileShareReadersOnly.

This allows or disallows read-only access without having to close and re-open the file.

Parameters

TFileMode aNewMode

The new access mode.

Return value

TInt

KErrNone, if successful; KErrArgument, if aNewMode has any value other than the two specified; KErrAccessDenied, if: a) the function is called when the current file share mode is EFileShareAny; b) the file has multiple readers, and an attempt is made to change the share mode to EFileShareExclusive; c) the file has been opened for writing in EFileShareExclusive mode, and an attempt is made to change the access mode to EFileShareReadersOnly.


Rename()

Capability: Dependent If aNewName starts with /Sys then capability Tcb is required If aNewName starts with /Resource then capability Tcb is required If aNewName starts with /Private and does not match this process' SID then AllFiles capability is required.

IMPORT_C 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 that 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 one of the other system-wide error codes.


Drive()

IMPORT_C TInt Drive(TInt &aDriveNumber, TDriveInfo &aDriveInfo) const;

Description

Gets information about the drive on which this file resides.

Parameters

TInt &aDriveNumber

On return, the drive number.

TDriveInfo &aDriveInfo

On return, contains information describing the drive and the medium mounted on it. The value of TDriveInfo::iType shows whether the drive contains media.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes


Adopt()

IMPORT_C TInt Adopt(RFs &aFs, TInt aHandle);

Description

Adopts an already open file.

Parameters

RFs &aFs

The file server session.

TInt aHandle

The handle number of the already opened file

Return value

TInt

KErrNone if successful, KErrBadHandle if the sub-session handle is invalid, otherwise one of the other system-wide error codes.


AdoptFromClient()

IMPORT_C TInt AdoptFromClient(const RMessage2 &aMsg, TInt aFsHandleIndex, TInt aFileHandleIndex);

Description

Allows a server to adopt an already open file from a client. The client's RFs and RFile handles are contained in message slots within aMsg.

Assumes that the client's RFs and RFile handles have been sent to the server using TransferToServer().

This RFile will own it's RFs session so that when the sub-session (RFile) is closed so will the RFs session.

Parameters

const RMessage2 &aMsg

The message received from the client

TInt aFsHandleIndex

The index that identifies the message slot of a file server session (RFs) handle

TInt aFileHandleIndex

The index that identifies the message slot of the sub-session (RFile) handle of the already opened file

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


AdoptFromServer()

IMPORT_C TInt AdoptFromServer(TInt aFsHandle, TInt aFileHandle);

Description

Allows a client to adopt an already open file from a server,

Assumes that the server's RFs and RFile handles have been sent to the client using TransferToClient().

This RFile will own it's RFs session so that when the sub-session (RFile) is closed so will the RFs session.

Parameters

TInt aFsHandle

The file server session (RFs) handle

TInt aFileHandle

The file (RFile) handle of the already opened file

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


AdoptFromCreator()

IMPORT_C TInt AdoptFromCreator(TInt aFsIndex, TInt aFileHandleIndex);

Description

Allows a server to adopt an already open file from a client process. The client's file-server (RFs) and file (RFile) handles are contained in this process's environment data slots.

Assumes that the client's RFs and RFile handles have been sent to the server process using TransferToProcess().

This RFile will own it's RFs session so that when the sub-session (RFile) is closed so will the RFs session.

Parameters

TInt aFsIndex

An index that identifies the slot in the process environment data that contains the file server session (RFs) handle

TInt aFileHandleIndex

An index that identifies the slot in the process environment data that contains the sub-session (RFile) handle of the already opened file

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


Name()

IMPORT_C TInt Name(TDes &aName) const;

Description

Gets the final part of a filename

This is used to retrieve the name and extension of a file that has been passed from one process to another using the RFile::AdoptXXX() methods.

Parameters

TDes &aName

On return, contains the name of the file, including the name and extension but excluding the drive letter and path.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


TransferToServer()

IMPORT_C TInt TransferToServer(TIpcArgs &aIpcArgs, TInt aFsHandleIndex, TInt aFileHandleIndex) const;

Description

Transfers an already open file to a server.

Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected().

This function packages handle details for this file into 2 arguments of a TIpcArgs object. When these arguments are sent in an IPC message, the server which receives them may call AdoptFromClient() to open a new RFile object which refers to the same file as this.

Parameters

TIpcArgs &aIpcArgs

The IPC message arguments.

TInt aFsHandleIndex

An index that identifies an argument in aIpcArgs where the file server session handle will be stored. This argument must not be used for anything else otherwise the results will be unpredictable.

TInt aFileHandleIndex

An index that identifies an argument in aIpcArgs where the file handle will be stored. This argument must not be used for anything else otherwise the results will be unpredictable.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


TransferToClient()

IMPORT_C TInt TransferToClient(const RMessage2 &aMsg, TInt aFileHandleIndex) const;

Description

Transfers an already open file from a server to a client.

Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected().

The file (RFile) handle is written to the client's address space to the package buffer in the message address slot in aMsg identified by aFileHandleIndex.

If no error occurs, then the message is completed with the file-server (RFs) session handle.

When the message completes, the client may call AdoptFromServer() to open a new RFile object which refers to the same file as this.

Note that if an error occurs then the message is not completed.

Parameters

const RMessage2 &aMsg

A message received from the client

TInt aFileHandleIndex

Identifies the message slot that contains a package buffer pointing to an address in the client's address space to receive the file (RFile) handle

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


TransferToProcess()

IMPORT_C TInt TransferToProcess(RProcess &aProcess, TInt aFsHandleIndex, TInt aFileHandleIndex) const;

Description

Transfers an already open file to another process.

Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected().

This function packages handle details for this file into 2 arguments in another process's environment data slots. When the other process runs, it may call AdoptFromCreator() to open a new RFile object which refers to the same file as this.

Parameters

RProcess &aProcess

A handle to another process.

TInt aFsHandleIndex

An index that identifies a slot in the process's environment data which on exit will contain the file server session (RFs) handle This slot must not be used for anything else otherwise the results will be unpredictable.

TInt aFileHandleIndex

An index that identifies a slot in the process's environment data which on exit will contain the file (RFile) handle. This slot must not be used for anything else otherwise the results will be unpredictable.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


Duplicate()

IMPORT_C TInt Duplicate(const RFile &aFile, TOwnerType aType=EOwnerProcess);

Description

Make a duplicate of the passed file handle in the same thread.

By default, any thread in the process can use the duplicated handle to access the file. However, specifying EOwnerThread as the second parameter to this function, means that only the creating thread can use the handle.

Parameters

const RFile &aFile

The file handle to duplicate

TOwnerType aType

An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

one of the other system-wide error codes.


FullName()

IMPORT_C TInt FullName(TDes &aName) const;

Description

Gets the full filename

This is used to retrieve the full filename, including drive and path, of a file that has been passed from one process to another using the RFile::AdoptXXX() methods.

Parameters

TDes &aName

On return, contains the full name of the file, including drive and path.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


BlockMap()

IMPORT_C TInt BlockMap(SBlockMapInfo &aInfo, TInt64 &aStartPos, TInt64 aEndPos=-1, TInt aBlockMapusage=EBlockMapUsagePaging) const;

Description

Fetches the Block Map of a file. Each file in the file system will consist of a number of groups of blocks. Each group represents a number of contiguous blocks. Such a group is represented by the TBlockMapEntry class. The full Block Map representing the file may be determined by repeatedly calling RFile::BlockMap until KErrCompletion is returned.

Note:

1. If the Block Map for the whole file is not required, then a start and end position for a section of the file can be specified. Both of these parameters specify offsets from the start of the file in bytes.

Parameters

SBlockMapInfo &aInfo

A structure describing a group of block maps.

TInt64 &aStartPos

A start position for a desired section of the file.

TInt64 aEndPos

An end position for a desired section of the file. If not passed, then the end of the file is assumed.

TInt aBlockMapusage

Return value

TInt

KErrNone until the end of the file or the file section is successfully reached; KErrCompletion if the end of the file is reached; KErrNotSupported if the file system does not support Block Mapping or the media is either removable or not pageable.