Enum TFileMode

TFileMode

Description

Access and share modes available when opening a file.

The access mode indicates whether the file is opened just for reading or for writing.

The share mode indicates whether other RFile objects can access the open file, and whether this access is read only.

Use EFileShareReadersOrWriters if a client does not care whether the file has been previously opened for ReadOnly or Read/Write access.

If EFileShareReadersOrWriters is not used, then a client needs to cooperate with other clients in order to open the file with the correct share mode, either EFileShareReadersOnly or EFileShareAny, depending on the share mode used when the file was originally opened.

To open a file for reading and writing with read and write shared access, use:

_LIT(KFilename, "filename.ext");
RFile file;
file.Open(theFs, KFilename, EFileShareAny|EFileWrite);

If another instance of RFile tries to open this file in EFileShareExclusive or EFileShareReadersOnly mode, access is denied. However, it can be opened in EFileShareAny mode or EFileShareReadersOrWriters mode.

If a file is opened with EFileShareReadersOrWriters, and the file is opened for sharing by another client, then the file share mode is promoted to the new share mode. When the file handle is closed then the share mode is demoted back to EFileShareReadersOrWriters.

Table of FileShare promotion rules
----------------------------------

Client A                   Client B                            Resultant Share Mode 
--------                    --------                            --------------------
ReadersOnly                 ReadersOnly                        ReadersOnly
ReadersOnly                 ReadersOrWriters|EFileRead         ReadersOnly
ReadersOnly                 ReadersOrWriters|EFileWrite        INCOMPATIBLE
ReadersOnly                 Any                                INCOMPATIBLE

ReadersOrWriters|EFileRead  ReadersOnly                       ReadersOnly
ReadersOrWriters|EFileRead  ReadersOrWriters|EFileRead        ReadersOrWriters
ReadersOrWriters|EFileRead  ReadersOrWriters|EFileWrite       ReadersOrWriters
ReadersOrWriters|EFileRead  Any                               Any

ReadersOrWriters|EFileWrite ReadersOnly                        INCOMPATIBLE
ReadersOrWriters|EFileWrite ReadersOrWriters|EFileRead         ReadersOrWriters
ReadersOrWriters|EFileWrite ReadersOrWriters|EFileWrite        ReadersOrWriters
ReadersOrWriters|EFileWrite Any                                Any

Any                         ReadersOnly                        INCOMPATIBLE
Any                         ReadersOrWriters|EFileRead         Any
Any                         ReadersOrWriters|EFileWrite        Any
Any                         Any                                Any

Use the following guidance notes for selecting FileShare mode with shared RFile objects:

EFileShareAny

• Use this mode to request both read and write access when another client needs to write to the file and respective client access to the file is coordinated.

• To open a file for non-exclusive write, use EFileShareAny | EFileWrite.

• It is recommended that either EFileShareAny or EFileShareAny | EFileRead are not used. These combinations will block users attempting to use the EFileShareReadersOnly mode even if all the EFileShareAny handles do not have the EFileWrite bit set as the EFileRead and EFileWrite bits have no affect on sharing. Use either EFileShareReadersOnly or EFileShareReadersOrWriters.

EFileShareReadersOrWriters

• Use this mode when it does not matter if another file writes to the file and file access can not be coordinated as other clients are unknown.

• To open a file for shared read access whilst permitting writers, use EFileShareReadersOrWriters | EFileRead.

• For write access with unrestricted share mode, EFileShareReadersOrWriters | EFileWrite may be used however EFilesShareAny | EFileWrite is preferred.

EFileShareReadersOnly

• Use this mode to get read access to the file and deny write access for any other handles on this file.

• To open a file for shared read access whilst disallowing writers use EFileShareReadersOnly.

Files may be opened in text or binary mode. Native Symbian OS application files are nearly all binary, (so they will usually be opened in binary mode). However, they can be opened in text mode (to support testing, and to make them compatible with text formats on remote systems). Symbian OS native text format uses CR-LF (ASCII 0x0d, 0x0a) to denote the end of a line. When reading, however, any combination of CR, LF, LF-CR or CR-LF is recognised as the end of a line. Where a remote file system uses a different format, it is the responsibility of the installable file system to present an interface for text files which conforms with this format.

The share mode may be OR’ed with either EFileStream or EFileStreamText.

Additionally, it may be OR’ed with either EFileRead or EFileWrite.

EFileShareExclusive Exclusive access for the program opening the file. No other program can access the file until it is closed. If another program is already accessing the file in any share mode, then an attempt to open it with an EFileShareExclusive will fail. EFileShareReadersOnly Read-only sharing. This means that the file may only be accessed for reading. A file cannot be opened using a share mode of EFileShareReadersOnly with an EFileWrite flag. EFileShareAny Shared access for reading and writing. This means that other programs may share access to the file for reading and writing with the program which opened the file. When using this mode, the program is expecting another program to be able to write to the file, so is not compatible with EFileShareReadersOnly. EFileShareReadersOrWriters Shared access for reading and writing. This means that other programs may share access to the file for reading and writing with the program which opened the file. When using this mode, the program does not care if another program has the file open for read or write access. EFileStream For files to be opened in binary mode. EFileStreamText For files to be opened in text mode. EFileRead The file may be read from but not written to. EFileWrite The file may be read from and written to Cannot be combined with a share mode of EFileShareReadersOnly. EFileReadAsyncAll Specifies that an asynchronous read request should not be completed until all requested data becomes available. Cannot be combined with the EFileShareExclusive or EFileShareReadersOnly share modes as this will prohibit a writer from updating the file. EFileWriteBuffered Enables write buffering EFileWriteDirectIO Disables write buffering EFileReadBuffered Enables read buffering EFileReadDirectIO Disables read buffering EFileReadAheadOn Enables read ahead. EFileReadAheadOff Disables read ahead.