![[Index]](../../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../../_stock/btn_next_wt.gif){kind=small}
|
|
| ||
|
|
|||
Location:
f32file.h
class RFs : public RSessionBase;
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.
RHandleBase - A handle to an objectRSessionBase - Client-side handle to a session with a serverRFs - A handle to a file server sessionDefined in RFs:
AddExtension(), AddFileSystem(), AllowDismount(), Att(), CharToDrive(), CheckDisk(), ClearPassword(), Connect(), ControlIo(), ControlIo(), ControlIo(), ControlIo(), CreatePrivatePath(), DebugNotify(), Delete(), DismountExtension(), DismountFileSystem(), Drive(), DriveList(), DriveToChar(), Entry(), ErasePassword(), ExtensionName(), FileSystemName(), FinaliseDrives(), GetDir(), GetDir(), GetDir(), GetDriveName(), GetLongName(), GetMediaSerialNumber(), GetNotifyUser(), GetReserveAccess(), GetShortName(), IsFileInRom(), IsFileOpen(), IsRomAddress(), IsValidDrive(), IsValidName(), IsValidName(), LoaderHeapFunction(), LockDrive(), MkDir(), MkDirAll(), Modified(), MountExtension(), MountFileSystem(), MountFileSystem(), MountFileSystem(), MountFileSystem(), MountFileSystemAndScan(), MountFileSystemAndScan(), NotifyChange(), NotifyChange(), NotifyChangeCancel(), NotifyChangeCancel(), NotifyDiskSpace(), NotifyDiskSpaceCancel(), NotifyDiskSpaceCancel(), NotifyDismount(), NotifyDismountCancel(), NotifyDismountCancel(), Parse(), Parse(), PrivatePath(), ReadFileSection(), RealName(), ReleaseReserveAccess(), RemountDrive(), RemoveExtension(), RemoveFileSystem(), Rename(), Replace(), ReserveDriveSpace(), ResourceCount(), ResourceCountMarkEnd(), ResourceCountMarkStart(), RmDir(), ScanDrive(), SessionPath(), SetAllocFailure(), SetAtt(), SetDebugRegister(), SetDriveName(), SetEntry(), SetErrorCondition(), SetLocalDriveMapping(), SetModified(), SetNotifyUser(), SetSessionPath(), SetSessionToPrivate(), SetStartupConfiguration(), SetSubst(), SetVolumeLabel(), StartupInitComplete(), Subst(), SwapFileSystem(), UnlockDrive(), Version(), Volume()
Inherited from RHandleBase:
Attributes(),
Close(),
Duplicate(),
FullName(),
Handle(),
HandleInfo(),
Name(),
SetHandle(),
SetHandleNC(),
iHandle
Inherited from RSessionBase:
CreateSession(),
EAutoAttach,
EExplicitAttach,
Open(),
Send(),
SendReceive(),
SetReturnedHandle(),
ShareAuto(),
ShareProtected(),
TAttachMode
IMPORT_C TInt Connect(TInt aMessageSlots=KFileServerDefaultMessageSlots);
Connects a client to the file server.
To end the file server session, use Close().
|
|
IMPORT_C TVersion Version() const;
Gets the client side version number.
|
| Capability: | DiskAdmin |
IMPORT_C TInt AddFileSystem(const TDesC &aFileName) const;
Adds a file system to the file server.
After calling this function, use MountFileSystem() to mount the file system on a drive.
|
|
RFs::MountFileSystem| Capability: | DiskAdmin |
IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, TInt aDrive) const;
Mounts a file system on a drive.
The file system must first have been added to the file server, using AddFileSystem().
The operation is asynchronous, i.e other concurrent file server operations can continue.
|
|
RFs::AddFileSystemRFs::FileSystemName| Capability: | DiskAdmin |
IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, TInt aDrive, TBool aIsSync) const;
Mounts a file system on a drive.
The file system must first have been added to the file server, using AddFileSystem().
The operation can be synchronous or asynchronous. Synchronous means that other concurrent file server operations are locked until the mount operation is complete. Asynchronous means that other concurrent file server operations can continue.
|
|
RFs::AddFileSystemRFs::FileSystemName| Capability: | DiskAdmin |
IMPORT_C TInt MountFileSystemAndScan(const TDesC &aFileSystemName, TInt aDrive, TBool &aIsMountSuccess) const;
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 file system will be marked as asynchronous. i.e. all subsequent file server operations on this drive will occur asynchronously;
|
|
RFs::TDriveNumberRFs::AddFileSystemRFs::FileSystemName| Capability: | DiskAdmin |
IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive);
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 operation is asynchronous, i.e other concurrent file server operations can continue.
|
|
RFs::AddFileSystemRFs::FileSystemName| Capability: | DiskAdmin |
IMPORT_C TInt MountFileSystem(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive, TBool aIsSync);
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 operation can be synchronous or asynchronous. Synchronous means that other concurrent file server operations are locked until the mount operation is complete. Asynchronous means that other concurrent file server operations can continue.
|
|
RFs::AddFileSystemRFs::FileSystemName| Interface status: | protoype |
IMPORT_C TInt MountFileSystemAndScan(const TDesC &aFileSystemName, const TDesC &aExtensionName, TInt aDrive, TBool &aIsMountSuccess) const;
|
|
| Capability: | DiskAdmin |
IMPORT_C TInt DismountFileSystem(const TDesC &aFileSystemName, TInt aDrive) const;
Dismounts the file system from the specified drive.
|
|
RFs::FileSystemName| Capability: | DiskAdmin |
IMPORT_C TInt RemoveFileSystem(const TDesC &aFileSystemName) const;
Removes the specified file system.
|
|
IMPORT_C TInt FileSystemName(TDes &aName, TInt aDrive) const;
Gets the name of the file system mounted on the specified drive.
The function can be called before calling DismountFileSystem().
|
|
RFs::DismountFileSystemIMPORT_C TInt AddExtension(const TDesC &aFileName);
Loads the specified extension.
|
|
IMPORT_C TInt MountExtension(const TDesC &aExtensionName, TInt aDrive);
Mounts the the specified extension.
The extension must first have been loaded using AddExtension().
|
|
RFs::ExtensionNameIMPORT_C TInt DismountExtension(const TDesC &aExtensionName, TInt aDrive);
Dismounts the specified extension.
|
|
RFs::ExtensionNameIMPORT_C TInt RemoveExtension(const TDesC &aExtensionName);
Removes the specified extension.
|
|
IMPORT_C TInt ExtensionName(TDes &aExtensionName, TInt aDrive, TInt aPos);
Gets the name of the extension on the specified drive at the specified position in the extension hierarchy.
|
|
IMPORT_C TInt RemountDrive(TInt aDrive, const TDesC8 *aMountInfo=0,TUint aFlags=0);
Forces a remount of the specified drive.
|
|
| Capability: | AllFiles |
IMPORT_C void NotifyChange(TNotifyType aType, TRequestStatus &aStat);
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.
|
| Capability: | AllFiles |
IMPORT_C void NotifyChange(TNotifyType aType, TRequestStatus &aStat, const TDesC &aPathName);
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.
|
| Capability: | AllFiles |
IMPORT_C void NotifyChangeCancel();
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.
| Capability: | AllFiles |
IMPORT_C void NotifyChangeCancel(TRequestStatus &aStat);
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.
|
IMPORT_C void NotifyDiskSpace(TInt64 aThreshold, TInt aDrive, TRequestStatus &aStat);
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.
|
IMPORT_C void NotifyDiskSpaceCancel(TRequestStatus &aStat);
Cancels a specific outstanding request for free disk space notification.
The outstanding request completes with KErrCancel.
|
IMPORT_C void NotifyDiskSpaceCancel();
Cancels all outstanding requests for free disk space notification.
Outstanding requests complete with KErrCancel.
IMPORT_C TInt DriveList(TDriveList &aList) const;
Gets a list of the available 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. The internal RAM always uses drive letter C. 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.
|
|
IMPORT_C TInt Drive(TDriveInfo &anInfo, TInt aDrive=KDefaultDrive) const;
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.
|
|
RFs::VolumeIMPORT_C TInt Volume(TVolumeInfo &aVol, TInt aDrive=KDefaultDrive) const;
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.
|
|
RFs::Drive| Capability: | DiskAdmin |
IMPORT_C TInt SetVolumeLabel(const TDesC &aName, TInt aDrive=KDefaultDrive);
Sets the label for a volume.
|
|
TDriveNumberTVolumeInfo::iNameRFs::VolumeIMPORT_C TInt Subst(TDes &aPath, TInt aDrive=KDefaultDrive) const;
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.
|
|
RFs::SetSubstTDriveInfoRFs::Drive| 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. |
| Capability: | DiskAdmin |
IMPORT_C TInt SetSubst(const TDesC &aPath, TInt aDrive=KDefaultDrive);
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.
|
|
| 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;
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.
|
|
IMPORT_C TInt GetMediaSerialNumber(TMediaSerialNumber &aSerialNum, TInt aDrive);
Gets the serial number of media.
Only local drive is allowed. Substed drive number will return KErrNotSupported.
|
|
TMediaSerialNumberIMPORT_C TInt SessionPath(TDes &aPath) const;
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.
|
|
| 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);
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.
|
|
IMPORT_C TInt Parse(const TDesC &aName, TParse &aParse) const;
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.
|
|
IMPORT_C TInt Parse(const TDesC &aName, const TDesC &aRelated, TParse &aParse) const;
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.
|
|
| 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);
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.
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.
|
|
RFs::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);
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.
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.
|
|
RFs::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 RmDir(const TDesC &aPath);
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 of its contents.
|
|
IMPORT_C TInt GetDir(const TDesC &aName, TUint anEntryAttMask, TUint anEntrySortKey, CDir *&anEntryList) const;
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.
|
|
IMPORT_C TInt GetDir(const TDesC &aName, TUint anEntryAttMask, TUint anEntrySortKey, CDir *&anEntryList, CDir *&aDirList) const;
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.
|
|
IMPORT_C TInt GetDir(const TDesC &aName, const TUidType &anEntryUid, TUint anEntrySortKey, CDir *&aFileList) const;
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.
|