Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]

#include <f32file.h>
Link against: efsrv.lib

Class RFs

class RFs : public RSessionBase;

Description

A handle to a file server session.

A program or thread may have arbitrarily many sessions open simultaneously.

Use this class for all file system manipulation, including:

1. adding, removing, moving and renaming files and directories

2. inspecting and changing file attributes and directory entry details. These include the time and date when the file or directory was last written to, its size and various attribute flags such as read-only, hidden, archive or system.

3. finding a file’s real name; if the file system on which it is stored has to "mangle" the name into a shorter format

4. getting directory listings

5. maintaining a default path; unlike some other systems, there is a single system default path, rather than one for each drive: the default path consists of a drive and a path specification.

6. performing context-sensitive parses using TParse objects, and the session path

7. obtaining information on drives and volumes

8. formatting and labelling volumes

9. obtaining a list of valid drives

10. emulating the DOS subst command, which allows any directory to appear as if it were a separate drive

11. requesting notification of when significant change occurs. This can be used for programs which maintain file lists, but must update those lists when change occurs.

12. finding the version number of the file server

13. resource counting to ensure that all resources are closed when the session terminates.

This class is not intended for user derivation.

The following restrictions apply when a path is specified:

1. its total length must not exceed 256 characters

2. wildcards cannot be used in the drive or in any directory name, although they may be allowed in the filename and extension.

3. double backslashes are not allowed in the path.

4. the following characters must not be included anywhere in the path: < > " / |

5. a colon may only be included between the drive and path

6. no directory name or filename plus extension may consist solely of space characters, or of a single or double dot.

7. spaces between the drive, if specified, and the first directory in the path are illegal, although there may be spaces between other path components, for instance between directories.

Derivation

Members

Defined in RFs:

Inherited from RHandleBase:

Inherited from RSessionBase:

Related Topics


Member functions


Connect()

IMPORT_C TInt Connect(TInt aMessageSlots=KFileServerDefaultMessageSlots);

Description

Connects a client to the file server.

To end the file server session, use Close().

Parameters

TInt aMessageSlots

The number of message slots required. The default value of KFileServerDefaultMessageSlots indicates that message slots will be acquired dynamically from the system wide pool. Override this value with a fixed number, if a fixed number of slots are to be allocated to the session. If overriding, note that the number of message slots represents the number of operations, such as reads and writes, that can be outstanding at once; always remember to provide a spare slot for the cancel operation.

Return value

TInt

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


Version()

IMPORT_C TVersion Version() const;

Description

Gets the client side version number.

Return value

TVersion

The client side version number.


AddFileSystem()

Capability: DiskAdmin

IMPORT_C TInt AddFileSystem(const TDesC &aFileName) const;

Description

Adds a file system to the file server.

After calling this function, use MountFileSystem() to mount the file system on a drive.

Parameters

const TDesC &aFileName

The name of the file system .FSY to install. Its full path can be specified.

Return value

TInt

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


MountFileSystem()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, TInt aDrive) const;

Description

Mounts a file system on a drive.

The file system must first have been added to the file server using AddFileSystem(). The drive is mounted as asynchronous, i.e operations on it don't block the file server and other drives;

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

TInt aDrive

The drive on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

Return value

TInt

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


MountFileSystem()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, TInt aDrive, TBool aIsSync) const;

Description

Mounts a file system on a specified drive.

The file system must first have been added to the file server using AddFileSystem(). Depending on the aIsSync parameter, the drive can be mounted as synchronous or asynchronous.

Asynchronous drive has its own processing thread, i.e operations on it don't block the file server and other drives; Synchronous drives' requests are being processed by the main file server thread and there is a possibility to block it along with all operations on other drives. Mounting a drive as synch. makes a sense if the operations on such drive are very fast e.g. this is an internal RAM or ROFS drive.

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

TInt aDrive

The drive number on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

TBool aIsSync

if ETrue the drive will be mounted as synchronous one; if EFalse the drive will be mounted as Asynchronous.

Return value

TInt

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


MountFileSystemAndScan()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystemAndScan(const TDesC &aFileSystemName, TInt aDrive, TBool &aIsMountSuccess) const;

Description

Mounts a file system on a drive, and performs a scan on that drive. The file system must first have been added to the file server using AddFileSystem().

Note that the scan is done only if the mount is successful.

The drive is mounted as asynchronous, i.e operations on it don't block the file server and other drives;

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

TInt aDrive

The drive on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

TBool &aIsMountSuccess

On return, set to: ETrue, if the if the mount is successful, set to EFalse otherwise.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes, reflecting the failure of the mount operation.


MountFileSystem()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive);

Description

Mounts a file system on a drive, and the specified extension.

The file system must first have been added to the file server using AddFileSystem(). The drive is mounted as asynchronous, i.e operations on it don't block the file server and other drives;

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

const TDesC &aExtensionName

The filename of the extension.

TInt aDrive

The drive on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

Return value

TInt

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


MountFileSystem()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive, TBool aIsSync);

Description

Mounts a file system on a drive, and the specified extension.

The file system must first have been added to the file server using AddFileSystem().

Depending on the aIsSync parameter, the drive can be mounted as synchronous or asynchronous.

Asynchronous drive has its own processing thread, i.e operations on it don't block the file server and other drives; Synchronous drives' requests are being processed by the main file server thread and there is a possibility to block it along with all operations on other drives. Mounting a drive as synch. makes sense if the operations on such drive are very fast e.g. this is an internal RAM or ROFS drive.

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

const TDesC &aExtensionName

The filename of the extension.

TInt aDrive

The drive on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

TBool aIsSync

if ETrue the drive will be mounted as synchronous one; if EFalse the drive will be mounted as Asynchronous.

Return value

TInt

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


MountFileSystemAndScan()

Capability: DiskAdmin

IMPORT_C TInt MountFileSystemAndScan(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive, TBool &aIsMountSuccess) const;

Description

Mounts a file system on a drive, and the specified extension and performs a scan on that drive.

The file system must first have been added to the file server, using AddFileSystem().

Note that the scan is done only if the mount is successful.

The operation is asynchronous, i.e other concurrent file server operations can continue.

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

const TDesC &aExtensionName

The filename of the extension.

TInt aDrive

The drive on which the file system is to be mounted; this can be one of the values defined by TDriveNumber.

TBool &aIsMountSuccess

On return, set to: ETrue, if the if the mount is successful, set to EFalse otherwise.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes, reflecting the failure of the mount operation.


DismountFileSystem()

Capability: DiskAdmin

IMPORT_C TInt DismountFileSystem(const TDesC &aFileSystemName, TInt aDrive) const;

Description

Dismounts the file system from the specified drive.

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName().

TInt aDrive

The drive from which the file system is to be dismounted.

Return value

TInt

KErrNone, if successful; KErrNotFound, if aFileSystemName is not found; KErrNotReady, if the drive does not have a file system mounted on it; KErrInUse, if the drive has a resource open on it; KErrAccessDenied, if there is an attempt to dismount a ROM file system, a substituted drive, or the drive which is the default drive; KErrArgument, if the specified drive value is outsdide of the valid range. KErrPermissionDenied, if the client does not have the necessary capabilities to dismount the file system.


RemoveFileSystem()

Capability: DiskAdmin

IMPORT_C TInt RemoveFileSystem(const TDesC &aFileSystemName) const;

Description

Removes the specified file system.

Parameters

const TDesC &aFileSystemName

The fullname of the file system, as returned from a call to FileSystemName(), to be removed.

Return value

TInt

KErrNone, if successful; KErrNotFound, if aFileSystemName is not found; otrherwise one of the other system-wide error codes.


FileSystemName()

IMPORT_C TInt FileSystemName(TDes &aName, TInt aDrive) const;

Description

Gets the name of the file system mounted on the specified drive.

The function can be called before calling DismountFileSystem().

Parameters

TDes &aName

On successful return, contains the name of the file system.

TInt aDrive

The drive for which the file system name is required.

Return value

TInt

KErrNone, if successful; KErrNotFound if aFileSystemName is not found, or the drive does not have a file system mounted on it; KErrArgument, if the drive value is outside the valid range, i.e. zero to KMaxDrives-1 inclusive.


AddExtension()

IMPORT_C TInt AddExtension(const TDesC &aFileName);

Description

Loads the specified extension.

Parameters

const TDesC &aFileName

The file name of the extension

Return value

TInt

KErrNone, if successful; otherwise one of the other system wide error codes.


MountExtension()

IMPORT_C TInt MountExtension(const TDesC &aExtensionName, TInt aDrive);

Description

Mounts the the specified extension.

The extension must first have been loaded using AddExtension().

Parameters

const TDesC &aExtensionName

The fullname of the extension, as returned from a call to ExtensionName().

TInt aDrive

The drive on which the extension is to be mounted;

Return value

TInt

KErrNone if successful; KErrNotFound, if the extension cannot be found; otherwise one of the other system-wide error codes.


DismountExtension()

IMPORT_C TInt DismountExtension(const TDesC &aExtensionName, TInt aDrive);

Description

Dismounts the specified extension.

Parameters

const TDesC &aExtensionName

The fullname of the extension, as returned from a call to ExtensionName().

TInt aDrive

The drive this extension is to be dismounted from.

Return value

TInt

KErrNone if successful; KErrNotFound if the extension cannot be found; otherwise one of the other system-wide error codes.


RemoveExtension()

IMPORT_C TInt RemoveExtension(const TDesC &aExtensionName);

Description

Removes the specified extension.

Parameters

const TDesC &aExtensionName

The fullname of the extension, as returned from a call to ExtensionName().

Return value

TInt

KErrNone, if successful; KErrNotFound, if aExtensionName is not found; otrherwise one of the other system-wide error codes.


ExtensionName()

IMPORT_C TInt ExtensionName(TDes &aExtensionName, TInt aDrive, TInt aPos);

Description

Gets the name of the extension on the specified drive at the specified position in the extension hierarchy.

Parameters

TDes &aExtensionName

On successful return, contains the name of the extension.

TInt aDrive

The drive for which the extension name is required.

TInt aPos

The position of the extension in the extension hierarchy.

Return value

TInt

KErrNone, if successful; KErrNotFound if the extension name is not found;


RemountDrive()

IMPORT_C TInt RemountDrive(TInt aDrive, const TDesC8 *aMountInfo=0,TUint aFlags=0);

Description

Forces a remount of the specified drive.

Parameters

TInt aDrive

The drive for which a remount is to be forced.

const TDesC8 *aMountInfo

Information passed down to the media driver. The meaning of this information depends on the media driver, for example, keys for secure areas.

TUint aFlags

When the flag is set to 0x00000001 - Used to simulate ejecting and re-inserting the media. 0x80000000 - used to force the media driver for the specified logical drive to be closed and reopened.

Return value

TInt

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


NotifyChange()

IMPORT_C void NotifyChange(TNotifyType aType, TRequestStatus &aStat);

Description

Requests a notification of change to files or directories.

Changes are notified either:

1. following any change in the file system

or

2. only following the addition or deletion of a directory entry, or after a disk has been formatted or changed.

Such notification is useful for programs that maintain displays of file lists which must be dynamically updated. The alternative is to do no updating, or to perform periodic monitoring for change, which is inefficient.

This is an asynchronous request and, as such, results in precisely one signal to the request status passed as a parameter. To avoid missing any change, this request should be issued before the first file list is constructed. When the request completes, a new request should be issued before the next file list is constructed. When the file server session is closed, this request is implicitly cancelled.

Call NotifyChangeCancel() to explicitly cancel a notification request.

Parameters

TNotifyType aType

Indicates the kind of change that should result in notification. For example: ENotifyEntry causes notification only when an entry is added or deleted, or when a disk is formatted or changed; ENotifyAll causes notification following any type of change, such as when a file is written to, or when a file's attributes are changed.

TRequestStatus &aStat

The request status. This is set to KErrNone on completion, otherwise one of the other system-wide error codes.


NotifyChange()

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

IMPORT_C void NotifyChange(TNotifyType aType, TRequestStatus &aStat, const TDesC &aPathName);

Description

Requests a notification of change to files or directories, allowing a directory/file path to be specified.

Changes are notified either:

1. following any change in the file system

or

2. only following the addition or deletion of a directory entry, or after a disk has been formatted or changed.

Such notification is useful for programs that maintain displays of file lists which must be dynamically updated. The alternative is to do no updating, or to perform periodic monitoring for change, which is inefficient.

This is an asynchronous request and, as such, results in precisely one signal to the request status passed as a parameter. To avoid missing any change, this request should be issued before the first file list is constructed. When the request completes, a new request should be issued before the next file list is constructed. When the file server session is closed, this request is implicitly cancelled.

Call NotifyChangeCancel() to explicitly cancel a notification request.

Parameters

TNotifyType aType

Indicates the kind of change that should result in notification. For example: ENotifyEntry causes notification only when an entry is added or deleted, or when a disk is formatted or changed; ENotifyAll causes notification following any type of change, such as when a file is written to, or when a file's attributes are changed.

TRequestStatus &aStat

The request status. This is set to KErrNone on completion, otherwise one of the other system-wide error codes.

const TDesC &aPathName

The directory or file for which notification is required. By specifying a drive as a wildcard, for example "?:\\Resource\\apps\\", or "*:\\Resource\\apps\\", a client can ask to be notified of changes to a given directory on any drive. As with all directory paths aPathName must be terminated with '\', Please refer to "Structure of paths and filenames" section in the Symbian OS Library.


NotifyChangeCancel()

IMPORT_C void NotifyChangeCancel();

Description

Cancels all outstanding requests for notification of change to files or directories.

All outstanding requests complete with KErrCancel.

Note that this is a synchronous function.


NotifyChangeCancel()

IMPORT_C void NotifyChangeCancel(TRequestStatus &aStat);

Description

Cancels the specific request for notification of change to files or directories.

The outstanding request completes with KErrCancel.

Note that this is an asynchronous function.

Parameters

TRequestStatus &aStat

The request status object associated with the request to be cancelled. Note that the function does not change this parameter.


NotifyDiskSpace()

IMPORT_C void NotifyDiskSpace(TInt64 aThreshold, TInt aDrive, TRequestStatus &aStat);

Description

Requests notification when the free disk space on the specified drive crosses the specified threshold value.

The threshold is crossed if free disk space increases to a value above the threshold value or decreases to a value below the threshold value.

This is an asynchronous request that completes if any of the following events occur:

1. the threshold is crossed

2. any drive is formatted

3. there is a media change on any socket

4. power up

5. the scandrive utility is run on any drive

5. the specified threshold value is outside its limits

7. the outstanding request is cancelled.

Note that free disk space notification is not supported for drives using remote file systems.

Parameters

TInt64 aThreshold

The threshold value. This must be greater than zero and less than the total size of the disk.

TInt aDrive

The drive number. This is an explicit drive defined by one of the TDriveNumber enum values or the value KDefaultDrive. If KDefaultDrive is specified, then the drive monitored is the session path drive.

TRequestStatus &aStat

The request status object. On request completion, contains: KErrNone, if the threshold value is crossed, if any drive is formatted, if there is a media change on any socket, if there is a power up or if the scandrive utility is run on any drive; KErrCancel, if the outstanding request is cancelled by a call to NotifyDiskSpaceCancel(); KErrArgument, if the threshold value is outside its limits.

See also:


NotifyDiskSpaceCancel()

IMPORT_C void NotifyDiskSpaceCancel(TRequestStatus &aStat);

Description

Cancels a specific outstanding request for free disk space notification.

The outstanding request completes with KErrCancel.

Parameters

TRequestStatus &aStat

The request status object identified with the original notification request.


NotifyDiskSpaceCancel()

IMPORT_C void NotifyDiskSpaceCancel();

Description

Cancels all outstanding requests for free disk space notification.

Outstanding requests complete with KErrCancel.


DriveList()

IMPORT_C TInt DriveList(TDriveList &aList) const;

Description

Gets a list of the available (not remote and non hidden) drives.

The drive list consists of an array of 26 bytes. Array index zero corresponds to drive A, index one equals B etc.

Each byte with a non zero value signifies that the corresponding drive is available to the system. In the case of removable media, RFs::Drive should be used to determine wether the media is inserted or not.

The local file system always reserves drive letters A through I. Drive letter Z is always used for the ROM which means that letters J through Y are available to be used by SetSubst() or for redirecting.

Parameters

TDriveList &aList

On return, contains a list of drive attributes (only the first 8 bits) for the available non-remote and non-hidden drives.

Return value

TInt

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


DriveList()

IMPORT_C TInt DriveList(TDriveList &aList, TUint aFlags) const;

Description

Gets a list of the available drives that match a combination of drive attributes,specified in aFlags. This combination may include,exclude or exclusively specify the attributes that that drives to be returned should match.

The drive list consists of an array of 26 bytes. Array index zero corresponds to drive A, index one equals B etc.

Each byte with a non zero value signifies that the corresponding drive is available to the system. In the case of removable media, RFs::Drive should be used to determine wether the media is inserted or not.

The local file system always reserves drive letters A through I. Drive letter Z is always used for the ROM which means that letters J through Y are available to be used by SetSubst() or for redirecting.

Parameters

TDriveList &aList

On return, contains a list of available drives that qualify aFlags.

TUint aFlags

A combination of drive attributes that drives to be returned must qualify.

Return value

TInt

KErrNone, successful, otherwise one of the other system-wide error codes; KErrArgument, If aFlags contains an invalid attribute combination.


Drive()

IMPORT_C TInt Drive(TDriveInfo &anInfo, TInt aDrive=KDefaultDrive) const;

Description

Gets information about a drive and the medium mounted on it.

Note that Volume() can also be used to give information about the drive and the volume mounted on it. These two functions are separate because, while the characteristics of a drive cannot change, those of a volume can, by mounting different media, reformatting etc.

Parameters

TDriveInfo &anInfo

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

TInt aDrive

The drive for which information is requested. Specify KDefaultDrive for the session default drive. Specify a drive in the range EDriveA to EDriveZ for drives A to Z respectively.

Return value

TInt

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


Volume()

IMPORT_C TInt Volume(TVolumeInfo &aVol, TInt aDrive=KDefaultDrive) const;

Description

Gets volume information for a formatted device.

This function provides additional information to that given by Drive(), including the volume label, if set, and the amount of free space on the disk.

Note, use Drive() to get information about the drive without reference to a volume. These two functions are separate because, while the characteristics of a drive cannot change, those of a volume can, by mounting different media, reformatting etc. A volume may not even be present if the media is removable.

Parameters

TVolumeInfo &aVol

On return, contains the volume information.

TInt aDrive

The drive which contains the media for which volume information is to be displayed. Specify a drive in the range EDriveA to EDriveZ for drives A to Z respectively. The default drive is the session default drive KDefaultDrive.

Return value

TInt

KErrNone, if successful; KErrNotReady, if the drive contains no media; otherwise one of the other system-wide error codes.


SetVolumeLabel()

Capability: DiskAdmin

IMPORT_C TInt SetVolumeLabel(const TDesC &aName, TInt aDrive=KDefaultDrive);

Description

Sets the label for a volume.

Parameters

const TDesC &aName

The volume label.

TInt aDrive

The drive containing the media whose label is to be set. Specify a drive in the range EDriveA to EDriveZ for drives A to Z. The default drive is the session default drive KDefaultDrive.

Return value

TInt

KErrNone, if successful; KErrNotReady, if the drive contains no media; otherwise one of the other system-wide error codes.

See also:


Subst()

IMPORT_C TInt Subst(TDes &aPath, TInt aDrive=KDefaultDrive) const;

Description

Gets the path assigned to a drive letter by an earlier call to SetSubst().

To find out whether a drive letter has been substituted, first get the drive information, using Drive(), and then test the value of the KDriveAttSubsted bit provided by TDriveInfo::iDriveAtt.

Parameters

TDes &aPath

On return, contains the path which has been assigned to the drive. If the drive letter has not been substituted, this argument returns an empty descriptor.

TInt aDrive

The drive which is the subject of the enquiry. Specify a number in the range 0 (EDriveA) to 25 (>EDriveZ) for drives A to Z. The default drive is the session default drive KDefaultDrive.

Return value

TInt

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

See also:


SetSubst()

Capability: Dependent If aPath is /Sys then Tcb capability is required. If aPath begins with /Private and does not match this process' SID then AllFiles capability is required. If aPath is /Resource then Tcb capability is required.
Capability: DiskAdmin

IMPORT_C TInt SetSubst(const TDesC &aPath, TInt aDrive=KDefaultDrive);

Description

Assigns a path to a drive letter.

Whenever that drive letter is used, it will be translated into a reference to the path specified here. To clear a drive substitution, specify an empty descriptor for aPath.

Note that the substituted path is text-only. Its components need not be syntactically correct, nor must they be valid at the time the substitution is set. Any component may be deleted, removed or unmounted while the substitution is set.

Parameters

const TDesC &aPath

The path to be assigned to the drive letter. If a drive letter is specified in the path, it must not itself be substituted or redirected, or the function will return an error. If no drive is specified, the drive contained in the default session path is used, and if no path is specified, the default session path is used. If a filename or extension is included in the path, the function will return an error. Therefore, the final component in the path must have a trailing backslash to indicate that it is a directory.

TInt aDrive

The drive to which a path is to be assigned. Specify a number in the range 0 (EDriveA) to 25 (EDriveZ) for drives A to Z. Must not be local, ROM, or redirected, otherwise an error is returned. May be substituted, but only if the function is being used to clear the substitution. If the same drive is specified in the path, the function will return an error. The default drive is the session default drive KDefaultDrive.

Return value

TInt

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


RealName()

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

IMPORT_C TInt RealName(const TDesC &aName, TDes &aResult) const;

Description

Gets the real name of a file.

This is used in circumstances where a file system needs to mangle Symbian OS natural names so that it can store them on that file system.

Parameters

const TDesC &aName

Contains the name by which the file is normally referred.

TDes &aResult

On return, contains the real name of the file, comprising the full path, including the drive letter.

Return value

TInt

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


GetMediaSerialNumber()

IMPORT_C TInt GetMediaSerialNumber(TMediaSerialNumber &aSerialNum, TInt aDrive);

Description

Gets the serial number of media.

Only local drive is allowed. Substed drive number will return KErrNotSupported.

Parameters

TMediaSerialNumber &aSerialNum

Contains serial number on successful return.

TInt aDrive

Drive number.

Return value

TInt

KErrNone if successful; KErrNotSupported if media doesn't support serial number (e.g. substed drives); KErrBadName if drive number is invalid; otherwise one of system-wide error codes.


SessionPath()

IMPORT_C TInt SessionPath(TDes &aPath) const;

Description

Gets the session path.

When a client connects to the file server, its session path is initialised to the system default path. The session path of an existing client can only be changed by this function.

Parameters

TDes &aPath

On return, contains the session path, including a trailing backslash.

Return value

TInt

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


SetSessionPath()

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

IMPORT_C TInt SetSessionPath(const TDesC &aPath);

Description

Sets the session path for the current file server client.

When the client first connects to the file server, its session path is initialised to the system default path.

Note that the session path is text-only. It does not cause any locking. Thus, although the path must be syntactically correct, its components do not need to be valid at the time the path is set, and any component may be deleted, removed or unmounted while the path is set.

Parameters

const TDesC &aPath

The new session path. Consists of a drive and path. Normally, a drive should be specified, but if not, the drive specified in the existing session path is preserved. If a file is specified, then the function fails and returns an error code. Therefore, the final component in the path must have a trailing backslash to indicate that it is a directory. All components of the path must be syntactically correct, for example, wildcard characters and double backslashes are not allowed in any part of it.

Return value

TInt

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


Parse()

IMPORT_C TInt Parse(const TDesC &aName, TParse &aParse) const;

Description

Parses a filename specification.

Parsing is done with wildcard resolution, using the session path as the default. You can then use TParse's getter functions to extract individual components of the resulting name. All the path components that are included in aName are put into the resulting filename. Any components that are still missing are taken from the session path.

Specifying:

TParse fp;
fs.Parse(name,fp);

is equivalent to

TParse fp;
fp.Set(name,NULL,&fs.SessionPath());

Note that the function does not check for illegal characters, or for illegal path components in either of the paths specified.

Parameters

const TDesC &aName

The file name to be parsed, using the session path to provide the missing components.

TParse &aParse

A TParse objct that provides functions for extracting individual components of the resulting file name.

Return value

TInt

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


Parse()

IMPORT_C TInt Parse(const TDesC &aName, const TDesC &aRelated, TParse &aParse) const;

Description

Parses a filename specification, specifying related file path components.

Parsing is done with wildcard resolution, using the session path as the default. You can then use TParse's getter functions to extract individual components of the resulting name. All the path components that are included in aName are put into the resulting filename. Any missing components are taken from the optional aRelated argument, which has the next order of precedence. Finally, any components that are still missing are taken from the session path.

Specifying:

TParse fp;
fs.Parse(name,related,fp);

is equivalent to

TParse fp;
fp.Set(name,related,&fs.SessionPath());

Note that the function does not check for illegal characters, or for illegal path components in any of the paths specified.

Parameters

const TDesC &aName

The file name to be parsed, using the session path and the related path to provide the missing components.

const TDesC &aRelated

The related file specification.

TParse &aParse

A TParse objct that provides functions for extracting individual components of the resulting file name.

Return value

TInt

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


MkDir()

Capability: Dependent If aPath is /Sys then Tcb capability is required. If aPath begins with /Private and does not match this process' SID then AllFiles capability is required. If aPath is /Resource then Tcb capability is required.

IMPORT_C TInt MkDir(const TDesC &aPath);

Description

Makes a directory.

It should be a sub-directory of an existing directory and its name should be unique within its parent directory, otherwise the function returns error code KErrAlreadyExists.

Note that if a filename is specified in the argument, it is ignored. Therefore, there should be a trailing backslash after the final directory name in the argument to indicate that it is a directory, not a filename.

For example, following code will create directory "C:\\DIR1\\"

fs.MkDir(_L("C:\\DIR1\\"));

The last line in the following example will result in KErrAlreadyExists because "DIR2" doesn't have a trailing backslash, therefore is considered as a file name and discarded. Directory "C:\\DIR1\\" has already been created.

fs.MkDir(_L("C:\\DIR1\\"));     // shall create DIR1 in the root directory
fs.MkDir(_L("C:\\DIR1\\DIR2")); // No trailing backslash, fails with KErrAlreadyExists

This example will always fail because "DIR1" doesn't have a trailing backslash and discarded while the root directory always exists.

fs.MkDir(_L("C:\\DIR1"));  // No trailing backslash, will always fail with KErrAlreadyExists

Note also that because this method can return an error code (eg. because the disk is full) before checking whether the path already exists, it is not appropriate to use it just to work out whether a path exists or not.

See MkDirAll(), which may also create intermediate directories.

Parameters

const TDesC &aPath

The name of the new directory. Any path components which are not specified here will be taken from the session path.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes. Even if another error code is returned, (for example, if the disk is full) it is still possible that the path may already exist.


MkDirAll()

Capability: Dependent If aPath is /Sys then Tcb capability is required. If aPath begins with /Private and does not match this process' SID then AllFiles capability is required. If aPath is /Resource then Tcb capability is required.

IMPORT_C TInt MkDirAll(const TDesC &aPath);

Description

Makes one or more directories.

Any valid path component specified in aPath which does not already exist is created as a directory.

Note that if a filename is specified in the argument, it is ignored. Therefore, there should be a trailing backslash after the final directory name in the argument to indicate that it is a directory, not a filename.

See also notes on RFs::MkDir() about trailing backslashes in directory names.

Note also that because this method can return an error code (eg. because the disk is full) before checking whether the path already exists, it is not appropriate to use it just to work out whether a path exists or not.

See MkDir(), which creates only a single new directory.

Parameters

const TDesC &aPath

The path name specifiying the directory or directories to create. If the function completes successfully, this path identifies a valid directory. Any path components which are not specified here are taken from the session path.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes. Even if another error code is returned, (for example, if the disk is full) it is still possible that the path may already exist.


RmDir()

Capability: Dependent If aPath is /Sys then Tcb capability is required. If aPath begins with /Private and does not match this process' SID then AllFiles capability is required. If aPath is /Resource then Tcb capability is required.

IMPORT_C TInt RmDir(const TDesC &aPath);

Description

Removes a directory.

The directory must be empty and cannot be the root directory.

Note that if a filename is specified in the argument, it is ignored.

For example, following code will result in directory "C:\\SRC\\" being removed as long as it is empty, the existance of "ENTRY" will not be checked:

fs.RmDir(_L("C:\\SRC\\ENTRY"));

Similarly, following code will try to remove "C:\\SRC\\" instead of "C:\\SRC\DIR\\":

fs.RmDir(_L("C:\\SRC\\DIR"));

Therefore, there should be a trailing backslash after the final directory name in the argument to indicate that it is a directory, not a filename.

See class CFileMan for information on deleting a non-empty directory and all of its contents.

Parameters

const TDesC &aPath

The path name of the directory to be removed. Any path components which are not specified here are taken from the session path. Only the lowest-level directory identified is removed.

Return value

TInt

KErrNone, if successful; KErrInUse, if trying to remove a non-empty directory or root directory; otherwise, one of the other system-wide error codes.

See also:


GetDir()

IMPORT_C TInt GetDir(const TDesC &aName, TUint anEntryAttMask, TUint anEntrySortKey, CDir *&anEntryList) const;

Description

Gets a filtered list of a directory's contents.

The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.

Notes:

1. If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in anAttMask.

2. The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.

3. The caller of this function is responsible for deleting aFileList after the function has returned.

Parameters

const TDesC &aName

The name of the directory for which a listing is required. Wildcards may be used to specify particular files.

TUint anEntryAttMask

Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in the listing. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.

TUint anEntrySortKey

The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.

CDir *&anEntryList

On return contains a filtered list of directory and file entries.

Return value

TInt

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

See also:


GetDir()

IMPORT_C TInt GetDir(const TDesC &aName, TUint anEntryAttMask, TUint anEntrySortKey, CDir *&anEntryList, CDir *&aDirList) const;

Description

Gets a filtered list of the directory and file entries contained in a directory, and a list of the directory entries only.

The bitmask determines which file and directory entry types should be listed in aFileList. The contents of the second list, aDirList are not affected by the bitmask; it returns all directory entries contained in directory aName. The sort key determines the order in which both lists are sorted.

Notes:

1. If sorting by UID (as indicated when the ESortByUid bit is OR'ed with the sort key), then UID information will be included in the listing whether or not KEntryAttAllowUid is specified in anAttMask.

2. The function sets both aFileList and aDirList to NULL, and then allocates memory to them before appending entries to the lists. Therefore, aFileList and aDirList should have no memory allocated to them before this function is called, otherwise the allocated memory will become orphaned.

3. The caller of this function is responsible for deleting aFileList and aDirList after the function has returned.

Parameters

const TDesC &aName

The name of the directory for which a listing is required. Wildcards may be used to specify particular files.

TUint anEntryAttMask

Bitmask indicating the attributes of interest. Only files and directories whose attributes match those specified here can be included in aFileList. aDirList is unaffected by this mask. For more information, see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.

TUint anEntrySortKey

The sort key. This is a set of flags indicating the order in which the entries in both lists are to be sorted. These flags are defined by TEntryKey.

CDir *&anEntryList

On return contains a filtered list of directory and file entries.

CDir *&aDirList

On return contains a filtered list of directory entries only.

Return value

TInt

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

See also:


GetDir()

IMPORT_C TInt GetDir(const TDesC &aName, const TUidType &anEntryUid, TUint anEntrySortKey, CDir *&aFileList) const;

Description

Gets a filtered list of a directory's contents by UID type.

The aUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.

Notes:

1. The function sets aFileList to NULL, and then allocates memory for it before appending entries to the list. Therefore, aFileList should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.

2. The caller of this function is responsible for deleting aFileList after the function has returned.

Parameters

const TDesC &aName

The name of the directory for which a listing is required. Wildcards may be used to specify particular files.

const TUidType &anEntryUid

Only those files whose UIDs match those specified within this UID type will be included in the file list. Any, or all, of the three UIDs within the UID type may be omitted. Any UID which is omitted acts in a similar manner to a wildcard character, matching to all UIDs.

TUint anEntrySortKey

The sort key. This is a set of flags indicating the order in which the entries are to be sorted. These flags are defined by TEntryKey.

CDir *&aFileList

On return contains a filtered list of directory and file entries.

Return value

TInt

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

See also:


Delete()

Capability: Dependent If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required.

IMPORT_C TInt Delete(const TDesC &aName);

Description

Deletes a single file.

Wildcards are not allowed in either the file name or the extension, otherwise an error is returned.

Note that the file must be closed and must not be read-only. Hidden files can be deleted but system files cannot.

See class CFileMan for information on deleting multiple files.

Parameters

const TDesC &aName

The name of the file to be deleted. Any path components which are not specified here will be taken from the session path.

Return value

TInt

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

See also:


Rename()

Capability: Dependent If either anOldName or aNewName is /Sys then Tcb capability is required. If either anOldName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required. If either anOldName or aNewName is /Resource then Tcb capability is required.

IMPORT_C TInt Rename(const TDesC &anOldName, const TDesC &aNewName);

Description

Renames a single file or directory.

It can also be used to move a file or directory by specifying different destination and source directories. If so, the destination and source directories must be on the same drive. If a directory is moved, then the directory structure beneath it is also moved.

If a directory specified by aNewName is different from one specified by anOldName, then the file or directory is moved to the new directory. The file or directory cannot 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 SetSubst().

The function fails and returns an error code in the following circumstances:

1. If either the old or new name includes wildcards.

2. If a file or directory with the new name already exists in the target directory. Overwriting is not permitted.

3. If file anOldName does not exist, or is open.

Read-only, system and hidden files may be renamed. The renamed file's attributes are preserved.

Note that when this function is operating on directories, a trailing backslash is not required after the final directory name in either anOldName or aNewName.

See class CFileMan for information on renaming multiple files.

Parameters

const TDesC &anOldName

File or directory to be renamed. Any path components which are not specified here will be taken from the session path.

const TDesC &aNewName

Path specifying the new name for the file or directory and/or its new parent directory. All directories specified in this path must exist. Any path components which are not specified here will be taken from the session path.

Return value

TInt

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

See also:


Replace()

Capability: Dependent If either anOldName or aNewName is /Sys then Tcb capability is required. If either anOldName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required. If either anOldName or aNewName is /Resource then Tcb capability is required.

IMPORT_C TInt Replace(const TDesC &anOldName, const TDesC &aNewName);

Description

Replaces a single file with another.

This function does not support the use of wildcards. Unlike Rename(), it only applies to files.

This function operates as follows:

1. if the aNewName file does not exist, it is created.

2. anOldName's contents, attributes and the date and time of its last modification are copied to file aNewName, overwriting any existing contents and attribute details.

3. anOldName is deleted.

anOldName may be hidden, read-only or a system file. However, neither anOldName, nor, if it exists, aNewName, can be open; aNewName must not be read-only. Both files must be on the same drive.

Parameters

const TDesC &anOldName

The file to be replaced. Must exist and must be closed. It is deleted by this function.

const TDesC &aNewName

The file to replace anOldName. Does not need to exist, but if it does exist, it must be closed. If it exists, its name remains unchanged but its contents, attributes and the date and time of its last modification are replaced by those of anOldName. If it does not exist, it will be created and is assigned the contents and attributes of anOldName. Must not be followed by a trailing backslash.

Return value

TInt

KErrNone, if successful; KErrAccessDenied, if an attempt is made to replace a directory; otherwise one of the other system-wide error codes.


Att()

Capability: Dependent If aName contains /sys/ then AllFiles capability is required. If aName contains /Private/ and does not match this process' SID then AllFiles capability is required.

IMPORT_C TInt Att(const TDesC &aName, TUint &aAttValue) const;

Description

Gets a file's attributes.

Parameters

const TDesC &aName

The filename. Any path components which are not specified here will be taken from the session path.

TUint &aAttValue

On return, the individual bits within the byte indicate which attributes have been set. For more information see KEntryAttNormal and the other file/directory attributes.

Return value

TInt

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

See also:


SetAtt()

Capability: Dependent If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required.

IMPORT_C TInt SetAtt(const TDesC &aName, TUint aSetAttMask, TUint aClearAttMask);

Description

Sets or clears the attributes of a single file or directory.

The function uses two bitmasks. The first bitmask specifies the attributes to be set; the second specifies the attributes to be cleared.

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

Parameters

const TDesC &aName

File or directory name. Any path components which are not specified here will be taken from the session path. Must not include wildcard characters. The file must be closed.

TUint aSetAttMask

Bitmask indicating the attributes to be set.

TUint aClearAttMask

Bitmask indicating the attributes to be cleared. For more information, see KEntryAttNormal and the other file or directory attributes.

Return value

TInt

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

Panic codes

FSCLIENT

21 if any attribute appears in both bitmasks.


Modified()

Capability: Dependent If aName contains /sys/ then AllFiles capability is required. If aName contains /Private/ and does not match this process' SID then AllFiles capability is required.

IMPORT_C TInt Modified(const TDesC &aName, TTime &aTime) const;

Description

Gets the last modification date and time of a file or a directory, in UTC.

If there has been no modification, the function gets the date and time of the file or directory's creation.

Parameters

const TDesC &aName

File or directory name.

TTime &aTime

On return, contains the date and time of the file or directory's last modification in universal time.

Return value

TInt

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


SetModified()

Capability: Dependent If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required.

IMPORT_C TInt SetModified(const TDesC &aName, const TTime &aTime);

Description

Sets the date and time that the contents of a file or directory were modified, in UTC.

Parameters

const TDesC &aName

File or directory name.

const TTime &aTime

The new date and time that the file or directory was modified in universal time.

Return value

TInt

KErrNone if successful; KErrInUse, if the file is open; otherwise one of the other system-wide error codes.


Entry()

Capability: Dependent If aName contains "\\Sys\\" and includes an additional file or directory then AllFiles capability is required. For example, the paths "c:\\sys" and "c:\\sys\\" will always be readable, whereas the path "c:\\sys\\abc\\" will only be readable with AllFiles capability. If aName contains \Private\ and includes an additional file, or a directory which does not match this process' SID, then AllFiles capability is required. For example, the paths "c:\\private" and "c:\\private\\" will always be readable, whereas the path "c:\\private\\<n>\\" will only be readable with AllFiles capability or if matches the process' SID.

IMPORT_C TInt Entry(const TDesC &aName, TEntry &anEntry) const;

Description

Gets the entry details for a file or directory.

This information includes UID information.

Parameters

const TDesC &aName

Name of file or directory.

TEntry &anEntry

On return, contains the entry details for the file or directory. TEntry::iModified contains UTC date and time.

Return value

TInt

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


SetEntry()

Capability: Dependent If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required.

IMPORT_C TInt SetEntry(const TDesC &aName, const TTime &aTime, TUint aSetAttMask, TUint aClearAttMask);

Description

Sets both the attributes and the last modified date and time for a file or directory.

The function uses two bitmasks. The first bitmask determines which attributes should be set. The second bitmask determines which should be cleared.

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

Parameters

const TDesC &aName

File or directory name.

const TTime &aTime

New date and time. UTC date and time should be used.

TUint aSetAttMask

Bitmask indicating which attributes are to be set.

TUint aClearAttMask

Bitmask indicating which attributes are cleared. For more information, see KEntryAttNormal, and the other file or directory attributes.

Return value

TInt

KErrNone, if successful; KErrInUse, if the file is open; otherwise one of the other system-wide error codes.

Panic codes

FSCLIENT

21 if any attribute appears in both bitmasks.

See also:


ReadFileSection()

Capability: Dependent If the path for aName starts with /Sys capability AllFiles is required If the path for aName starts with /Private and this process does not have the relevant SID capability AllFiles is required

IMPORT_C TInt ReadFileSection(const TDesC &aName, TInt aPos, TDes8 &aDes, TInt aLength) const;

Description

Reads data from a file without opening it.

The contents of the file can be accessed regardless of the file's lock state.

The file may be open by any number of other clients for reading or writing. In allowing such access to a file, the fileserver makes no guarantees as to the validity of the data it returns.

Parameters

const TDesC &aName

Name of the file to be accessed.

TInt aPos

The offset, in bytes, from the start of the file where reading is to start.

TDes8 &aDes

On return, contains the data read from the file. The length of the descriptor is set to the number of bytes read. If the specified offset lies beyond the end of the file, no data is read and the length of this descriptor is set to zero.

TInt aLength

The number of bytes to be read from the file.

Return value

TInt

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

Panic codes

FSCLIENT

19 if aPos negative.

FSCLIENT

26 if aLength is greater than the maximum length of the target descriptor.


IsValidDrive()

static IMPORT_C TBool IsValidDrive(TInt aDrive);

Description

Tests whether the specified drive number is valid.

A valid drive number is any number between 0 and (KMaxDrives-1) inclusive, or the specific value KDefaultDrive (implying the session default drive).

Parameters

TInt aDrive

The drive number.

Return value

TBool

True if the drive is valid; false if not.

See also:


CharToDrive()

static IMPORT_C TInt CharToDrive(TChar aChar, TInt &aDrive);

Description

Maps a drive character to a drive number.

The drive character must be in the range A to Z or a to z. For example, drive A (or a) corresponds to zero, drive B (or b) corresponds to 1 etc. For the drive number enumeration, see TDriveNumber.

Parameters

TChar aChar

The drive character.

TInt &aDrive

On return, contains the drive number.

Return value

TInt

KErrNone, if successful; KErrArgument, if the drive character is not in the range A to Z or a to z.

See also:


DriveToChar()

static IMPORT_C TInt DriveToChar(TInt aDrive, TChar &aChar);

Description

Maps a drive number to the corresponding character.

The drive number must be in the range 0 to (KMaxDrives-1). For example, drive number zero (EDriveA) corresponds to drive A, one (EDriveB) corresponds to drive B. For the drive number enumeration, see TDriveNumber.

The drive number can also be KDefaultDrive, implying the default drive. In this case the current drive is taken and converted.

Parameters

TInt aDrive

The drive number.

TChar &aChar

On return, contains the drive character.

Return value

TInt

KErrNone, if successful; KErrArgument, if the drive number is invalid; otherwise one of the other system-wide error codes.


IsRomAddress()

static IMPORT_C TBool IsRomAddress(TAny *aAny);

Description

Tests whether the specified address is in ROM.

Parameters

TAny *aAny

The address.

Return value

TBool

True, if the address is in ROM; false, if not.


GetSystemDrive()

static IMPORT_C TDriveNumber GetSystemDrive();

Description

Obtain the system drive number.

The System Drive is a defined drive on the device which is:

The System drive is utilised as:

It the system drive is not set previously (see RFs::SetSystemDrive) EDriveC is returned by default.

Return value

TDriveNumber

TDriveNumber contains the drive number of the system drive.

See also:


GetSystemDriveChar()

static IMPORT_C TChar GetSystemDriveChar();

Description

This is a wrapper around GetSystemDrive() function. It returns the character corresponding to the system drive.

aDriveChar On return, contains the system drive character

Return value

TChar

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


SetSystemDrive()

Capability: TCB

IMPORT_C TInt SetSystemDrive(TDriveNumber aSystemDrive);

Description

Set a specified drive as a "System Drive", see RFs::GetSystemDrive(). The "System Drive" can be set only once, any subsequent calls will result in the error 'KErrAlreadyExists'.

The media type for the system drive shall be one of the: EMediaHardDisk, EMediaFlash, EMediaNANDFlash, EMediaRam Required drive attributes: KDriveAttLocal, KDriveAttInternal Prohibited drive attributes: KDriveAttRom,KDriveAttRedirected,KDriveAttSubsted,KDriveAttRemovable

Parameters

TDriveNumber aSystemDrive

specifies the drive number to be set as System Drive

Return value

TInt

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


ResourceCountMarkStart()

IMPORT_C void ResourceCountMarkStart() const;

Description

Marks the start of resource count checking.

Typically, this function is called immediately after a client is connected to the file server, and before any resources are opened.


ResourceCountMarkEnd()

IMPORT_C void ResourceCountMarkEnd() const;

Description

Ends resource count checking.

A panic is raised if the number of resources opened since the start of resource count checking is not equal to the number of resources closed. Typically, this function is called immediately before closing a session with the file server.


ResourceCount()

IMPORT_C TInt ResourceCount() const;

Description

Gets the number of currently open resources.

The resource count is incremented by one: when a file or directory is opened, when a device is opened in preparation for formatting, when a direct access channel to a disk is opened.

Return value

TInt

The number of resources currently open.


IsFileOpen()

Capability: Dependent If the path for aFileName starts with /Sys capability AllFiles is required If the path for aFileName starts with /Private and this process does not have the relevant SID capability AllFiles is required

IMPORT_C TInt IsFileOpen(const TDesC &aFile, TBool &anAnswer) const;

Description

Tests whether a file is open.

This function is useful because several file based operations provided by the RFs class, for example: Delete(), Replace() and Rename(), require that the file be closed.

Parameters

const TDesC &aFile

The name of the file to test. Any path components which are not specified here will be taken from the session path. If a directory is specified instead of a file then KErrNone will be returned and anAnswer will be set to EFalse.

TBool &anAnswer

On return, true if the file is open, false if closed.

Return value

TInt

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


CheckDisk()

Capability: DiskAdmin

IMPORT_C TInt CheckDisk(const TDesC &aDrive) const;

Description

Checks the integrity of the disk on the specified drive. On FAT, this checks if a cluster number is invalid, if a cluster is allocated to more than one file entry, if an unallocated cluster is not set free, and if size of an entry is invalid.

Parameters

const TDesC &aDrive

Path indicating the drive which contains the disk to be checked. If the drive information is not specified the current session drive is taken by default. Checkdisk is performed on the requested drive irrespective of the correctness or existance of the given path.

Return value

TInt

KErrNone, if successful; 1, if successful but a file cluster contains a bad value; 2, if successful but two files are linked to the same cluster; 3, if successful but an unallocated cluster contains a value; 4, if successful but the size of a file is not equal to the number of clusters in chain; KErrNotReady, if the specified drive is empty; KErrNotSupported, if the drive cannot handle this request; KErrPermissionDenied, if the caller doesn't have DiskAdmin capability; KErrTooBig, if the drives folder depth exceededs 25; Other system wide error codes may also be returned.


ScanDrive()

Capability: DiskAdmin

IMPORT_C TInt ScanDrive(const TDesC &aDrive) const;

Description

Checks the specified drive for errors and corrects them. Specifically, it checks if long file name entries' IDs are in sequence and short name is valid, and file's allocated clusters are not used by other files.

This does not run on the internal RAM drive, and only applies to a FAT file system.

Parameters

const TDesC &aDrive

Path indicating the drive which contains the disk to be checked. If the drive information is not specified the current session drive is taken by default. ScanDrive is performed on the requested drive irrespective of the correctness or existance of the given path.

Return value

TInt

KErrNone if successful, KErrPermissionDenied if caller doesn't have capability DiskAdmin, KErrInUse if drive is in use, otherwise one of the other system-wide error codes


GetShortName()

Capability: Dependent If the path for aLongName starts with /Sys capability AllFiles is required If the path for aLongName starts with /Private and this process does not have the relevant SID capability AllFiles is required

IMPORT_C TInt GetShortName(const TDesC &aLongName, TDes &aShortName) const;

Description

Gets the short filename associated with a VFAT long filename.

The short filename has a limit of eight characters for the file name and three characters for the extension.

Parameters

const TDesC &aLongName

The long filename. Any path components which are not specified here will be taken from the session path. If the path specifies a directory, it may or may not be followed by a trailing backslash.

TDes &aShortName

On return, contains the short filename associated with the file or directory specified in aLongName.

Return value

TInt

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


GetLongName()

Capability: Dependent If the path for aShortName starts with /Sys capability AllFiles is required If the path for aShortName starts with /Private and this process does not have the relevant SID capability AllFiles is required

IMPORT_C TInt GetLongName(const TDesC &aShortName, TDes &aLongName) const;

Description

Gets the long filename associated with a short (8.3) filename.

A long filename has a limit of 256 characters for each component, as well as a limit of 256 characters for the entire path.

Parameters

const TDesC &aShortName

The short file name. Any path components which are not specified here will be taken from the session path. If the path specifies a directory, it may or may not be followed by a trailing backslash.

TDes &aLongName

On return, contains the long version of the name.

Return value

TInt

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


GetNotifyUser()

IMPORT_C TBool GetNotifyUser();

Description

Tests whether user notification of file read or write failure is in effect.

Return value

TBool

True if notification in effect, false if not.


SetNotifyUser()

IMPORT_C void SetNotifyUser(TBool aValue);

Description

Sets whether the user should be notified of file read or write failure. Note that if some drive is mounted as synchronous (see RFs::MountFileSystem), the user won't be notified about read/write failures on it.

Parameters

TBool aValue

ETrue, if user is to be notified of read or write failures; EFalse, for no notification.


IsFileInRom()

Capability: Dependent If the path for aFileName starts with /Sys capability AllFiles is required If the path for aFileName starts with /Private and this process does not have the relevant SID capability AllFiles is required

IMPORT_C TUint8 *IsFileInRom(const TDesC &aFileName) const;

Description

Gets a pointer to the specified file, if it is in ROM.

Note that this is not a test of whether the file is on the Z: drive, as the Z: drive may consist of a ROM and another file system, using the composite file system. For example, the file system may be ROFS, and the underlying media NAND flash.

Parameters

const TDesC &aFileName

The filename whose address is sought. Cannot include wildcards. Any path components which are not specified here will be taken from the session path.

Return value

TUint8 *

Address of the start of the file, if it is in ROM. This is NULL, if the file is not in ROM. Note that for the composite file system, the file might be on the Z: drive but in a non-ROM file system (i.e. ROFS), in which case the function still returns NULL.


IsValidName()

IMPORT_C TBool IsValidName(const TDesC &anEntryName) const;

Description

Tests whether a filename and path are syntactically correct.

The following restrictions apply to the path and to its components:

1. Wildcards are not allowed in any path component, including the filename and extension. 2. Double backslashes are not allowed anywhere in the path 3. The following 6 characters cannot appear in the path: < > : " / | 4. Either or both of a filename or extension must be present. This means that a valid aFileName can not end with backslash (like "c:\\SomeName\\"), because it will mean that "SomeName" is a directory.

5. The entire component following the final backslash (the filename and extension) cannot consist solely of space characters, or of a single or double dot.

6. Spaces between the drive, if specified, and the first directory in the path are illegal, although there may be spaces between other path components, for example, between directories.

7. If the path in aFileName is not fully specified, i.e. doesn't look like "c:\\Dir1\\File1.bin", all missing parts of the full path will be taken from the session path,

Parameters

const TDesC &anEntryName

The path to be checked for validity. May specify a filename alone, or an entire path specification, including drive letter. If a path is specified, all components are checked for validity.

Return value

TBool

ETrue, if the name is valid (conforms to the mentioned above criteria); EFalse otherwise.

See also:


IsValidName()

IMPORT_C TBool IsValidName(const TDesC &aFileName, TText &aBadChar) const;

Description

The following restrictions apply to the path and to its components:

1. Wildcards are not allowed in any path component, including the filename and extension. 2. Double backslashes are not allowed anywhere in the path 3. The following 6 characters cannot appear in the path: < > : " / | 4. Either or both of a filename or extension must be present. This means that a valid aFileName can not end with backslash (like "c:\\SomeName\\"), because it will mean that "SomeName" is a directory.

5. The entire component following the final backslash (the filename and extension) cannot consist solely of space characters, or of a single or double dot.

6. Spaces between the drive, if specified, and the first directory in the path are illegal, although there may be spaces between other path components, for example, between directories.

7. If the path in aFileName is not fully specified, i.e. doesn't look like "c:\\Dir1\\File1.bin", all missing parts of the full path will be taken from the session path,

Parameters

const TDesC &aFileName

The path to be checked for validity. May specify a filename alone, or an entire path specification, including drive letter. If a path is specified, all components are checked for validity.

TText &aBadChar

reference to the variable that on return can contain illegal character from aFileName. 1. if the filename and optional path in aFileName are valid, this method will return ETrue and aBadChar will be set to 0x00. 2. if there is an illegal character in aFileName, this method will return EFalse and aBadChar will contain this illegal character. 3. if there is no illegal characters in aFileName, but this is still not a valid filename (like "\\SomeName\\") this method will return EFalse and aBadChar will contain space ' ' or code 0x20.

Return value

TBool

ETrue, if the name is valid (conforms to the mentioned above criteria); EFalse otherwise.

See also:


GetDriveName()

IMPORT_C TInt GetDriveName(TInt aDrive, TDes &aDriveName) const;

Description

Gets the name of a drive.

Drive naming is optional. If the drive specified has not been assigned a name, this function returns a descriptor whose length is zero.

Parameters

TInt aDrive

The drive number. Specify a drive in the range EDriveA to EDriveZ for drives A to Z, respectively. The default drive is the session default drive represented by KDefaultDrive.

TDes &aDriveName

On return, the drive name.

Return value

TInt

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

See also:


SetDriveName()

Capability: DiskAdmin

IMPORT_C TInt SetDriveName(TInt aDrive, const TDesC &aDriveName);

Description

Sets the name of a drive.

Drive naming is optional. Any drive can be assigned a name, and more than one drive can share the same name.

Parameters

TInt aDrive

The drive number. Specify a drive in the range EDriveA to EDriveZ for drives A to Z, respectively. Specify KDefaultDrive for the session default drive.

const TDesC &aDriveName

The name of the drive, with a maximum of 256 characters. The name cannot contain the 6 characters < > : " / |

Return value

TInt

KErrNone if successful; KErrBadName, if the name contains illegal characters; otherwise one of the other system-wide error codes.


LoaderHeapFunction()

IMPORT_C TInt LoaderHeapFunction(TInt aFunction, TAny *aArg1=0, TAny *aArg2=0);

Description

This member function is not implemented in this version of Symbian OS. It always returns KErrNotSupported.

Parameters

TInt aFunction

TAny *aArg1

TAny *aArg2

Return value

TInt

KErrNotSupported is returned always.


SetErrorCondition()

IMPORT_C TInt SetErrorCondition(TInt anError, TInt aCount=0);

Description

Sets the failure condition.

This function can only be used in debug builds or if _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt anError

An error condition to be simulated

TInt aCount

An error condition is set after aCount instances of occurence.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


SetDebugRegister()

IMPORT_C TInt SetDebugRegister(TInt aVal);

Description

Sets the debug register to the given value.

This function can only be used in debug builds or if _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aVal

Value to be set

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


SetAllocFailure()

IMPORT_C TInt SetAllocFailure(TInt aAllocNum);

Description

Fails an allocation after aAllocNum successes.

This function can only be used in debug builds or if _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aAllocNum

Count after which allocation failure is expected.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


DebugNotify()

IMPORT_C void DebugNotify(TInt aDrive, TUint aNotifyType, TRequestStatus &aStat);

Description

Request notification of a file server event - file system specific.

This function can only be used in debug builds or if _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aDrive

A drive on which the file server event notification is requested; this can be one of the values defined by TDriveNumber.

TUint aNotifyType

A number identifying the event that should cause notification;

TRequestStatus &aStat

The request status used to contain completion information for the function. On completion, contains a system-wide error code.

See also:


ControlIo()

IMPORT_C TInt ControlIo(TInt aDrive, TInt aCommand);

Description

General purpose test interface - file system specific.

This function can only be used in debug builds or if _USE_CONTROLIO, _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

There are drive specific and non-drive specific commands. Following are non-drive specific commands

Parameters

TInt aDrive

A drive on which aCommand is to be executed; this can be one of the values defined by TDriveNumber.

TInt aCommand

A command to be executed, specific to the file system implementation.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


ControlIo()

IMPORT_C TInt ControlIo(TInt aDrive, TInt aCommand, TDes8 &aParam1);

Description

General purpose test interface - file system specific.

This function can only be used in debug builds or if _USE_CONTROLIO, _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aDrive

A drive on which aCommand is to be executed; this can be one of the values defined by TDriveNumber.

TInt aCommand

A command to be executed, specific to the file system implementation.

TDes8 &aParam1

Placeholder for a parameter, specific to the file system implementation.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


ControlIo()

IMPORT_C TInt ControlIo(TInt aDrive, TInt aCommand, TDes8 &aParam1, TDes8 &aParam2);

Description

General purpose test interface - file system specific.

This function can only be used in debug builds or if _USE_CONTROLIO, _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aDrive

A drive on which aCommand is to be executed; this can be one of the values defined by TDriveNumber.

TInt aCommand

A command to be executed, specific to the file system implementation.

TDes8 &aParam1

Placeholder for a parameter, specific to the file system implementation.

TDes8 &aParam2

Placeholder for a parameter, specific to the file system implementation.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


ControlIo()

IMPORT_C TInt ControlIo(TInt aDrive, TInt aCommand, TAny *aParam1, TAny *aParam2);

Description

General purpose test interface - file system specific.

This function can only be used in debug builds or if _USE_CONTROLIO, _DEBUG or _DEBUG_RELEASE is defined. In release build, this method is not implemented and it always returns KErrNotSupported.

Parameters

TInt aDrive

A drive on which aCommand is to be executed; this can be one of the values defined by TDriveNumber.

TInt aCommand

A command to be executed, specific to the file system implementation.

TAny *aParam1

Placeholder for a parameter, specific to the file system implementation.

TAny *aParam2

Placeholder for a parameter, specific to the file system implementation.

Return value

TInt

On completion, KErrNone if successful, otherwise one of the system wide error codes in debug builds. KErrNotSupported in release build.


LockDrive()

Capability: DiskAdmin

IMPORT_C TInt LockDrive(TInt aDrv, const TMediaPassword &aOld, const TMediaPassword &aNew, TBool aStr);

Description

Sets the password for the media in the specified drive.

The media is not necessarily locked afterwards. Accessibility is determined by the following rules:

Parameters

TInt aDrv

The drive.

const TMediaPassword &aOld

The existing password. If no password is set, this must be a zero-length descriptor.

const TMediaPassword &aNew

The new password.

TBool aStr

ETrue if the new password is to be saved to the controller password store; EFalse if not.

Return value

TInt

KErrNone if successful; KErrNotSupported if the media does not support password locking.


UnlockDrive()

Capability: DiskAdmin

IMPORT_C TInt UnlockDrive(TInt aDrv, const TMediaPassword &Pswd, TBool aStr);

Description

Unlocks the media in the specified drive.

The password must be added to the MultiMedia card controller's password store so that the controller can subsequently issue the password without the user having to be prompted for it again.

Parameters

TInt aDrv

The drive.

const TMediaPassword &Pswd

The password.

TBool aStr

Specify ETrue to add the password to the controller's password store.

Return value

TInt

KErrNone, if successful; KErrAccessDenied, if the password is incorrect; KErrAlreadyExists, if the card has already been unlocked; KErrNotSupported, if the media does not support password locking.


ClearPassword()

Capability: DiskAdmin

IMPORT_C TInt ClearPassword(TInt aDrv, const TMediaPassword &aPswd);

Description

Clears the password from the locked MultiMedia card in the specified drive.

Clearing the password causes the MultiMedia card controller to set the password to null.

Parameters

TInt aDrv

The drive.

const TMediaPassword &aPswd

The current password, which is required to perform this operation.

Return value

TInt

KErrNone, if successful; KErrAccessDenied, if the password is wrong or the card is still locked; otherwise one of the other system-wide error codes.


ErasePassword()

Capability: DiskAdmin

IMPORT_C TInt ErasePassword(TInt aDrv);

Description

Erase the password from the locked MultiMedia card in the specified drive.

Used when the password is unknown, and may result in the media being erased.

Successful execution of this call may result in leaving the media in unformatted state. Hence, it is recommended to format the Multimedia card after calling RFs::ErasePassword().

Parameters

TInt aDrv

The drive.

Return value

TInt

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


SetSessionToPrivate()

IMPORT_C TInt SetSessionToPrivate(TInt aDrive);

Description

Sets the session path to point to the private path on the specified drive.

The private directory does not need to exist at this point.

The private path for a process has the form: \Private\13579BDF\ where 13579BDF is the identity of the process.

Parameters

TInt aDrive

The drive for which information is requested. Specify a drive in the range EDriveA to EDriveZ for drives A to Z respectively.

Return value

TInt

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


PrivatePath()

IMPORT_C TInt PrivatePath(TDes &aPath);

Description

Creates the text defining the private path for a process.

The private path for a process has the form: \Private\13579BDF\ where 13579BDF is the identity of the process.

Parameters

TDes &aPath

On successful return, contains the private path for a process.

Return value

TInt


CreatePrivatePath()

IMPORT_C TInt CreatePrivatePath(TInt aDrive);

Description

Creates the private path for a process on the specified drive.

The private path for a process has the form: \Private\13579BDF\ where 13579BDF is the identity of the process.

Parameters

TInt aDrive

The drive for which the private path is to be created. Specify a drive in the range EDriveA to EDriveZ for drives A to Z respectively.

Return value

TInt

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


StartupInitComplete()

IMPORT_C void StartupInitComplete(TRequestStatus &aStat);

Description

Noifies the file server that startup initialisation is complete.

Parameters

TRequestStatus &aStat

Request status object.


SetLocalDriveMapping()

IMPORT_C TInt SetLocalDriveMapping(const TDesC8 &aMapping);

Description

Parameters

const TDesC8 &aMapping

Return value

TInt


FinaliseDrives()

Capability: DiskAdmin

IMPORT_C TInt FinaliseDrives();

Description

Makes the best effort to finalise all drives in the system. Effectively calls RFs::FinaliseDrive(..., EFinal_RW) to all present drives in the system. This makes impossible to analyse the error code if the finalisation of some fails. It is much better to use RFs::FinaliseDrive(...) specifying concrete drive number and desired finalisation mode.

Return value

TInt

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


FinaliseDrive()

Capability: DiskAdmin

IMPORT_C TInt FinaliseDrive(TInt aDriveNo, TFinaliseDrvMode aMode) const;

Description

Finalise the given drive. This operation is intended to put the drive into the consistent state when it is safe to remove it physically or switch the power off.

Parameters

TInt aDriveNo

drive number

TFinaliseDrvMode aMode

describes the finalisation operation, see RFs::TFinaliseDrvMode enum

Return value

TInt

KErrNone on success, KErrArgument if the function arguments are invalid KErrInUse if the drive has opened objects (files, directories etc.) and therefore can not be finalised KErrCorrupt if the drive is corrupt. System wide error codes otherwise.


SwapFileSystem()

Capability: DiskAdmin

IMPORT_C TInt SwapFileSystem(const TDesC &aOldFileSystemName, const TDesC &aNewFileSystemName, TInt aDrive) const;

Description

Dismount aOldFileSystemName and mount aNewFileSystemName in an atomic operation

If swapping in the composite filesystem, and no mounts have been added to it, then ROFS is added to it by default. The synchronous state of the composite filesystem will be used in preference to that of the old filesystem when it is mounted.

Parameters

const TDesC &aOldFileSystemName

The filesystem name that is currently on the drive.

const TDesC &aNewFileSystemName

The filesystem name that is to be swapped onto the drive.

TInt aDrive

The drive for which the filesystem is to be swapped.

Return value

TInt

KErrNone if successful KErrInUse if a dismount is pending on the drive KErrNotSupported if swapping Z drive with something other then composite or if the drive is asynchronous KErrAlreadyExists if swapping the composite filesystem, and it is already mounted KErrNotFound If the filesystem name provided could not be found.


ReserveDriveSpace()

IMPORT_C TInt ReserveDriveSpace(TInt aDriveNo, TInt aSpace);

Description

Reserves an area of a drive. It is intended that sensible (tm) apps will reserve a small area of disk for 'emergency' use in case of later out of disk situations. If the amount of reserved space later needs to be readjusted, this method should be called again with aSpace as the amount of extra space needed.

Once space has been reserved via this method, an application can use RFs::GetReserveAccess to gain access to the reserved area prior to executing disk space critical sections of code. After the section of code is complete, the application should release access to the reserved area.

For internal drives, reserved space will be lost if a reboot occurs. For removeable drives, reserved space may be lost if there is a media change.

Reserved space will be cleaned up automatically when the RFs is closed.

Each drive has a max amount of space available to be reserved, and individual sessions also have a max amount of space. These are defined in f32/sfile/sf_std.h as KMaxTotalDriveReserved and KMaxSessionDriveReserved respectively. Once space is reserved, it is only available to the reserving session until that session releases the reserved space.

Parameters

TInt aDriveNo

Which drive to reserve space on

TInt aSpace

Amount of space to reserve

Return value

TInt

KErrNone if successful KErrInUse if the session already has reserved access KErrArgument if aSpace is invalid (greater than KMaxSessionDriveReserved, negative number, etc.) KErrDiskFull if insufficient space is left on the drive to service the request KErrTooBig if this request would overflow the available reserve (greater than KMaxTotalDriveReserved) any of the possible error return codes from TDrive::Volume()


GetReserveAccess()

IMPORT_C TInt GetReserveAccess(TInt aDriveNo);

Description

Get exclusive access for this session to overwrite a specific disk area, which has previously been reserved via RFs::ReserveDriveSpace

Parameters

TInt aDriveNo

drive on which to get reserved access

Return value

TInt

KErrNone if successful KErrPermissionDenied if the drive has no spare reserved space


ReleaseReserveAccess()

IMPORT_C TInt ReleaseReserveAccess(TInt aDriveNo);

Description

Release exclusive access for this session to overwrite a specific disk area.

Parameters

TInt aDriveNo

drive on which to release reserved access

Return value

TInt

KErrNone (always returned)


NotifyDismount()

IMPORT_C void NotifyDismount(TInt aDrive, TRequestStatus &aStat, TNotifyDismountMode aMode=EFsDismountRegisterClient) const;

Description

Sets up a pending dismount notifier, the type of which is specified by TNotifyDismountMode.

EFsDismountRegisterClient - Sets up a notifier to signal the client when a dismount has been requested. EFsDismountNotifyClients - Notifies all clients (who registered using EFsDismountRegisterClient) of a pending dismount, signalling the caller when all clients have responded. EFsDismountForceDismount - Forcibly dismounts the file system without signalling any registered clients.

This API is intended to be used to allow applications and servers to commit their data to the media prior to the file system being dismounted. The application forcing the dismount should first attempt to notify all clients. If all clients don't respond in a a reaonable time, the dismount request may be cancelled, followed by a forced dismount.

Any handles left open on the file system shall be disassociated from the media. Attempts to access these resources shall return with the KErrDismounted error code.

Parameters

TInt aDrive

TRequestStatus &aStat

Completed when all clients have indicated that it is safe to remove the media

TNotifyDismountMode aMode

A TNotifyDismountMode specifying the behaviour of the notification API


NotifyDismountCancel()

IMPORT_C void NotifyDismountCancel(TRequestStatus &aStat) const;

Description

Cancels the oustanding dismount notifier, completing with KErrCancel.

Parameters

TRequestStatus &aStat

The request status object associated with the request to be cancelled.


NotifyDismountCancel()

IMPORT_C void NotifyDismountCancel() const;

Description

Cancel all oustanding dismount notifiers for this session, completing with KErrCancel.


AllowDismount()

IMPORT_C TInt AllowDismount(TInt aDrive) const;

Description

Used by a client to indicate that it is safe to dismount the file system. This should be called after receiving a pending media removal notification.

Not calling this does not guarantee that the dismount will not occur as the application requesting the dismount may decide to forcibly dismount after a given timeout period.

Parameters

TInt aDrive

Return value

TInt

KErrNone if successful


AddCompositeMount()

Capability: DiskAdmin

IMPORT_C TInt AddCompositeMount(const TDesC &aFileSystemName, TInt aLocalDriveToMount, TInt aCompositeDrive, TBool aSync) const;

Description

Adds a local drive to the composite filesystem. This can only be used before the composite filesystem is mounted. The local drive is mounted with the filesystem provided. If any local drive added is marked to be asynchronous, then the whole composite drive will be treated asynchronous.

Parameters

const TDesC &aFileSystemName

The filesystem of the local drive to be added.

TInt aLocalDriveToMount

The local drive to be added.

TInt aCompositeDrive

The drive the composite filesystem will be mounted on.

TBool aSync

If the filesystem added here is preferred to be synchronous.

Return value

TInt

KErrNone if successful KErrNotFound If the filesystem name provided could not be found. KErrNotReady If the composite filesystem has not been initialised. KErrNotSupported If the composite filesystem is already mounted or the parameters passed are unsupported


SetNotifyChange()

Capability: DiskAdmin

IMPORT_C TInt SetNotifyChange(TBool aNotifyChange);

Description

Enables/Disables change notification on a per-session basis. Change notification is enabled by default, and can be disabled using this API. Disabling change notification will result in clients of the file server not being notified of events such as directory/file changes.

Parameters

TBool aNotifyChange

ETrue to enable change notifications, EFalse to disable.

Return value

TInt

KErrNone if successful.


VolumeIOParam()

IMPORT_C TInt VolumeIOParam(TInt aDriveNo, TVolumeIOParamInfo &aParamInfo) const;

Description

This function queries a set of I/O parameters on the specified volume, this includes the block size of underlying media, cluster size of the mounted file system and the recommended read/write buffer sizes.

The volume information is retuned through aParamInfo. Even if VolumeIOParam() returns successful, errors can effect the return value of each field within aParamInfo.

Parameters

TInt aDriveNo

A drive number, specifies which volume to query.

TVolumeIOParamInfo &aParamInfo

A TVolumeIOParamInfo containing the volume parameters.

Return value

TInt

KErrNone if successful; otherwise, another system wide error code is returned.


FileSystemSubType()

IMPORT_C TInt FileSystemSubType(TInt aDriveNo, TDes &aName) const;

Description

This function queries the sub type of the file system mounted on the specified volume. For example, 'FAT16' of the Fat file system.

TFSName is recommended as the type for aName when using this function.

NOTE: File systems without a sub type (For example, a ROM file system), the name of the file system is returned (For example, 'Rom').

Parameters

TInt aDriveNo

A drive number, specifies which volume to query.

TDes &aName

A descriptor containing the returned sub type name or file system name.

Return value

TInt

KErrNone if successful; KErrNotSuppoted if sub type is not supported; otherwise another system-wide error code is returned.

See also:


InitialisePropertiesFile()

Capability: Illegal

IMPORT_C TInt InitialisePropertiesFile(const TPtrC8 &aPtr) const;

Description

Sets the F32 properties file - Can only be called from the ESTART process

Parameters

const TPtrC8 &aPtr

A descriptor pointing to an INI file in ROM.

Return value

TInt

KErrNone if successful.

[Top]


Member enumerations


Enum TFinaliseDrvMode

TFinaliseDrvMode

Description

specifies drive finalisation modes

EFinal_RW

after successful finalisation the drive remains writable and will become "not finalised" after the first write operation.

EFinal_RO

after successful finalisation the drive becomes read-only