RFile Class Reference

#include <f32file.h>

Link against: efsrv.lib

class RFile : public RSubSessionBase

Inherits from

RFile

Public Member Functions
EFSRV_IMPORT_C TInt	Adopt(RFs &, TInt)
EFSRV_IMPORT_C TInt	AdoptFromClient(const RMessage2 &, TInt, TInt)
EFSRV_IMPORT_C TInt	AdoptFromCreator(TInt, TInt)
EFSRV_IMPORT_C TInt	AdoptFromServer(TInt, TInt)
EFSRV_IMPORT_C TInt	Att(TUint &)
EFSRV_IMPORT_C TInt	BlockMap(SBlockMapInfo &, TInt64 &, TInt64, TInt)
EFSRV_IMPORT_C TInt	ChangeMode(TFileMode)
TInt	Clamp(RFileClamp &)
EFSRV_IMPORT_C void	Close()
EFSRV_IMPORT_C TInt	Create(RFs &, const TDesC &, TUint)
EFSRV_IMPORT_C TInt	Drive(TInt &, TDriveInfo &)
EFSRV_IMPORT_C TInt	Duplicate(const RFile &, TOwnerType)
EFSRV_IMPORT_C TInt	Flush()
EFSRV_IMPORT_C void	Flush(TRequestStatus &)
EFSRV_IMPORT_C TInt	FullName(TDes &)
EFSRV_IMPORT_C TInt	Lock(TInt, TInt)
EFSRV_IMPORT_C TInt	Modified(TTime &)
EFSRV_IMPORT_C TInt	Name(TDes &)
EFSRV_IMPORT_C TInt	Open(RFs &, const TDesC &, TUint)
EFSRV_IMPORT_C TInt	Read(TDes8 &)
EFSRV_IMPORT_C void	Read(TDes8 &, TRequestStatus &)
EFSRV_IMPORT_C TInt	Read(TDes8 &, TInt)
EFSRV_IMPORT_C void	Read(TDes8 &, TInt, TRequestStatus &)
EFSRV_IMPORT_C TInt	Read(TInt, TDes8 &)
EFSRV_IMPORT_C void	Read(TInt, TDes8 &, TRequestStatus &)
EFSRV_IMPORT_C TInt	Read(TInt, TDes8 &, TInt)
EFSRV_IMPORT_C void	Read(TInt, TDes8 &, TInt, TRequestStatus &)
EFSRV_IMPORT_C void	ReadCancel(TRequestStatus &)
EFSRV_IMPORT_C void	ReadCancel()
EFSRV_IMPORT_C TInt	Rename(const TDesC &)
EFSRV_IMPORT_C TInt	Replace(RFs &, const TDesC &, TUint)
EFSRV_IMPORT_C TInt	Seek(TSeek, TInt &)
EFSRV_IMPORT_C TInt	Set(const TTime &, TUint, TUint)
EFSRV_IMPORT_C TInt	SetAtt(TUint, TUint)
EFSRV_IMPORT_C TInt	SetModified(const TTime &)
EFSRV_IMPORT_C TInt	SetSize(TInt)
EFSRV_IMPORT_C TInt	Size(TInt &)
EFSRV_IMPORT_C TInt	Temp(RFs &, const TDesC &, TFileName &, TUint)
EFSRV_IMPORT_C TInt	TransferToClient(const RMessage2 &, TInt)
EFSRV_IMPORT_C TInt	TransferToProcess(RProcess &, TInt, TInt)
EFSRV_IMPORT_C TInt	TransferToServer(TIpcArgs &, TInt, TInt)
EFSRV_IMPORT_C TInt	UnLock(TInt, TInt)
EFSRV_IMPORT_C TInt	Write(const TDesC8 &)
EFSRV_IMPORT_C void	Write(const TDesC8 &, TRequestStatus &)
EFSRV_IMPORT_C TInt	Write(const TDesC8 &, TInt)
EFSRV_IMPORT_C void	Write(const TDesC8 &, TInt, TRequestStatus &)
EFSRV_IMPORT_C TInt	Write(TInt, const TDesC8 &)
EFSRV_IMPORT_C void	Write(TInt, const TDesC8 &, TRequestStatus &)
EFSRV_IMPORT_C TInt	Write(TInt, const TDesC8 &, TInt)
EFSRV_IMPORT_C void	Write(TInt, const TDesC8 &, TInt, TRequestStatus &)

Protected Member Functions
void	CloseSubSession(TInt)
TInt	CreateSubSession(const RSessionBase &, TInt, const TIpcArgs &)
TInt	DuplicateHandle(TInt &)
TInt	SendReceive(TInt, const TIpcArgs &)

Inherited Functions
	RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
	RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
	RSubSessionBase::RSubSessionBase()
	RSubSessionBase::Send(TInt)const
	RSubSessionBase::Send(TInt,const TIpcArgs &)const
	RSubSessionBase::SendReceive(TInt)const
	RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSubSessionBase::Session()const
	RSubSessionBase::SubSessionHandle()const

Detailed Description

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

These 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. Note that if a file exists, its length is reset to zero.

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

Member Function Documentation

Adopt ( RFs &, TInt )

EFSRV_IMPORT_C TInt	Adopt	(	RFs &	aFs,
			TInt	aHandle
		)

Adopts an already open file.

Deprecated

Parameter	Description
aFs	The file server session.
aHandle	The handle number of the already opened file

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

AdoptFromClient ( const RMessage2 &, TInt, TInt )

EFSRV_IMPORT_C TInt	AdoptFromClient	(	const RMessage2 &	aMsg,
			TInt	aFsHandleIndex,
			TInt	aFileHandleIndex
		)

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.

Parameter	Description
aMsg	The message received from the client
aFsHandleIndex	The index that identifies the message slot of a file server session (RFs) handle
aFileHandleIndex	The index that identifies the message slot of the sub-session (RFile) handle of the already opened file

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

AdoptFromCreator ( TInt, TInt )

EFSRV_IMPORT_C TInt	AdoptFromCreator	(	TInt	aFsIndex,
			TInt	aFileHandleIndex
		)

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.

Parameter	Description
aFsIndex	An index that identifies the slot in the process environment data that contains the file server session (RFs) handle
aFileHandleIndex	An index that identifies the slot in the process environment data that contains the sub-session (RFile) handle of the already opened file

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

AdoptFromServer ( TInt, TInt )

EFSRV_IMPORT_C TInt	AdoptFromServer	(	TInt	aFsHandle,
			TInt	aFileHandle
		)

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.

Parameter	Description
aFsHandle	The file server session (RFs) handle
aFileHandle	The file (RFile) handle of the already opened file

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

Att ( TUint & )

EFSRV_IMPORT_C TInt

Att

(

TUint &

aAttValue

)

const

Gets the file's attributes.

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

BlockMap ( SBlockMapInfo &, TInt64 &, TInt64, TInt )

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

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.

Parameter	Description
aInfo	A structure describing a group of block maps.
aStartPos	A start position for a desired section of the file.
aEndPos	An end position for a desired section of the file. If not passed, then the end of the file is assumed.

Returns: 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.

ChangeMode ( TFileMode )

EFSRV_IMPORT_C TInt

ChangeMode

(

TFileMode

aNewMode

)

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.

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

Parameter	Description
aNewMode	The new access mode.

Returns: 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.

Clamp ( RFileClamp & )

TInt

Clamp

(

RFileClamp &

aHandle

)

Instructs the File Server that the file is not to be modified on storage media.

Parameter	Description
aHandle	On return, a handle to the file.

Close ( )

EFSRV_IMPORT_C void

(

)

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.

CloseSubSession ( TInt )

void

CloseSubSession

(

TInt

aFunction

)

[protected]

Reimplemented from RSubSessionBase::CloseSubSession(TInt)

Create ( RFs &, const TDesC &, TUint )

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

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.

See also: TFileMode

capability: Dependent If the path in aName starts with /Sys then capability Tcb is required

capability: Dependent If the path in aName starts with /Resource then capability Tcb is required

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

Parameter	Description
aFs	The file server session.
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. The file name shall not contain wild cards ('?' or '*' characters) and illegal characters like '<', '>', ':', '"', '/', '\|' and ''. Backslash '\' character is allowed only as a path delimiter. The filename containing only white space characters (See TChar::IsSpace()) is also illegal.
aFileMode	The mode in which the file is opened. The access mode is automatically set to EFileWrite. See TFileMode.

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

CreateSubSession ( const RSessionBase &, TInt, const TIpcArgs & )

TInt	CreateSubSession	(	const RSessionBase &	aSession,
			TInt	aFunction,
			const TIpcArgs &	aArgs
		)	[protected]

Reimplemented from RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)

Creates a new sub-session within an existing session.

Parameter	Description
aSession	The session to which this sub-session will belong.
aFunction	The opcode specifying the requested service; the server should interpret this as a request to create a sub-session.
aArgs	The message arguments.

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

Drive ( TInt &, TDriveInfo & )

EFSRV_IMPORT_C TInt	Drive	(	TInt &	aDriveNumber,
			TDriveInfo &	aDriveInfo
		)	const

Gets information about the drive on which this file resides.

Parameter	Description
aDriveNumber	On return, the drive number.
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.

Duplicate ( const RFile &, TOwnerType )

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

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.

Parameter	Description
aFile	The file handle to duplicate
aType	An enumeration whose enumerators define the ownership of this handle. If not explicitly specified, EOwnerProcess is taken as default.

Returns: one of the other system-wide error codes.

DuplicateHandle ( TInt & )

TInt

DuplicateHandle

(

TInt &

aSubSessionHandle

)

const [protected]

Flush ( )

EFSRV_IMPORT_C TInt

Flush

(

)

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.

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

Flush ( TRequestStatus & )

EFSRV_IMPORT_C void

Flush

(

TRequestStatus &

aStatus

)

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

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

FullName ( TDes & )

EFSRV_IMPORT_C TInt

FullName

(

TDes &

aName

)

const

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.

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

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

Lock ( TInt, TInt )

EFSRV_IMPORT_C TInt	Lock	(	TInt	aPos,
			TInt	aLength
		)	const

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.

panic: FSCLIENT 17 if aLength is not greater than zero,

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
aPos	Position in file from which to lock; this is the offset from the beginning of the file.
aLength	Number of bytes to lock.

Returns: KErrNone if successful; KErrArgument if aPos+aLength>2G-1 boundary; otherwise one of the other system-wide error codes.

Modified ( TTime & )

EFSRV_IMPORT_C TInt

Modified

(

TTime &

aTime

)

const

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

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

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

Name ( TDes & )

EFSRV_IMPORT_C TInt

Name

(

TDes &

aName

)

const

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.

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

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

Open ( RFs &, const TDesC &, TUint )

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

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.

See also: TFileMode

capability: Dependent If the path for aName is /Sys and aMode is neither EFileShareReadersOnly nor EFileRead then Tcb capability is required.

capability: Dependent If the path for aName is /Sys and aMode is either EFileShareReadersOnly or EFileRead then Allfiles capability is required.

capability: Dependent If the path for aName begins with /Private and does not match this process' SID then AllFiles capability is required.

capability: Dependent If the path for aName begins with /Resource and aMode is neither EFileShareReadersOrWriters|EFileRead nor EFileShareReadersOnly nor EFileRead then Tcb capability is required.

Parameter	Description
aFs	The file server session.
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.The file name shall not contain wild cards ('?' or '*' characters) and illegal characters like '<', '>', ':', '"', '/', '\|' and ''. Backslash '\' character is allowed only as a path delimiter. The filename containing only white space characters (See TChar::IsSpace()) is also illegal.
aFileMode	The mode in which the file is opened. See TFileMode.

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

Read ( TDes8 & )

EFSRV_IMPORT_C TInt

Read

(

TDes8 &

aDes

)

const

Reads from the file at the current position.

This is a synchronous function.

Read ( TDes8 &, TRequestStatus & )

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

Reads from the file at the current position.

This is an asynchronous function.

Read ( TDes8 &, TInt )

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

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.

Parameter	Description
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.
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.

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

Read ( TDes8 &, TInt, TRequestStatus & )

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

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.

Parameter	Description
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.
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.
aStatus	Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

Read ( TInt, TDes8 & )

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

Reads from the file at the specified offset within the file

This is a synchronous function.

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.

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

Read ( TInt, TDes8 &, TRequestStatus & )

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

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

This is an asynchronous function.

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.
aStatus	The request status. On completion, contains an error code of KErrNone if successful, otherwise one of the other system-wide error codes.

Read ( TInt, TDes8 &, TInt )

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

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.

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.
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.

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

Read ( TInt, TDes8 &, TInt, TRequestStatus & )

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

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.

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.
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.
aStatus	Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

ReadCancel ( TRequestStatus & )

EFSRV_IMPORT_C void

ReadCancel

(

TRequestStatus &

aStatus

)

const

Cancels a specific outstanding asynchronous read request.

The outstanding request completes with KErrCancel.

ReadCancel ( )

EFSRV_IMPORT_C void

ReadCancel

(

)

const

Cancels all outstanding asynchronous read requests for this subsession.

All outstanding requests complete with KErrCancel.

Rename ( const TDesC & )

EFSRV_IMPORT_C TInt

Rename

(

const TDesC &

aNewName

)

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.

capability: Dependent If aNewName starts with /Sys then capability Tcb is required

capability: Dependent If aNewName starts with /Resource then capability Tcb is required

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

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

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

Replace ( RFs &, const TDesC &, TUint )

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

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:

the length of an existing file with the same filename is re-set to zero

a new file is created, if no existing file with the same filename can be found.

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

Notes:

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

It automatically sets the file's archive attribute.

See also: TFileMode

capability: Dependent If the path in aName starts with /Sys then capability Tcb is required

capability: Dependent If the path in aName starts with /Resource then capability Tcb is required

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

Parameter	Description
aFs	The file server session.
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. The file name shall not contain wild cards ('?' or '*' characters) and illegal characters like '<', '>', ':', '"', '/', '\|' and ''. Backslash '\' character is allowed only as a path delimiter. The filename containing only white space characters (See TChar::IsSpace()) is also illegal.
aFileMode	The mode in which the file is opened. The access mode is automatically set to EFileWrite. See TFileMode.

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

Seek ( TSeek, TInt & )

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

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.

Parameter

Description

aMode

Seek mode. Controls the destination of the seek operation.

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.

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

SendReceive ( TInt, const TIpcArgs & )

TInt	SendReceive	(	TInt	aFunction,
			const TIpcArgs &	aArgs
		)	const [protected]

Reimplemented from RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const

Sends a message to the server and waits synchronously for a reply.

An opcode specifies the service required. A set of message arguments is passed that can be used to specify client addresses, which the server can use to read from and write to the client address space.

Note that this function will only fail if the server itself fails or environmental errors occur in the server. All requests made using this function are guaranteed to reach the server. This means that all synchronous client requests (typically those that return void) should be routed through this synchronous variant of SendReceive().

Parameter	Description
aFunction	The opcode specifying the requested service.
aArgs	The message arguments.

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

Set ( const TTime &, TUint, TUint )

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

Sets the file s attributes, and the date and time it was last modified.

It combines the functionality of SetAtt() and SetModified()

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

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

Parameter	Description
aTime	The new date and time the file was last modified. UTC date and time should be used.
aSetAttMask	A bitmask indicating the file attributes to be set
aClearAttMask	A bitmask indicating the attributes to be cleared. For more information see KEntryAttNormal, and the other file/directory attributes.

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

SetAtt ( TUint, TUint )

EFSRV_IMPORT_C TInt	SetAtt	(	TUint	aSetAttMask,
			TUint	aClearAttMask
		)

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

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

Parameter	Description
aSetAttMask	A bitmask indicating the file attributes to be set
aClearAttMask	A bitmask indicating the attributes to be cleared. For more information see KEntryAttNormal, and the other file/directory attributes.

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

SetModified ( const TTime & )

EFSRV_IMPORT_C TInt

SetModified

(

const TTime &

aTime

)

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

Parameter	Description
aTime	The new date and time the file was last modified, in universal time.

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

SetSize ( TInt )

EFSRV_IMPORT_C TInt

SetSize

(

TInt

aSize

)

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.

panic: FSCLIENT 20 If aSize is negative.

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

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

Size ( TInt & )

EFSRV_IMPORT_C TInt

Size

(

TInt &

aSize

)

const

Gets the current file size.

Parameter	Description
aSize	On return, the size of the file in bytes.

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

Temp ( RFs &, const TDesC &, TFileName &, TUint )

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

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

Notes:

1. To close the file, use Close()

See also: TFileMode

capability: Dependent If aPath starts with /Sys then capability Tcb is required

capability: Dependent If aPath starts with /Resource then capability Tcb is required

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

Parameter	Description
aFs	The file server session.
aPath	The directory in which the file is created.
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.
aFileMode	The mode in which the file is opened. The access mode is automatically set to EFileWrite. See TFileMode.

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

TransferToClient ( const RMessage2 &, TInt )

EFSRV_IMPORT_C TInt	TransferToClient	(	const RMessage2 &	aMsg,
			TInt	aFileHandleIndex
		)	const

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.

Parameter	Description
aMsg	A message received from the client
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

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

TransferToProcess ( RProcess &, TInt, TInt )

EFSRV_IMPORT_C TInt	TransferToProcess	(	RProcess &	aProcess,
			TInt	aFsHandleIndex,
			TInt	aFileHandleIndex
		)	const

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.

Parameter	Description
aProcess	A handle to another process.
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.
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.

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

TransferToServer ( TIpcArgs &, TInt, TInt )

EFSRV_IMPORT_C TInt	TransferToServer	(	TIpcArgs &	aIpcArgs,
			TInt	aFsHandleIndex,
			TInt	aFileHandleIndex
		)	const

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.

Parameter	Description
aIpcArgs	The IPC message arguments.
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.
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.

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

UnLock ( TInt, TInt )

EFSRV_IMPORT_C TInt	UnLock	(	TInt	aPos,
			TInt	aLength
		)	const

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.

panic: FSCLIENT 18 if aLength is not greater than zero,

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
aPos	Position in file from which to unlock; this is the offset from the beginning of the file.
aLength	Number of bytes to unlock.

Returns: KErrNone if successful; KErrArgument if aPos+aLength>2G-1 boundary; otherwise one of the other system-wide error codes.

Write ( const TDesC8 & )

EFSRV_IMPORT_C TInt

Write

(

const TDesC8 &

aDes

)

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

Parameter	Description
aDes	The descriptor from which binary data is written. The function writes the entire contents of aDes to the file.

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

Write ( const TDesC8 &, TRequestStatus & )

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

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

Parameter	Description
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.
aStatus	Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

Write ( const TDesC8 &, TInt )

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

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

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

Parameter	Description
aDes	The descriptor from which binary data is written.
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.

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

Write ( const TDesC8 &, TInt, TRequestStatus & )

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

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

Parameter	Description
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.
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.
aStatus	Request status. On completion contains KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.

Write ( TInt, const TDesC8 & )

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

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

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
aDes	The descriptor from which binary data is written. The function writes the entire contents of aDes to the file.

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

Write ( TInt, const TDesC8 &, TRequestStatus & )

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

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

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.
aStatus	Request status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

Write ( TInt, const TDesC8 &, TInt )

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

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

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
aDes	The descriptor from which binary data is written.
aLength	The number of bytes to be written from aDes . It must not be negative.

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

Write ( TInt, const TDesC8 &, TInt, TRequestStatus & )

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

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

panic: FSCLIENT 19 if aPos is negative.

Parameter	Description
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.
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.
aLength	The number of bytes to be written from aDes. It must not be negative.
aStatus	Request status. On completion contains KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.