// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

/**

 @file

 @publishedAll

 @released

*/

#if !defined(__F32FILE_H__)

#define __F32FILE_H__

#if !defined(__E32BASE_H__)

#include <e32base.h>

#endif

#ifndef SYMBIAN_ENABLE_PUBLIC_PLATFORM_HEADER_SPLIT

// Old implementation including platform e32svr.h (which includes the several other platform headers)...

#if !defined(__E32SVR_H__)

#include <e32svr.h>

#endif

#include <e32ldr.h>

#else

// New implementation including only the public headers needed for f32file.h...

#include <e32ldr.h>

// And the public headers previously included via e32svr.h but otherwise not needed for f32file.h...

#include <e32def.h>

#include <e32event.h>

#include <e32debug.h>

#include <e32keys.h> 

#endif

/**

@publishedAll

@released

The session default drive.

*/

const TInt KDefaultDrive=KMaxTInt;

/**

@publishedAll

@released

Indicates a drive letter which is not in use. 

This is useful when scanning a drive list to find which drives are available.

*/

const TInt KDriveAbsent=0x00;

/**

@publishedAll

@released

The default value for the number of message slots passed to RFs::Connect().

@see RFs::Connect

*/

const TInt KFileServerDefaultMessageSlots=-1;

/**

@publishedAll

@released

The size of the array of TEntry items contained in a TEntryArray object.

@see TEntryArray

@see TEntry

*/

const TInt KEntryArraySize=(0x200*sizeof(TText));

/**

@publishedAll

@released

The character used to separate directories in the path name.

*/

const TInt KPathDelimiter='\\';

/**

@publishedAll

@released

The character used to separate the drive letter from the path.

*/

const TInt KDriveDelimiter=':';

/**

@publishedAll

@released

The character used to separate the filename from the extension.

*/

const TInt KExtDelimiter='.';

/**

@publishedAll

@released

The maximum number of available drives.

*/

const TInt KMaxDrives=26;

/**

@publishedAll

@released

The maximum number of available proxy drives.

*/

const TInt KMaxProxyDrives=KMaxDrives-KMaxLocalDrives;

/**

@publishedAll

@released

Defines a modifiable buffer descriptor to contain a drive list.

The descriptor has maximum length KMaxDrives, sufficient to contain

all possible drive letters.

@see RFs::DriveList

@see KMaxDrives

*/

typedef TBuf8<KMaxDrives> TDriveList;

/**

@publishedAll

@released

The maximum length of a drivename.

Sufficient for a drive letter and colon.

*/

const TInt KMaxDriveName=0x02;

/**

@publishedAll

@released

Defines a modifiable buffer descriptor to contain a drive name.

A drive name comprises a drive letter (A through Z) and a colon.

KMaxDriveName (2 bytes) is sufficient for a drive letter and colon.

@see TDriveUnit::Name

@see KMaxDriveName

*/

typedef TBuf<KMaxDriveName> TDriveName;

/**

@publishedAll

@released

The maximum length of a file system name or file system sub type name.

32 characters is sufficient for a file system or sub type name.

*/

const TInt KMaxFSNameLength=0x0020;

/**

@publishedAll

@released

Defines a modifiable buffer descriptor to contain a file system or file system sub type name.

@see KMaxFSNameLength

*/

typedef TBuf<KMaxFSNameLength> TFSName;

/**

@publishedAll

@released

File/directory attribute: any file without the hidden or system attribute.

*/

const TUint KEntryAttNormal=0x0000;

/**

@publishedAll

@released

File/directory attribute: read-only file or directory.

*/

const TUint KEntryAttReadOnly=0x0001;

/**

@publishedAll

@released

File/directory attribute: hidden file or directory.

*/

const TUint KEntryAttHidden=0x0002;

/**

@publishedAll

@released

File/directory attribute: system file.

*/

const TUint KEntryAttSystem=0x0004;

/**

@publishedAll

@released

File/directory attribute: volume name directory.

*/

const TUint KEntryAttVolume=0x0008;

/**

@publishedAll

@released

File/directory attribute: a directory without the hidden or system attribute.

*/

const TUint KEntryAttDir=0x0010;

/**

@publishedAll

@released

File/directory attribute: an archive file.

*/

const TUint KEntryAttArchive=0x0020;

/**

@publishedAll

@released

File/directory attribute: ROM eXecute In Place file

*/

const TUint KEntryAttXIP=0x0080;

/**

@publishedAll

@released

This file attribute bit is set if the file exists only on a remote file 

system and is not locally cached.

Due to the potential high-latency of remote file systems, applications 

(or users of applications) may make use of this bit to modify their 

behaviour when working with remote files.

This is a read-only attribute, so any attempt to set this attribute will

will be ignored.

*/

const TUint KEntryAttRemote=0x0100;

/**

@publishedAll

@released

The range of entry attributes reserved for file-system specific meanings.

File systems may assign meaning to these bits, but their definition will

not be supported nor maintained by Symbian.

All other file attribute bits are reserved for use by Symbian.

The following table summarises the assignment of attribute bits:

	 0 - KEntryAttReadOnly

	 1 - KEntryAttHidden

	 2 - KEntryAttSystem

	 3 - KEntryAttVolume

	 4 - KEntryAttDir

	 6 - KEntryAttArchive

	 7 - KEntryAttXIP

	 8 - KEntryAttRemote

	 9 - Reserved

	10 - Reserved

	11 - Reserved

	12 - Reserved

	13 - Reserved

	14 - Reserved

	15 - Reserved

	16 - File System Specific

	17 - File System Specific

	18 - File System Specific

	19 - File System Specific

	20 - File System Specific

	22 - File System Specific

	22 - File System Specific

	23 - File System Specific

	24 - KEntryAttPacked

	25 - Reserved

	26 - Reserved

	27 - KEntryAttMatchExclude

	28 - KEntryAttAllowUid

	29 - Reserved

	30 - KEntryAttMatchExclusive

	31 - Reserved

*/

const TUint KEntryAttMaskFileSystemSpecific=0x00FF0000;

/**

@publishedAll

@released

Bit mask for matching file and directory entries.

This mask ensures that directories and hidden and

system files are matched.

(Note that KEntryAttNormal matches all entry types except directories, hidden

and system entries).

@see RFs::GetDir

*/

const TUint KEntryAttMatchMask=(KEntryAttHidden|KEntryAttSystem|KEntryAttDir);

/**

@publishedAll

@released

Bit mask for matching file and directory entries.

This is used when all entry types, including hidden and system files,

but excluding the volume entry are to be matched.

@see RFs::GetDir

*/

const TUint KEntryAttMaskSupported=0x3f;

/**

@publishedAll

@released

Bit mask for matching file and directory entries.

This is used for exclusive matching. When OR'ed with one or more file attribute

constants, for example, KEntryAttNormal, it ensures that only the files with

those attributes are matched.

When OR’ed with KEntryAttDir, directories only (not hidden or system) are matched.

@see KEntryAttDir

@see KEntryAttNormal

@see RFs::GetDir

*/

const TUint KEntryAttMatchExclusive=0x40000000;

/**

@publishedAll

@released

Bit mask for feature manager file entries.

It is used in order to identify each ROM feature set data file 

uniquely in the mount order of ROM sections.

*/

const TUint KEntryAttUnique=0x01000000;

/**

@publishedAll

@released

Bit mask for matching file and directory entries.

It is used to exclude files or directories with certain attributes from

directory listings. This bitmask has the opposite effect

to KEntryAttMatchExclusive. For example:

@code

KEntryAttMatchExclude|KEntryAttReadOnly

@endcode

excludes all read only entries from the directory listing.

@code

KEntryAttMatchExclusive|KEntryAttReadOnly

@endcode

lists only read only entries.

@see KEntryAttMatchExclusive

@see RFs::GetDir

*/

const TUint KEntryAttMatchExclude=0x08000000;

/**

@publishedAll

@released

Bit mask for matching file and directory entries.

Bit mask flag used when UID information should be included in the directory

entry listing.

@see RFs::GetDir

*/

const TUint KEntryAttAllowUid=0x10000000;

/**

@publishedAll

@released

Indicates that a TEntry (that is generally returned from a TEntryArray) is

stored in packed format where the iSizeHigh and iReserved fields follow the

valid characters of the name string.  Before accessing the aforementioned

members, the entry must be unpacked.

*/

const TUint KEntryAttPacked = 0x01000000;

/**

@publishedAll

@released

*/

const TUint KMaxMapsPerCall = 0x8;

enum TNotifyType

/**

@publishedAll

@released

A set of change notification flags.

These flags indicate the kind of change that should result in notification.

This is useful for programs that maintain displays of file lists that

must be dynamically updated.

@see RFs::NotifyChange

@see RFs

@see RFile

@see RRawDisk

*/

	{

	/**

	Any change, including mounting and unmounting drives.

	*/

	ENotifyAll=0x01,

	/**

	Addition or deletion of a directory entry, or changing or formatting a disk.

	*/

	ENotifyEntry=0x02,

	/**

	Change resulting from file requests:

	RFile::Create(), RFile::Replace(), RFile::Rename(), RFs::Delete(),

	RFs::Replace(), and RFs::Rename().

	*/

	ENotifyFile=0x04,

	/**

	Change resulting from directory requests:

	RFs::MkDir(), RFs::RmDir(), and RFs::Rename().

	*/

	ENotifyDir=0x08,

	/**

	Change resulting from: RFs::SetEntry(), RFile::Set(), RFile::SetAtt(),

	RFile::SetModified() and RFile::SetSize() requests.

	*/

	ENotifyAttributes=0x10,

	/**

	Change resulting from the RFile::Write() request.

	*/

	ENotifyWrite=0x20,

	/**

	Change resulting from the RRawDisk::Write() request.

	*/

	ENotifyDisk=0x40

	};

/**

    @publishedAll

    @released

    Notification modes for safe media removal notification API

    @see RFs::NotifyDismount

*/

enum TNotifyDismountMode

	{

	/** Used by a client to register for notification of pending dismount. This is the default behaviour for RFs::NotifyDismount*/

	EFsDismountRegisterClient=0x01,

	/** 

    Used for graceful file system dismounting with notifying clients of a pending dismount. 

    If all clients have responded by RFs::AllowDismount(), the file system will be dismounted. 

    */

	EFsDismountNotifyClients=0x02,

	/**  Used to forcibly dismount the file system without notifying clients. */

	EFsDismountForceDismount=0x03,

	};

enum TFileCacheFlags

/**

@publishedAll

@released

Flags used to enable file server drive-specific caching 

*/

	{

	/**

	Enable read caching - if file explicitly opened in EFileReadBuffered mode

	*/

	EFileCacheReadEnabled = 0x01,

	/**

	Enable read caching for all files, regardless of file open mode

	*/

	EFileCacheReadOn = 0x02,

	/**

	Enable read-ahead caching - if file explicitly opened in EFileReadAheadOn mode

	*/

	EFileCacheReadAheadEnabled = 0x04,	

	/**

	Enable read-ahead caching, regardless of file open mode

	*/

	EFileCacheReadAheadOn = 0x08,	

	/**

	Enable write caching, if file explicitly opened in EFileWriteBuffered mode

	*/

	EFileCacheWriteEnabled = 0x10,	

	/**

	Enable write caching for all files, regardless of file open mode

	*/

	EFileCacheWriteOn = 0x20,	

	};

/**

@publishedAll

@released

Commands to query specific volume information.

@see TVolumeIOParamInfo

*/

enum TQueryVolumeInfoExtCmd

	{

	/**

    Queries the sub type of the file system mounted on a specified volume.

    For example, FAT12, FAT16 or FAT32.

    */

    EFileSystemSubType,

    /**

    Queries the I/O parameters of a specificed volume.

    This includes the block size, the cluster size and the recommended read and write sizes for the media.    

    */

    EIOParamInfo,

    /** 

    This command determines whether the volume is synchronous or asynchronous.

    A boolean value is returned within the buffer defined as TPckgBuf<TBool>. 

    ETrue for Synchronous and EFalse for Asynchronous.

    */

    EIsDriveSync,

    /**

    Query if the given drive is finalised. See RFs::FinaliseDrive() 

    Not all file systems may support this query.

    A boolean value is returned within the buffer defined as TPckgBuf<TBool>. 

    ETrue value means that the drive is finalised

    */

    EIsDriveFinalised,

	};

/**

@publishedAll

@released

Volume IO parameter information.

This class is used to return IO parameter information for a specified volume.

The volume parameter information holds recommended buffer sizes for the creation of efficient buffers for

reading and writing.

@see RFs::VolumeIOParam()

*/

class TVolumeIOParamInfo

	{

public:

	/**

	The size of a block in bytes.

	Reads and writes that are aligned on block boundaries are up to twice as fast as when 

	mis-aligned.	

	Read and write operations on certain underlying media is done in blocks.

	A write operation that modifies only part of a block is less efficient, in general, than

	one that modifies an entire block. Data throughput degrades linearly for reads and writes in smaller

	sized units. 

	*/

	TInt iBlockSize;

	/**

	The size in bytes of a single disk cluster.

	Read and write operations that are aligned on cluster boundaries are more efficient.

	The file system organises and allocates the file data on the disk in clusters where each cluster is

	one or more blocks. Files that are not zero length occupy at least one cluster of the disk, 

	so large numbers of very small files use up more disk space than expected. 

	*/

	TInt iClusterSize;

	/**

	The recommended buffer size for optimised reading performance. 

	The given buffer size is based on sensible benchmark testing results produced by the mobile device vendor.

	The buffer size is then added to the estart.txt file

	The figure is included in the estart.txt file along with the drive number and the variable name. 

	The example below shows the required format:

	[DriveC]

	RecReadBufSize 8192

	When no value is provided, value KErrNotSupported is returned.

	*/

	TInt iRecReadBufSize;

	/**

	The recommended buffer size for optimised writing performance. 

	The given buffer size is based on sensible benchmark testing results produced by the mobile device vendor.

	The buffer size is then added to the estart.txt file

	The figure is included in the estart.txt file along with the drive number and the variable name. 

	The example below shows the required format:

	[DriveC]

	RecWriteBufSize 16384

	When no value is provided, value KErrNotSupported is returned.

	*/

	TInt iRecWriteBufSize;

    /** 

    The maximum file size that is supported by the file system mounted on this volume. 

    Not all file system may provide this parameter;  The value KMaxTUint64 (0xffffffffffffffff) means that this particular file system hasn't 

    provided this information.

    */

    TUint64 iMaxSupportedFileSize;

private:

	/*

	Reserved space for future use

	*/

	TInt iReserved[2];

	};

enum TDriveNumber

/**

@publishedAll

@released

The drive number enumeration.

*/

	{

	EDriveA,   EDriveB,   EDriveC,   EDriveD,   EDriveE,

	EDriveF,   EDriveG,   EDriveH,   EDriveI,   EDriveJ,

	EDriveK,   EDriveL,   EDriveM,   EDriveN,   EDriveO, 

	EDriveP,   EDriveQ,   EDriveR,   EDriveS,   EDriveT,

	EDriveU,   EDriveV,   EDriveW,   EDriveX,   EDriveY,

	EDriveZ

	};

enum TEntryKey

/**

@publishedAll

@released

Flags indicating the order in which directory entries are to be sorted.

@see RFs::GetDir

@see CDirScan::SetScanDataL

@see CDir::Sort

*/

	{

	/**

	The default; no sorting takes place

	*/

	ESortNone=0,

	/**

	Sort according to alphabetic order of file and directory name.

    This setting is mutually exclusive with ESortByExt, ESortBySize,

    ESortByDate and ESortByUid.

	*/

	ESortByName,

	/**

	Sort according to alphabetic order of file extension.

	Files without an extension take precedence over files with an extension.

	For files with the same extension or without an extension, the default is

	to sort by name.

    This setting is mutually exclusive with ESortByName, ESortBySize,

    ESortByDate and ESortByUid.

	*/

	ESortByExt,

	/**

	Sort according to file size.

    This setting is mutually exclusive with ESortByName, ESortByExt,

    ESortByDate and ESortByUid.

	*/

	ESortBySize,

	/**

	Sort according to files' last modified time and date.

	By default, most recent last.

    This setting is mutually exclusive with ESortByName, ESortByExt,

    ESortBySize and ESortByUid.

	*/

	ESortByDate,

	/**

	Sort according to file UID.

    This setting is mutually exclusive with ESortByName, ESortByExt,

    ESortBySize and ESortByDate.

	*/

	ESortByUid,

	/**

	Qualifies the sort order; if set, directories are listed in the order in

	which they occur. 

	This is the default.

    This flag is mutually exclusive with EDirsFirst and EDirslast.

	*/

	EDirsAnyOrder=0,

	/**

	Qualifies the sort order; if set, directories come before files in sort order.

    This flag is mutually exclusive with EDirsAnyOrder and EDirsLast.

	*/

	EDirsFirst=0x100,

	/**

	Qualifies the sort order; if set, files come before directories in sort order.

    This flag is mutually exclusive with EDirsAnyOrder and EDirsFirst.

	*/

	EDirsLast=0x200,

	/**

	Qualifies the sort order; files are sorted in ascending order, i.e. from A to Z.

	This is the default behaviour.

    This flag is mutually exclusive with EDescending and EDirDescending.

	*/

	EAscending=0,

	/**

	Qualifies the sort order; files are sorted in descending order, i.e. from Z to A.

    This flag is mutually exclusive with EAscending and EDirDescending.

	*/

	EDescending=0x400,

	/**

	Qualifies the sort order; directories are sorted in descending order, i.e. from Z to A.

    This flag shall be used in combination with either EDirsFirst or EDirsLast.

    This flag is mutually exclusive with EAscending and EDescending.

	*/

	EDirDescending=0x800

	};

enum TFileMode

/**

@publishedAll

@released

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:

@code

_LIT(KFilename, "filename.ext");

RFile file;

file.Open(theFs, KFilename, EFileShareAny|EFileWrite);

@endcode

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.

@code

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

@endcode

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