RFile Class Reference

#include <f32file.h>

Link against: efsrv.lib

class RFile : public RSubSessionBase

Inherits from

  • RFile
    Public Member Functions
    EFSRV_IMPORT_C TIntAdopt(RFs &, TInt)
    EFSRV_IMPORT_C TIntAdoptFromClient(const RMessage2 &, TInt, TInt)
    EFSRV_IMPORT_C TIntAdoptFromCreator(TInt, TInt)
    EFSRV_IMPORT_C TIntAdoptFromServer(TInt, TInt)
    EFSRV_IMPORT_C TIntAtt(TUint &)
    EFSRV_IMPORT_C TIntBlockMap(SBlockMapInfo &, TInt64 &, TInt64, TInt)
    EFSRV_IMPORT_C TIntChangeMode(TFileMode)
    TInt Clamp(RFileClamp &)
    EFSRV_IMPORT_C voidClose()
    EFSRV_IMPORT_C TIntCreate(RFs &, const TDesC &, TUint)
    EFSRV_IMPORT_C TIntDrive(TInt &, TDriveInfo &)
    EFSRV_IMPORT_C TIntDuplicate(const RFile &, TOwnerType)
    EFSRV_IMPORT_C TIntFlush()
    EFSRV_IMPORT_C voidFlush(TRequestStatus &)
    EFSRV_IMPORT_C TIntFullName(TDes &)
    EFSRV_IMPORT_C TIntLock(TInt, TInt)
    EFSRV_IMPORT_C TIntModified(TTime &)
    EFSRV_IMPORT_C TIntName(TDes &)
    EFSRV_IMPORT_C TIntOpen(RFs &, const TDesC &, TUint)
    EFSRV_IMPORT_C TIntRead(TDes8 &)
    EFSRV_IMPORT_C voidRead(TDes8 &, TRequestStatus &)
    EFSRV_IMPORT_C TIntRead(TDes8 &, TInt)
    EFSRV_IMPORT_C voidRead(TDes8 &, TInt, TRequestStatus &)
    EFSRV_IMPORT_C TIntRead(TInt, TDes8 &)
    EFSRV_IMPORT_C voidRead(TInt, TDes8 &, TRequestStatus &)
    EFSRV_IMPORT_C TIntRead(TInt, TDes8 &, TInt)
    EFSRV_IMPORT_C voidRead(TInt, TDes8 &, TInt, TRequestStatus &)
    EFSRV_IMPORT_C voidReadCancel(TRequestStatus &)
    EFSRV_IMPORT_C voidReadCancel()
    EFSRV_IMPORT_C TIntRename(const TDesC &)
    EFSRV_IMPORT_C TIntReplace(RFs &, const TDesC &, TUint)
    EFSRV_IMPORT_C TIntSeek(TSeek, TInt &)
    EFSRV_IMPORT_C TIntSet(const TTime &, TUint, TUint)
    EFSRV_IMPORT_C TIntSetAtt(TUint, TUint)
    EFSRV_IMPORT_C TIntSetModified(const TTime &)
    EFSRV_IMPORT_C TIntSetSize(TInt)
    EFSRV_IMPORT_C TIntSize(TInt &)
    EFSRV_IMPORT_C TIntTemp(RFs &, const TDesC &, TFileName &, TUint)
    EFSRV_IMPORT_C TIntTransferToClient(const RMessage2 &, TInt)
    EFSRV_IMPORT_C TIntTransferToProcess(RProcess &, TInt, TInt)
    EFSRV_IMPORT_C TIntTransferToServer(TIpcArgs &, TInt, TInt)
    EFSRV_IMPORT_C TIntUnLock(TInt, TInt)
    EFSRV_IMPORT_C TIntWrite(const TDesC8 &)
    EFSRV_IMPORT_C voidWrite(const TDesC8 &, TRequestStatus &)
    EFSRV_IMPORT_C TIntWrite(const TDesC8 &, TInt)
    EFSRV_IMPORT_C voidWrite(const TDesC8 &, TInt, TRequestStatus &)
    EFSRV_IMPORT_C TIntWrite(TInt, const TDesC8 &)
    EFSRV_IMPORT_C voidWrite(TInt, const TDesC8 &, TRequestStatus &)
    EFSRV_IMPORT_C TIntWrite(TInt, const TDesC8 &, TInt)
    EFSRV_IMPORT_C voidWrite(TInt, const TDesC8 &, TInt, TRequestStatus &)
    Protected Member Functions
    voidCloseSubSession(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).

    See also: TDes8 TDesC8

    Member Function Documentation

    Adopt ( RFs &, TInt )

    EFSRV_IMPORT_C TIntAdopt(RFs &aFs,
    TIntaHandle
    )

    Adopts an already open file.

    Deprecated

    ParameterDescription
    aFsThe file server session.
    aHandleThe 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 TIntAdoptFromClient(const RMessage2 &aMsg,
    TIntaFsHandleIndex,
    TIntaFileHandleIndex
    )

    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.

    ParameterDescription
    aMsgThe message received from the client
    aFsHandleIndexThe index that identifies the message slot of a file server session (RFs) handle
    aFileHandleIndexThe 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 TIntAdoptFromCreator(TIntaFsIndex,
    TIntaFileHandleIndex
    )

    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.

    ParameterDescription
    aFsIndexAn index that identifies the slot in the process environment data that contains the file server session (RFs) handle
    aFileHandleIndexAn 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 TIntAdoptFromServer(TIntaFsHandle,
    TIntaFileHandle
    )

    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.

    ParameterDescription
    aFsHandleThe file server session (RFs) handle
    aFileHandleThe 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 TIntAtt(TUint &aAttValue)const

    Gets the file's attributes.

    See also: KEntryAttNormal

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

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

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

    EFSRV_IMPORT_C TIntBlockMap(SBlockMapInfo &aInfo,
    TInt64 &aStartPos,
    TInt64aEndPos = -1,
    TIntaBlockMapusage = 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.

    ParameterDescription
    aInfoA structure describing a group of block maps.
    aStartPosA start position for a desired section of the file.
    aEndPosAn 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 TIntChangeMode(TFileModeaNewMode)

    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
    ParameterDescription
    aNewModeThe 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.

    See also: RFs::Unclamp

    ParameterDescription
    aHandleOn return, a handle to the file.

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

    Close ( )

    EFSRV_IMPORT_C voidClose()

    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 )

    voidCloseSubSession(TIntaFunction)[protected]

    Reimplemented from RSubSessionBase::CloseSubSession(TInt)

    Create ( RFs &, const TDesC &, TUint )

    EFSRV_IMPORT_C TIntCreate(RFs &aFs,
    const TDesC &aName,
    TUintaFileMode
    )

    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.
    ParameterDescription
    aFsThe file server session.
    aNameThe 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.
    aFileModeThe 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,
    TIntaFunction,
    const TIpcArgs &aArgs
    )[protected]

    Creates a new sub-session within an existing session.

    ParameterDescription
    aSessionThe session to which this sub-session will belong.
    aFunctionThe opcode specifying the requested service; the server should interpret this as a request to create a sub-session.
    aArgsThe message arguments.

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

    Drive ( TInt &, TDriveInfo & )

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

    Gets information about the drive on which this file resides.

    See also: RFs::Drive

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

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

    Duplicate ( const RFile &, TOwnerType )

    EFSRV_IMPORT_C TIntDuplicate(const RFile &aFile,
    TOwnerTypeaType = 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.

    ParameterDescription
    aFileThe file handle to duplicate
    aTypeAn 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 TIntFlush()

    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 voidFlush(TRequestStatus &aStatus)

    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.

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

    FullName ( TDes & )

    EFSRV_IMPORT_C TIntFullName(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.

    ParameterDescription
    aNameOn 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 TIntLock(TIntaPos,
    TIntaLength
    )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.
    ParameterDescription
    aPosPosition in file from which to lock; this is the offset from the beginning of the file.
    aLengthNumber 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 TIntModified(TTime &aTime)const

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

    ParameterDescription
    aTimeOn 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 TIntName(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.

    ParameterDescription
    aNameOn 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 TIntOpen(RFs &aFs,
    const TDesC &aName,
    TUintaFileMode
    )

    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.
    ParameterDescription
    aFsThe file server session.
    aNameThe 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.
    aFileModeThe 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 TIntRead(TDes8 &aDes)const

    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.

    See also: TDesC8::Length

    ParameterDescription
    aDesDescriptor into which binary data is read. Any existing contents are 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 ( TDes8 &, TRequestStatus & )

    EFSRV_IMPORT_C voidRead(TDes8 &aDes,
    TRequestStatus &aStatus
    )const

    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.

    See also: TDesC8::Length

    ParameterDescription
    aDesDescriptor 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.
    aStatusRequest status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes.

    Read ( TDes8 &, TInt )

    EFSRV_IMPORT_C TIntRead(TDes8 &aDes,
    TIntaLength
    )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.

    ParameterDescription
    aDesDescriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
    aLengthThe 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 voidRead(TDes8 &aDes,
    TIntaLength,
    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.

    ParameterDescription
    aDesDescriptor 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.
    aLengthThe 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.
    aStatusRequest status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

    Read ( TInt, TDes8 & )

    EFSRV_IMPORT_C TIntRead(TIntaPos,
    TDes8 &aDes
    )const

    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.

    panic
    FSCLIENT 19 if aPos is negative.
    ParameterDescription
    aPosPosition 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.
    aDesThe 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 voidRead(TIntaPos,
    TDes8 &aDes,
    TRequestStatus &aStatus
    )const

    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.

    panic
    FSCLIENT 19 if aPos is negative.
    ParameterDescription
    aPosPosition 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.
    aDesThe 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.
    aStatusThe 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 TIntRead(TIntaPos,
    TDes8 &aDes,
    TIntaLength
    )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.
    ParameterDescription
    aPosPosition 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.
    aDesThe descriptor into which binary data is read. Any existing contents are overwritten. On return, its length is set to the number of bytes read.
    aLengthThe 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 voidRead(TIntaPos,
    TDes8 &aDes,
    TIntaLength,
    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.
    ParameterDescription
    aPosPosition 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.
    aDesThe 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.
    aLengthThe 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.
    aStatusRequest status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

    ReadCancel ( TRequestStatus & )

    EFSRV_IMPORT_C voidReadCancel(TRequestStatus &aStatus)const

    Cancels a specific outstanding asynchronous read request.

    The outstanding request completes with KErrCancel.

    ReadCancel ( )

    EFSRV_IMPORT_C voidReadCancel()const

    Cancels all outstanding asynchronous read requests for this subsession.

    All outstanding requests complete with KErrCancel.

    Rename ( const TDesC & )

    EFSRV_IMPORT_C TIntRename(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.
    ParameterDescription
    aNewNameThe 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 TIntReplace(RFs &aFs,
    const TDesC &aName,
    TUintaFileMode
    )

    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.
    ParameterDescription
    aFsThe file server session.
    aNameThe 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.
    aFileModeThe 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 TIntSeek(TSeekaMode,
    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.

    ParameterDescription
    aModeSeek mode. Controls the destination of the seek operation.
    aPosOffset 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(TIntaFunction,
    const TIpcArgs &aArgs
    )const [protected]

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

    ParameterDescription
    aFunctionThe opcode specifying the requested service.
    aArgsThe message arguments.

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

    Set ( const TTime &, TUint, TUint )

    EFSRV_IMPORT_C TIntSet(const TTime &aTime,
    TUintaSetAttMask,
    TUintaClearAttMask
    )

    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.

    See also: RFile::SetModified RFile::SetAtt

    ParameterDescription
    aTimeThe new date and time the file was last modified. UTC date and time should be used.
    aSetAttMaskA bitmask indicating the file attributes to be set
    aClearAttMaskA 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 TIntSetAtt(TUintaSetAttMask,
    TUintaClearAttMask
    )

    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.
    ParameterDescription
    aSetAttMaskA bitmask indicating the file attributes to be set
    aClearAttMaskA 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 TIntSetModified(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).

    ParameterDescription
    aTimeThe 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 TIntSetSize(TIntaSize)

    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.
    ParameterDescription
    aSizeThe 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 TIntSize(TInt &aSize)const

    Gets the current file size.

    ParameterDescription
    aSizeOn 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 TIntTemp(RFs &aFs,
    const TDesC &aPath,
    TFileName &aName,
    TUintaFileMode
    )

    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.
    ParameterDescription
    aFsThe file server session.
    aPathThe directory in which the file is created.
    aNameOn return, contains the full path and file name of the file. The filename is guaranteed to be unique within the directory specified by aPath.
    aFileModeThe 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 TIntTransferToClient(const RMessage2 &aMsg,
    TIntaFileHandleIndex
    )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.

    ParameterDescription
    aMsgA message received from the client
    aFileHandleIndexIdentifies 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 TIntTransferToProcess(RProcess &aProcess,
    TIntaFsHandleIndex,
    TIntaFileHandleIndex
    )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.

    ParameterDescription
    aProcessA handle to another process.
    aFsHandleIndexAn 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.
    aFileHandleIndexAn 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 TIntTransferToServer(TIpcArgs &aIpcArgs,
    TIntaFsHandleIndex,
    TIntaFileHandleIndex
    )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.

    ParameterDescription
    aIpcArgsThe IPC message arguments.
    aFsHandleIndexAn 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.
    aFileHandleIndexAn 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 TIntUnLock(TIntaPos,
    TIntaLength
    )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.
    ParameterDescription
    aPosPosition in file from which to unlock; this is the offset from the beginning of the file.
    aLengthNumber 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 TIntWrite(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

    ParameterDescription
    aDesThe 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 voidWrite(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

    ParameterDescription
    aDesThe 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.
    aStatusRequest status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

    Write ( const TDesC8 &, TInt )

    EFSRV_IMPORT_C TIntWrite(const TDesC8 &aDes,
    TIntaLength
    )

    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.
    ParameterDescription
    aDesThe descriptor from which binary data is written.
    aLengthThe 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 voidWrite(const TDesC8 &aDes,
    TIntaLength,
    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

    ParameterDescription
    aDesThe 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.
    aLengthThe 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.
    aStatusRequest 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 TIntWrite(TIntaPos,
    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.
    ParameterDescription
    aPosThe 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.
    aDesThe 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 voidWrite(TIntaPos,
    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.
    ParameterDescription
    aPosThe 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.
    aDesThe 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.
    aStatusRequest status. On completion contains KErrNone if successful, otherwise one of the other system-wide error codes.

    Write ( TInt, const TDesC8 &, TInt )

    EFSRV_IMPORT_C TIntWrite(TIntaPos,
    const TDesC8 &aDes,
    TIntaLength
    )

    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.
    ParameterDescription
    aPosThe 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.
    aDesThe descriptor from which binary data is written.
    aLengthThe 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 voidWrite(TIntaPos,
    const TDesC8 &aDes,
    TIntaLength,
    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.
    ParameterDescription
    aPosThe 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.
    aDesThe 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.
    aLengthThe number of bytes to be written from aDes. It must not be negative.
    aStatusRequest status. On completion contains KErrNone if successful; KErrArgument if aLength is negative; otherwise one of the other system-wide error codes.