RFs Class Reference

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.

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.

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.

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.

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.

See also: TDriveNumber

Cancels a specific outstanding request for free disk space notification.

The outstanding request completes with KErrCancel.

Cancels all outstanding requests for free disk space notification.

Outstanding requests complete with KErrCancel.

Controls file system dismounting on the specified drive, the way of control depends on the parameter TNotifyDismountMode.

This API allows interested parties to: 1. Subscribe for notification of file system dismounting events. This allows subscribers to commit their data to the media prior to the file system being dismounted. See TNotifyDismountMode::EFsDismountRegisterClient

2. Make a graceful attempt to dismount the file system by notifying the subscribers about a pending file system dismount and waiting until all subscribers have finished processing the notification and have signaled that they are ready. If all clients don't respond in a reasonable time, the dismount request may be cancelled, followed by a forced dismount. If some client does not subscribe for dismounting notification and keeps handles opened, then after the file system dismounting all these handles will become invalid, any subsequent attempts to use them will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). See TNotifyDismountMode::EFsDismountNotifyClients

3. Dismount the file system by force even if there are opened handles (files, directories) on the volume being dismounted. Any clients that kept handles opened, after forced file system dismounting will have them invalidated. And any further attempts to use these handles will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). See TNotifyDismountMode::EFsDismountForceDismount

If there are clamped files on the volume, the file system dismounting will not happen until these files are unclamped.

The use case scenario: A 'Master' application that wants to dismount the file system on some drive 'aDrive' 'Client1' and 'Client2' applications interested in file system dismount event notifications, because they need to commit their data before the file system is dismounted.

1. 'Client1' and 'Client2' subscribe to the FS dismount notification using EFsDismountRegisterClient and start waiting on the request status objects. 2. 'Master' decides to dismount the file system on the drive 'aDrive'. 2.1 Graceful attempt: 'Master' calls RFs::NotifyDismount() with EFsDismountNotifyClients and starts waiting on 'aStat' for some time until all 'Client1' and 'Client2' respond or timeout occurs.

3. 'Client1' and 'Client2' have their 'aStat' completed as the result of the 'Master' calling EFsDismountNotifyClients. 3.1 'Client1' and 'Client2' flush data and close file handles. 3.2 as soon as 'Client1' and 'Client2' decide that they are ready for the pending FS dismount, they signal the 'Master' that they are ready by calling RFs::AllowDismount()

4. As soon as _all_ subscribed clients ('Client1' and 'Client2') have called RFs::AllowDismount(), the file system on drive 'aDrive' is dismounted and 'Master' has 'aStat' completed.

If, for example, 'Client2' hasn't responded in a reasonable time by calling RFs::AllowDismount(), the 'Master' can cancel the pending 'aStat' and dismount the file system by force by calling this API with EFsDismountForceDismount. In this case all subsequent attempts by 'Client2' to use its opened handles will result in KErrDismounted; these handles should be closed.

Cancels the oustanding dismount notifier, completing with KErrCancel.

See also: RFs::NotifyDismount

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

See also: RFs::NotifyDismount

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.

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.

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

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.

Queries specific information on volumes by commands. Available commands is defined by TQueryVolumeInfoExtCmd.

See also: TQueryVolumeInfoExtCmd TVolumeIOParamInfo

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.

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.

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

Forces a remount of the specified drive.

Removes the specified extension.

Removes the specified file system.

Removes the specified plugin.

Removes the specified extension.

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.

See also: CFileMan

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.

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.

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.

Ends resource count checking. Typically, this function is called immediately before closing a session with the file server.

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.

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"));

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.

See also: CFileMan

Checks the integrity of the File System mounted on the specified drive and attempts to correct some known File System errors. The behaviour of this API and return codes are File System specific, dependent on how the File System implements its ScanDrive functionality.

ScanDrive will not run on drives that have files or directories opened.

ScanDrive is intended to be run ONLY on "Rugged-FAT" file system which is applicable to internal non-removable drives. Internal RAM drives are not supported.

The "Rugged FAT" file system is designed in such a way that only a limited number of known cases of corruption can be caused by sudden power loss. All of these known cases can be corrected by ScanDrive. Hence, running ScanDrive on "Rugged FAT" file system will result in: KErrNone If there was no File System corruption or ScanDrive has successfully repaired the File System. KErrCorrupt If ScanDrive has found a File System error that it cannot repair. Other system-wide error codes, see above.

Running ScanDrive on removable media or media that has FAT file system not in "Rugged FAT" mode is not practical, because ScanDrive is not designed for this. Therefore, do not treat ScanDrive on removable media as a generic "disk repair utility".

Issues a synchronous request to the server with the specified function number and arguments.

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.

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.

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.

See also: RFs::SetEntry

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.