![[Index]](../../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../a_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
||
Location:
f32file.h
Link against: efsrv.lib
class RFile : public RSubSessionBase;
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).
RSubSessionBase - Client-side handle to a sub-session
RFile - Creates and opens a file, and performs all operations on a single open file
Defined in RFile:
Adopt(), AdoptFromClient(), AdoptFromCreator(), AdoptFromServer(), Att(), BlockMap(), ChangeMode(), Close(), Create(), Drive(), Duplicate(), Flush(), Flush(), FullName(), Lock(), Modified(), Name(), Open(), Read(), Read(), Read(), Read(), Read(), Read(), Read(), Read(), ReadCancel(), ReadCancel(), Rename(), Replace(), Seek(), Set(), SetAtt(), SetModified(), SetSize(), Size(), Temp(), TransferToClient(), TransferToProcess(), TransferToServer(), UnLock(), Write(), Write(), Write(), Write(), Write(), Write(), Write(), Write()
Inherited from RSubSessionBase:
CloseSubSession(),
CreateAutoCloseSubSession(),
CreateSubSession(),
Send(),
SendReceive(),
Session(),
SubSessionHandle()
| Capability: | Dependent | If the path for aName is /Sys and aMode is neither EFileShareReadersOnly nor EFileRead then Tcb capability is required. If the path for aName is /Sys and aMode is either EFileShareReadersOnly or EFileRead then Allfiles capability is required. If the path for aName begins with /Private and does not match this process' SID then AllFiles capability is required. If the path for aName begins with /Resource and aMode is neither EFileShareReadersOrWriters|EFileRead nor EFileShareReadersOnly nor EFileRead then Tcb capability is required. |
IMPORT_C TInt Open(RFs &aFs, const TDesC &aName, TUint aFileMode);
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.
|
|
IMPORT_C void Close();
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.
| Capability: | Dependent | If the path in aName starts with /Sys then capability Tcb is required If the path in aName starts with /Resource then capability Tcb is required If the path in aName starts with /Private and does not match this process' SID then AllFiles capability is required. |
IMPORT_C TInt Create(RFs &aFs, const TDesC &aName, TUint aFileMode);
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.
|
|
| Capability: | Dependent | If the path in aName starts with /Sys then capability Tcb is required If the path in aName starts with /Resource then capability Tcb is required If the path in aName starts with /Private and does not match this process' SID then AllFiles capability is required. |
IMPORT_C TInt Replace(RFs &aFs, const TDesC &aName, TUint aFileMode);
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.
|
|
| Capability: | Dependent | If aPath starts with /Sys then capability Tcb is required If aPath starts with /Resource then capability Tcb is required If aPath starts with /Private and does not match this process' SID then AllFiles capability is required. |
IMPORT_C TInt Temp(RFs &aFs, const TDesC &aPath, TFileName &aName, TUint aFileMode);
Creates and opens a temporary file with a unique name for writing and reading.
Notes:
1. To close the file, use Close()
|
|
IMPORT_C TInt Read(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.
|
|
IMPORT_C void Read(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.
|
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.
|
|
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.
|
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.
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.
|
|
|
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.
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.
|
|
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.
|
|
|
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.
|
|
IMPORT_C void ReadCancel(TRequestStatus &aStatus) const;
Cancels a specific outstanding asynchronous read request.
The outstanding request completes with KErrCancel.
|
IMPORT_C void ReadCancel() const;
Cancels all outstanding asynchronous read requests for this subsession.
All outstanding requests complete with KErrCancel.
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
|
|
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
|
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
|
|
|
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
|
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
|
|
|
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
|
|
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
|
|
|
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
|
|
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.
|
|
|
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.
|
|
|
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.
|
|
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.
|
IMPORT_C void Flush(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.
|
IMPORT_C TInt Size(TInt &aSize) const;
Gets the current file size.
|
|
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.
|
|
|
IMPORT_C TInt Att(TUint &aAttValue) const;
Gets the file's attributes.
|
|
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).
|
|
|
IMPORT_C TInt Modified(TTime &aTime) const;
Gets local date and time the file was last modified, in universal time.
|
|
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).
|
|
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()
|
|
|
| Capability: | Dependent | If the path starts with /Resource then capability DiskAdmin is required |
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 aNewName starts with /Sys then capability Tcb is required If aNewName starts with /Resource then capability Tcb is required If aNewName starts with /Private and does not match this process' SID then AllFiles capability is required. |
IMPORT_C TInt Rename(const TDesC &aNewName);
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.
|
|
IMPORT_C TInt Drive(TInt &aDriveNumber, TDriveInfo &aDriveInfo) const;
Gets information about the drive on which this file resides.
|
|
IMPORT_C TInt Adopt(RFs &aFs, TInt aHandle);
Adopts an already open file.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
|
Copyright ©2008 Symbian Software Ltd. |
|
![[Previous]](../../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../../a_stock/btn_top.gif)
![[Next]](../../../../a_stock/btn_next.gif){kind=small}