Class CFileMan

CFileMan

Support

Supported from 5.0

Description

File management services which accept the use of wildcards — synchronous and asynchronous. It also provides enquiry functions, which, like those provided by the base class CFileBase, may be used by an observer class object to provide the user with information about the progress of the operation.

All of the file management functions provided by this class accept the use of wildcards, and may operate either synchronously or asynchronously. When CFileMan is operating asynchronously, the operation takes place in a separate thread from the calling code.

A file notification observer (an instance of a class deriving from MFileManObserver) may optionally be used by CFileMan when operating synchronously or asynchronously. If provided, the appropriate notification function is called before or after each entry has been processed, or during a file copy or move. This notification can be used to provide information about the state of the operation, such as the number of bytes transferred during a large-scale file copy. It can also be used to allow the user to cancel, retry or continue processing an entry, or to abort the whole operation. If such notification is required, specify an object deriving from MFileManObserver class in the constructor, or call SetObserver(), defined in the base class, CFileBase.

All of the file manipulation functions except Rename() may operate recursively, and all can operate non-recursively. When operating recursively, these functions will act on all matching files located throughout the source directory’s hierarchy. When operating non-recursively, these functions act upon files contained in the single top level source directory only. Recursion is set or unset using the switch parameter to these functions.

This class is not intended for user derivation.

Derivation

CBase Base class for all classes to be instantiated on the heap CFileBase Abstract base class for file management CFileMan File management services which accept the use of wildcards -- synchronous and asynchronous

Defined in CFileMan:
Attribs(), BytesTransferredByCopyStep(), Copy(), CurrentAction(), Delete(), EAttribs, ECopy, EDelete, EMove, ENone, EOverWrite, ERecurse, ERename, ERenameInvalidEntry, ERmDir, GetCurrentSource(), GetCurrentTarget(), Move(), NewL(), Rename(), RmDir(), TAction, TSwitch

Inherited from CBase:
operator new()

Inherited from CFileBase:
AbbreviatedPath(), CurrentEntry(), FullPath(), GetLastError(), GetMoreInfoAboutError(), SetObserver()

See also:

• Using CFileMan

static CFileMan* NewL(RFs& aFs);

Description

Constructs and allocates memory for a new CFileMan object.

Parameters

RFs& aFs File server session

Return value

CFileMan* Newly created CFileMan object.

Leave codes

A leave may occur if there is insufficient memory available

static CFileMan* NewL(RFs& aFs,MFileManObserver* anObserver);

Description

Constructs and allocates memory for a new CFileMan object with an observer.

Parameters

RFs& aFs File server session MFileManObserver* anObserver File management observer

Return value

CFileMan* Newly created CFileMan object.

TAction CurrentAction();

Description

Gets the action which CFileMan is currently carrying out.

Return value

TAction The action which CFileMan is carrying out.

void GetCurrentTarget(TFileName& aFile);

Description

Gets the name of the target file for the CFileMan operation currently being carried out. This function is relevant when copying, moving or renaming files.

Parameters

TFileName& aFile The full path and filename of the target file for current CFileMan operation.

void GetCurrentSource(TFileName& aFile);

Description

Gets the name of the source file or directory for the CFileMan operation currently being carried out. The source is the file or directory which is being copied, deleted etc.

Parameters

TFileName& aFile The full path and filename of the source file for current CFileMan operation.

TInt BytesTransferredByCopyStep();

Description

Gets the number of bytes transferred during a copy or move operation. Large files are copied and moved in stages. After each portion of the source file has been copied to the target, the number of bytes transferred is updated. This function may be called from MFileManObserver::NotifyFileManOperation() and may be used to support the increment of progress bars.

Return value

TInt The number of bytes transferred

TInt Attribs(const TDesC& aName,TUint aSetMask,TUint aClearMask,const TTime& aTime,TUint aSwitch=0);

Description

Sets or clears attributes for one or more files using two bitmasks — synchronous overload. The first bitmask specifies the attributes to set. The second specifies the attributes to clear. The date and time of the files' last modification may also be changed.

The function may operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified inaName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aNamewill be affected.

Notes:

• A panic occurs if any attribute is specified in both bitmasks.

• Attempting to change the attributes for an open file will result in an error for that file, as retrieved by CFileBase::GetLastError().

• An attempt to set or clear the KEntryAttDir or KEntryAttVolume attribute for a file or directory will have no effect.

Parameters

const TDesC& aName Path indicating the file(s) whose attributes are to be changed. Any path components which are not specified here will be taken from the session path. Use wildcards to specify more than one file. TUint aSetMask Bitmask indicating the attributes to be set. TUint aClearMask Bitmask indicating the attributes to be cleared. For more information seeKEntryAttNormal and the other file/directory attributes. const TTime& aTime On return, contains the new date and time that the files were modified. TUint aSwitch=0 Specify zero for no recursion, CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively.

Return value

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

See also:

• Using CFileMan

TInt Attribs(const TDesC& aName,TUint aSetMask,TUint aClearMask,const TTime& aTime,TUint aSwitch,TRequestStatus& aStatus);

Description

Sets or clears attributes for one or more files using two bitmasks — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& aName Path indicating the file(s) whose attributes are to be changed. Any path components which are not specified here will be taken from the session path. Use wildcards to specify more than one file. TUint aSetMask Bitmask indicating the attributes to be set. TUint aClearMask Bitmask indicating the attributes to be cleared. For more information seeKEntryAttNormal and the other file/directory attributes const TTime& aTime On return, contains the new date and time that the files were modified. TUint aSwitch Specify ERecurse for recursion, zero for no recursion. TRequestStatus& aStatus A request status object. On return, indicates how the request completed.KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

See also:

• Using CFileMan

TInt Copy(const TDesC& anOld,const TDesC& aNew,TUint aSwitch=EOverWrite);

Description

Copies one or more files — synchronous overload.

Optionally, this function may be set to overwrite any files with the same name which exist in the target directory. If the flag is set for no overwriting, any files with the same name will not be overwritten, and an error (KErrAlreadyExists) will be returned for that file. Error codes may be retrieved using CFileBase::GetLastError().

If recursive operation is set, all intermediate directories will be created, including any directories in the path specified by aNewwhich do not already exist.

If recursive operation is not set, only the matching files located in the single directory specified in anOld are copied. No intermediate directories will be created — if any directories in the destination path do not exist, no files will be copied, and this function returns KErrPathNotFound.

Notes:

• Files can be copied across drives.

• Open files can be copied if they have been opened using theEFileShareReadersOnly file share mode.

• Read-only, hidden and system files can be copied and the source file's attributes are preserved in the target file.

Parameters

const TDesC& anOld Path indicating the file(s) to be copied. Any path components which are not specified here will be taken from the session path. const TDesC& aNew Path indicating the directory into which the file(s) are to be copied. TUint aSwitch=EOverWrite Specify zero for no overwriting and no recursion.CFileMan::EOverWrite to overwrite files with the same name.CFileMan::ERecurse for recursion. By default, synchronous variant of this function operates non-recursively and with overwriting.

Return value

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

TInt Copy(const TDesC& anOld,const TDesC& aNew,TUint Switch,TRequestStatus& aStatus);

Description

Copies one or more files — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& anOld Path indicating the file(s) to be copied. Any path components which are not specified here will be taken from the session path. const TDesC& aNew Path indicating the directory into which the file(s) are to be copied. TUint aSwitch Specify zero for no overwriting and no recursion.CFileMan::EOverWrite to overwrite files with the same name.CFileMan::ERecurse for recursion. By default, synchronous variant of this function operates non-recursively and with overwriting. TRequestStatus& aStatus Request status object — on return, indicates how the request completed. KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

TInt Delete(const TDesC& aName,TUint aSwitch=0);

Description

Deletes one or more files — synchronous overload.

This function may operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified inaName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aNamewill be deleted.

Note:

• Read-only and open files may not be deleted. Attempting to do so will return an error for that file. Error codes may be retrieved usingCFileBase::GetLastError().

Parameters

const TDesC& aName Path indicating the file(s) to be deleted. May either be a full path, or relative to the session path. Use wildcards to specify more than one file. TUint aSwitch=0 Specify ERecurse for recursion, zero for no recursion. By default, the synchronous variant of this function operates non-recursively.

Return value

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

TInt Delete(const TDesC& aName,TUint aSwitch,TRequestStatus& aStatus);

Description

Deletes one or more files — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& aName Path indicating the file(s) to be deleted. May either be a full path, or relative to the session path. Use wildcards to specify more than one file. TUint aSwitch Specify ERecurse for recursion, zero for no recursion. By default, the synchronous variant of this function operates non-recursively. TRequestStatus& aStatus Request status object — on return, indicates how the request completed. KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

TInt Move(const TDesC& anOld,const TDesC& aNew,TUint aSwitch=EOverWrite);

Description

Moves one or more files — synchronous overload.

Optionally, this function may be set to overwrite any files with the same name which exist in the target directory. If the flag is set for no overwriting, any files with the same name will not be overwritten, and an error (KErrAlreadyExists) returned for that file. Error codes may be retrieved using CFileBase::GetLastError(). By default, when the function is operating synchronously, files are overwritten.

When this function is operating recursively, all intermediate directories will be created, including all directories in the destination path specified byaNew which do not already exist.

If recursive operation is not set, only the matching files located in the single directory specified in anOld are moved. No intermediate directories will be created — if any directories in the destination path do not exist, no files will be moved, and this function will return KErrPathNotFound.

Notes:

• Read-only, hidden and system files can be moved and the source file's attributes are preserved in the target file, but open files cannot be moved. Attempting to move an open file will return an error for that file, as retrieved by CFileBase::GetLastError().

• Files may be moved across drives.

Parameters

const TDesC& anOld Path indicating the files to be moved. May be either a full path, or relative to the session path. const TDesC& aNew Path indicating the directory into which the file(s) are to be moved. TUint aSwitch=EOverWrite Specify zero for no overwriting and no recursion.CFileMan::EOverWrite to overwrite files with the same name.CFileMan::ERecurse for recursion. By default, synchronous variant of function operates non-recursively and with overwriting.

Return value

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

TInt Move(const TDesC& anOld,const TDesC& aNew,TUint aSwitch, TRequestStatus& aStatus);

Description

Moves one or more files — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& anOld Path indicating the files to be moved. May be either a full path, or relative to the session path. const TDesC& aNew Path indicating the directory into which the file(s) are to be moved. TUint aSwitch Specify zero for no overwriting and no recursion.CFileMan::EOverWrite to overwrite files with the same name.CFileMan::ERecurse for recursion. By default, synchronous variant of function operates non-recursively and with overwriting. TRequestStatus& aStatus Request status object — on return, indicates how the request completed. KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

TInt Rename(const TDesC& anOld,const TDesC& aNew,TUint aSwitch=EOverWrite);

Description

Renames one or more files — synchronous overload. It can also be used to move files by specifying different destination and source directories. Note that the destination and source directories must be on the same drive.

If this function is being used to move files, an option is provided to allow the user to overwrite any files with the same name which may exist in the target directory. If the flag is set for no overwriting, any files with the same name will not be overwritten, and an error (KErrAlreadyExists) will be returned for that file, as retrieved by CFileBase::GetLastError().

This function can only operate non-recursively, so that only the matching files located in the single directory specified by anOld may be renamed.

Note:

• Read-only, system and hidden files may be renamed, and the source file's attributes are preserved in the target file, but open files cannot be renamed. Attempting to rename an open file will return an error for that file, as retrieved by CFileBase::GetLastError().

Parameters

const TDesC& anOld Path specifying the file(s) to be renamed. const TDesC& aNew Path specifying the new name for the files and/or the new directory. Any directories specified in this path which do not exist will be created. TUint aSwitch=EOverWrite Specify zero for no overwriting. CFileMan::EOverWrite to overwrite files with the same name. This function cannot operate recursively.

Return value

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

TInt Rename(const TDesC& anOld,const TDesC& aNew,TUint aSwitch, TRequestStatus& aStatus);

Description

Renames one or more files — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& anOld Path specifying the file(s) to be renamed. const TDesC& aNew Path specifying the new name for the files and/or the new directory. Any directories specified in this path which do not exist will be created. TUint aSwitch Specify zero for no overwriting. CFileMan::EOverWrite to overwrite files with the same name. This function cannot operate recursively. TRequestStatus& aStatus Request status object — on return, indicates how the request completed. KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

TInt RmDir(const TDesC& aDirName);

Description

Deletes a directory and all files and directories contained in the directory structure below it — synchronous overload.

This functions cannot be used non-recursively. For a non-recursive directory deletion, use RFs::RmDir().

Note:

• All files in the directory hierarchy to be deleted must be closed and none may have the read-only attribute. Otherwise, not all of the hierarchy will be deleted, and this function will return KErrInUse.

Parameters

const TDesC& aDirName Path specifying the directory to be deleted.

Return value

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

TInt RmDir(const TDesC& aDirName,TRequestStatus& aStatus);

Description

Deletes a directory and all files and directories contained in the directory structure below it — asynchronous overload.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

Parameters

const TDesC& aDirName Path specifying the directory to be deleted. TRequestStatus& aStatus If specified, request status object. On return, indicates how the request completed. KErrNone if successful, otherwise another of the system-wide error codes.

Return value

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

TAction

Description

Identify CFileMan tasks. This enumeration is used byCurrentAction() to identify which task currently being carried out.

ENone Inactive EAttribs Setting attributes ECopy Copying files EDelete Deleting files EMove Moving files ERename Renaming files ERmDir Deleting a directory and all contents ERenameInvalidEntry Renaming component to VFAT short name (guaranteed to be unique)

TSwitch

Description

Overwriting and recursion switch. Used in CFileMan functions to set whether operations are applied to the specified directory and all directories below it, or the specified directory only.

EOverWrite Any files in the destination directory which have the same name as the source files in a rename, move or copy operation, will be overwritten ERecurse Recursive operation