Symbian Developer Library

SYMBIAN OS V6.1 EDITION FOR C++

[Index] [Glossary] [Previous] [Next]



Location: f32file.h
Link against: efsrv.lib

Class RFs

RFs

Support

Supported from 5.0

Description

Handle to file server session. A program, or thread, may have arbitrarily many sessions open simultaneously.

Use this class for all file system manipulation, including

This class is not intended for user derivation.

Note that when using the functions provided by this class and a path is specified, the following restrictions apply to it and to its components:

Derivation

RFsHandle to file server session
RHandleBaseHandle to an object
RSessionBaseClient-side handle to a session with a server

Defined in RFs:
AddFileSystem(), Att(), CharToDrive(), CheckDisk(), ClearPassword(), Connect(), ControlIo(), DebugNotify(), DefaultPath(), Delete(), DismountFileSystem(), Drive(), DriveList(), DriveToChar(), Entry(), FileSystemName(), GetDir(), GetDriveName(), GetLongName(), GetNotifyUser(), GetShortName(), IsFileInRom(), IsFileOpen(), IsRomAddress(), IsValidDrive(), IsValidName(), LockDrive(), MkDir(), MkDirAll(), Modified(), MountFileSystem(), NotifyChange(), NotifyChangeCancel(), NotifyDiskSpace(), NotifyDiskSpaceCancel(), Parse(), ReadFileSection(), RealName(), RemoveFileSystem(), Rename(), Replace(), ResourceCount(), ResourceCountMarkEnd(), ResourceCountMarkStart(), RmDir(), ScanDrive(), SessionPath(), SetAtt(), SetDefaultPath(), SetDriveName(), SetEntry(), SetModified(), SetNotifyUser(), SetSessionPath(), SetSubst(), SetVolumeLabel(), Subst(), UnlockDrive(), Version(), Volume()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode


Connect to file server


Connect()

TInt Connect(TInt aMessageSlots=KFileServerDefaultMessageSlots);

Description

Connects a client process to the file server.

Notes:

Parameters

TInt aMessageSlots

The number of message slots required. The default is KFileServerDefaultMessageSlots.

Return value

TInt

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

[Top]


File and directory manipulation


MkDir()

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 an error.

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 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 another of the system-wide error codes.


MkDirAll()

TInt MkDirAll(const TDesC& aPath);

Description

Makes one or more directories. Any valid path component specified in the specified path 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 MkDir(), which creates only a single new directory.

Parameters

const TDesC& aPath

The path name indicating 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 another of the system-wide error codes.


RmDir()

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. 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 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, otherwise another of the system-wide error codes.

See also:


Delete()

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 may be deleted but system files may not be deleted.

See class CFileMan for information on deleting multiple files.

Parameters

const TDesC& aName

Name of 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 another of the system-wide error codes.

See also:


Rename()

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, see example below. The file or directory may not be moved to another device by this means, either explicitly (by another drive specified in the name) or implicitly (because the directory has been mapped to another device with SetSubst()).

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

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 another of the system-wide error codes.

See also:


Replace()

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:

anOldName may be hidden, read-only or a system file. However, neither anOldName or if it exists, aNewName, may be open and aNewName must not be read-only, or the function will fail, returning an error. 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 another of the system-wide error codes.

[Top]


File attributes


Att()

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

Description

Returns 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 another of the system-wide error codes.

See also:


SetAtt()

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

Description

Sets or clears the attributes of a single file.

The function uses two bitmasks. The first bitmask specifies the attributes to set. The second specifies the attributes to clear.

Notes:

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 seeKEntryAttNormal and the other file or directory attributes

Return value

TInt

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

See also:


Modified()

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

Description

Gets the last modification date and time of a file or directory. 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.

Return value

TInt

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


Entry()

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

Description

Gets the entry details, including UID information, for a file or directory.

Parameters

const TDesC& aName

Name of file or directory.

TEntry& anEntry

On return contains the entry details for a file or directory.

Return value

TInt

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


SetModified()

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

Description

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

Parameters

const TDesC& aName

File or directory name

const TTime& aTime

The new date and time of the file or directory's latest modification

Return value

TInt

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


SetEntry()

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 are cleared.

Notes:

Parameters

const TDesC& aName

File or directory name.

const TTime& aTime

New date and time for file or directory.

TUint aSetAttMask

Bitmask indicating which attributes are set

TUint aClearAttMask

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

Return value

TInt

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

See also:

[Top]


Real name


RealName()

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 EPOC 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 to

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 another of the system-wide error codes.

[Top]


Obtaining directory listings


GetDir()

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:

Parameters

const TDesC& aName

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

Flag indicating the order in which the entries are to be sorted. This flag is defined in TEntryKey.

CDir*& anEntryList

On return contains a list of directory and file entries.

Return value

TInt

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


GetDir()

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 inanEntryList. 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:

Parameters

const TDesC& aName

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 inanEntryList. 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 directry attributes.

TUint anEntrySortKey

Flag indicating the order in which entries in both lists are to be sorted. This flag is defined in TEntryKey.

CDir*& anEntryList

On return contains a filtered list of directories and files.

CDir*& aDirList

On return contains a list of directory entries only.

Return value

TInt

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


GetDir()

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. The TUidType parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.

Notes:

Parameters

const TDesC& aName

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 here will be included in the file list. Any or all of the three UIDs may be omitted. Any UID which is omitted will act in a similar manner to a wildcard character, matching to all UIDs. For more information see KEntryAttMatchMask and the other directory entry details. Also see KEntryAttNormal and the other file or directory attributes.

TUint anEntrySortKey

Flag indicating the order in which the entries are to be sorted. This flag is defined in TEntryKey.

CDir*& aFileList

On return contains a list of file entries

Return value

TInt

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

[Top]


Path handling


DefaultPath()

TInt DefaultPath(TDes& aPath) const;

Description

Gets the system default path. This path is assigned as the session path to new clients when they connect to the file server. There is a single system default path rather than one for each drive.

Parameters

TDes& aPath

On return, contains the system default path, including a trailing backslash.

Return value

TInt

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


SetDefaultPath()

TInt SetDefaultPath(const TDesC& aPath);

Description

Sets the system default path. This path is assigned as the session path to new clients when they connect to the file server. The session paths of existing clients remain unchanged. There is a single system default path rather than one for each drive.

Note:

Parameters

const TDesC& aPath

The new system default path. Consists of a drive and path. Normally, a drive should be specified, but if not, the system default drive is set to the drive specified in the existing session path. If a file is specified in the path, the function fails and returns an error. 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 another of the system-wide error codes.


SessionPath()

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

Parameters

TDes& aPath

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

Return value

TInt

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


SetSessionPath()

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:

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, 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 another of the system-wide error codes.

[Top]


Parsing


Parse()

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 may then use TParse’s getter functions to extract individual components of the resulting name. All the path components which are included in aName are put into the resulting filename; then, any components still missing are taken from the session path. See classTParse for more information on parsing file specifications.

If you specify

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

it is equivalent to

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

Note:

Parameters

const TDesC& aName

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

TParse& aParse

Instance of TParse, providing functions for extracting individual components of the resulting file name.

Return value

TInt

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


Parse()

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 may then use TParse’s getter functions to extract individual components of the resulting name. All the path components which are included in aName are put into the resulting filename; then, any missing components are taken from the optional aRelatedargument, which has next order of precedence; finally, any components still missing are taken from the session path. See class TParse for more information on parsing file specifications.

If you specify

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

it is equivalent to

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

Note:

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

Instance of TParse, providing functions for extracting individual components of the resulting file name.

Return value

TInt

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

[Top]


Drive and volume information


DriveList()

TInt DriveList(TDriveList& aList) const;

Description

Gets a list of the available drives. The drive list consists of an array of 26 bytes. Array index zero corresponds to drive A, one equals B etc. Each byte with a non zero value signifies that the corresponding drive contains recognised media.

Note:

Parameters

TDriveList& aList

On return, contains a list of available drives.

Return value

TInt

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


Drive()

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

Description

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

Note:

Parameters

TDriveInfo& anInfo

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

TInt aDrive=KDefaultDrive

The drive for which information is requested. SpecifyKDefaultDrive for the session default drive; specify a drive in range EDriveA to EDriveZ for drives A toZ.

Return value

TInt

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


Volume()

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:

Parameters

TVolumeInfo& aVol

On return, contains the volume information.

TInt aDrive

The drive which contains the media for which you want to display volume information. Specify a drive in the range EDriveA toEDriveZ for drives A to Z. The default drive is the session default driveKDefaultDrive.

Return value

TInt

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


SetVolumeLabel()

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

Description

Sets the label for a volume.

Note:

Parameters

const TDesC& aName

The volume label

TInt aDrive=KDefaultDrive

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. For the drive number enumeration, seeTDriveNumber. The default drive is the session default driveKDefaultDrive.

Return value

TInt

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


GetDriveName()

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

Drive number. Specify a drive in the range EDriveA toEDriveZ for drives A to Z. For the drive number enumeration, see TDriveNumber. The default drive is the session default drive KDefaultDrive.

TDes& aDriveName

On return, the drive name.

Return value

TInt

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


SetDriveName()

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

Description

Sets the name of a drive. Drive naming is optional. Any drive may be assigned a name and more than one drive may share the same name.

Parameters

TInt aDrive

Drive number. Specify KDefaultDrive for the session default drive; specify a drive in the range EDriveA toEDriveZ for drives A to Z. For the drive number enumeration, see TDriveNumber.

const TDesC& aDriveName

The name of the drive, with a maximum of 256 characters

Return value

TInt

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

[Top]


Drive mappings


IsValidDrive()

static TBool IsValidDrive(TInt aDrive);

Description

Tests whether a drive number is valid. A valid drive number is any number between 0 and 25 inclusive.

Parameters

TInt aDrive

Drive number. Specify KDefaultDrive for the session default drive. For the drive number enumeration, see TDriveNumber.

Return value

TBool

True if the drive specified is between EDriveA andEDriveZ inclusive; false if not.


CharToDrive()

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

Description

Maps a drive character to the corresponding number. The drive character must be in the range A to Z. For example, drive A corresponds to zero, drive B corresponds to 1. For the drive number enumeration, seeTDriveNumber.

Parameters

TChar aChar

Drive character

TInt& aDrive

On return, contains the drive number

Return value

TInt

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


DriveToChar()

static 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 25. For example, drive number zero (EDriveA) corresponds to drive A, one (EDriveB) corresponds to drive B. For the drive number enumeration, see TDriveNumber.

Parameters

TInt aDrive

Drive number

TChar& aChar

On return, contains the drive character

Return value

TInt

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

[Top]


Subst functions


Subst()

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

Description

Gets the path assigned to a drive letter bySetSubst().

Note:

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 range 0 (EDriveA) to 25 (EDriveZ) for drives Ato Z. The default drive is the session default driveKDefaultDrive.

Return value

TInt

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


SetSubst()

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:

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 drivesA to Z. Must not be local, ROM, or redirected, or 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 driveKDefaultDrive.

Return value

TInt

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

[Top]


Change notification


NotifyChange()

void NotifyChange(TNotifyType aType,TRequestStatus& aStat);

Description

Requests a notification of change to all files or directories. Changes are notified either following any change in the file system at all, or 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 would be either no updating at all or periodic monitoring for change — which would be wasteful.

This call is an asynchronous request and, as such, results in precisely one signal to the request status passed as a parameter. In order 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: otherwise, NotifyChangeCancel()can be used to explicitly cancel it.

Note:

Parameters

TNotifyType aType

Indicates what kind of change should result in notification.ENotifyEntry causes notification only when an entry is added or deleted or when a disk is formatted or changed. ENotifyAllcauses notification following any type of change, for instance when a file is written to, or when a file's attributes are changed.

TRequestStatus& aStat

Request status. KErrNone on completion, otherwise another of the system-wide error codes.


NotifyChange()

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

Description

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

Changes are notified either following any change in the file system at all, or 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 would be either no updating at all or periodic monitoring for change — which would be wasteful.

This call is an asynchronous request and, as such, results in precisely one signal to the request status passed as a parameter. In order 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: otherwise, NotifyChangeCancel()can be used to explicitly cancel it.

Note:

Parameters

TNotifyType aType

Indicates what kind of change should result in notification.ENotifyEntry causes notification only when an entry is added or deleted or when a disk is formatted or changed. ENotifyAllcauses notification following any type of change, for instance when a file is written to, or when a file's attributes are changed.

TRequestStatus& aStat

Request status. KErrNone on completion, otherwise another of the 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 "?:\\System\\Apps" or "*:\\System\\Apps", a client can ask to be notified of changes to a given directory on any drive.


NotifyChangeCancel()

void NotifyChangeCancel();

Description

Cancels a requested change notification — synchronous overload.


NotifyChangeCancel()

void NotifyChangeCancel(TRequestStatus& aStat);

Description

Cancels a requested change notification — asynchronous overload.

Parameters

TRequestStatus& aStat

Request status. KErrNone on successful completion, otherwise another of the system-wide error codes.


Version()

TVersion Version() const;

Description

Returns the version number.

Return value

TVersion

Version number.

[Top]


File systems


AddFileSystem()

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 another of the system-wide error codes.


MountFileSystem()

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

Parameters

const TDesC& aFileSystemName

The filename of the file system to be mounted

TInt aDrive

Drive on which the file system is to be mounted. EDriveA toEDriveZ.

Return value

TInt

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


RemoveFileSystem()

TInt RemoveFileSystem(const TDesC& aFileSystemName) const;

Description

Removes file system from the file server.

Parameters

const TDesC& aFileSystemName

The filename of the file system to be removed

Return value

TInt

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


DismountFileSystem()

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

Support

Supported from 5.1

Description

Dismounts a file system from the given drive.

Parameters

const TDesC& aFileSystemName

The name of the CObject-derived file system

TInt aDrive

Drive to dismount the file system from.

Return value

TInt

System-wide error codes including:KErrNotFound ifaFileSystemName is not found or if the drive does not have 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, substituted drive or the drive which is default drive.KErrArgument if the drive value out of the valid range. E.g. greater than zero and less than or equal to KMaxDrives=26

See also:


FileSystemName()

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

Support

Supported from 5.1

Description

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

Can be used before a call toDismountFileSystem().

Parameters

TDes& aName

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

TInt aDrive

The drive for which the file system name is required.

Return value

TInt

System-wide error codes including:KErrNotFound ifaFileSystemName is not found or if the drive does not have file system mounted on it.KErrArgument if the drive value out of the valid range. E.g. greater than zero and less than or equal toKMaxDrives=26

[Top]


Resource counting


ResourceCountMarkStart()

void ResourceCountMarkStart() const;

Description

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


ResourceCountMarkEnd()

void ResourceCountMarkEnd() const;

Description

Ends resource count checking. A panic occurs 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()

TInt ResourceCount() const;

Description

Returns the number of currently open resources. The resource count is incremented by one each time a file or directory is opened, when a device is opened in preparation for formatting, or when a direct access channel to a disk is opened.

Return value

TInt

The number of resources currently open

[Top]


Enquiry functions


IsFileOpen()

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 instanceDelete(), Rename() and Replace() require that the file must be closed.

Parameters

const TDesC& aFile

Name of the file to test. Any path components which are not specified here will be taken from the session path. Name of the file to test. Any path components which are not specified here will be taken from the session path.

TBool& anAnswer

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

Return value

TInt

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

See also:


CheckDisk()

TInt CheckDisk(const TDesC& aDrive) const;

Description

Checks the integrity of the disk contained in the specified driveaDrive.

Parameters

const TDesC& aDrive

Path indicating the drive which contains the disk to check.

Return value

TInt

KErrNone if successful and KErrNotReady if the drive specified is empty. Any other value indicates that the disk is corrupt.


ScanDrive()

TInt ScanDrive(const TDesC& aDrive) const;

Support

Supported from 6.0

Description

Checks the specified drive for specific errors and corrects them.

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

Parameters

const TDesC& aDrive

Path indicating the drive which contains the disk to check.

Return value

TInt

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


GetShortName()

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 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, 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 another of the system-wide error codes.


GetLongName()

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, a 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 path specifies a directory, may or may not be followed by a trailing backslash.

TDes& aLongName

On return, contains the long version of filenameaShortName.

Return value

TInt

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


IsRomAddress()

static TBool IsRomAddress(TAny* aAny);

Description

Tests whether the specified address is in ROM.

Parameters

TAny* aAny

The address.

Return value

TBool

True if address in ROM, false if not.


IsFileInRom()

TUint8* IsFileInRom(const TDesC& aFileName) const;

Description

Returns the address of a file located in ROM. If the file is not in ROM (i.e. not on drive Z:), the pointer returned is set to NULL.

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 a file in ROM


IsValidName()

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:

Parameters

const TDesC& anEntryName

Path to check 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

True if name is valid, false if invalid

See also:


IsValidName()

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

Description

Tests whether a filename and path are syntactically correct. The following restrictions apply to the path and to its components:

Parameters

const TDesC& aFileName

Path to check 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

On return, contains any illegal character withinaFileName — the name the client is querying.

Return value

TBool

True if name is valid, false if invalid

See also:

[Top]


User notification


GetNotifyUser()

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

void SetNotifyUser(TBool aValue);

Description

Sets whether the user should be notified of file read or write failure.

Parameters

TBool aValue

True if user is to be notified of read or write failures, false for no notification.

[Top]


Read bytes from file


ReadFileSection()

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 file to be accessed.

TInt aPos

The offset, in bytes, from the start of the file from which reading is to start. This value must not be negative, otherwise the function raises a FSCLIENT 19 panic.

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. This value must not be greater than the maximum length of the target descriptor, otherwise the function raises an FSCLIENT 26 panic.

Return value

TInt

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

[Top]


Password security support


LockDrive()

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

Support

Supported from 6.0

Description

Locks the card in the specified drive.

The function locks an unlocked card and sets the password. An existing password can be changed.

The new password can be added to the 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& aOld

The existing password, if the card has an existing password. If the card does not have an existing password, then this must be a zero length descriptor.

const TMediaPassword& aNew

The new password.

TBool aStr

ETrue if the new password is to be added to the controller's password store.EFalse if the new password is not to be added to the controller's password store. If there is an old password in the password store, then this is removed.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes. Specifically, KErrAccessDenied if the card does not have a password and the old password argument has a non-zero length, or the card is already locked.

Notes:


UnlockDrive()

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

Support

Supported from 6.0

Description

Unlocks the card in the specified drive.

The password can be added to the controller's password store so that 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

ETrue, if the password is to be added to the controller's password store. EFalse, if the password is not to be added to the controller's password store.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes. Specifically, KErrAccessDenied, if the password is incorrect; KErrAlreadyExists, if the card has already been unlocked.


ClearPassword()

TInt ClearPassword(TInt aDrv, const TMediaPassword& Pswd);

Support

Supported from 6.0

Description

Clears the password from the card in the specified drive.

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

Parameters

TInt aDrv

The drive.

const TMediaPassword& Pswd

The current password which is required to perform this operation.

Return value

TInt

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

[Top]


File system debugging support


ControlIo()

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

Support

Supported from 6.0

Description

A general purpose interface to aid debugging and verification of a file system. It provides a mechanism for passing information to and from a file system and is file system specific.

Note that the function is only supported in debug builds.

Parameters

TInt aDrv

A drive.

TInt aCommand

A command; the meaning is dependent on the file system.

TAny* aParam1

First parameter; the meaning is dependent on the file system.

TAny* aParam2

Second parameter; the meaning is dependent on the file system.

Return value

TInt

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


DebugNotify()

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

Support

Supported from 6.0

Description

A general purpose function to aid debugging and verification of a file system. It provides a mechanism for requesting notification of file system events. The set of events is specific to the file system.

Note that the function is only supported in debug builds.

Parameters

TInt aDrv

Events on this drive trigger notification.

TUint aNotifyType

Defines the set of event types which may be notified. The bits defining the event types must be one of the bits defined by the bitmask:KDebugNotifyMask defined in f32file.h

TRequestStatus& aStat

The request status.KErrNone on completion, otherwise another of the system-wide error codes.

[Top]


Free disk space notification


NotifyDiskSpace()

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

Support

Supported from 6.1

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:

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 enumerators 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 the NotifyDiskSpaceCancel() functions; KErrArgument, if the threshold value is outside its limits.

See also:


NotifyDiskSpaceCancel()

void NotifyDiskSpaceCancel(TRequestStatus& aStat);

Support

Supported from 6.1

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

void NotifyDiskSpaceCancel();

Support

Supported from 6.1

Description

Cancels all outstanding requests for free disk space notification.

Outstanding requests complete with KErrCancel.