|
||
class CFileMan : public CFileBase;
Offers 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.
CBase
- Base class for all classes to be instantiated on the heap
CFileBase
- Abstract base class for file management
CFileMan
- Offers file management services which accept the use of wildcards; synchronous and asynchronous
Defined in CFileMan
:
Attribs()
Sets or clears attributes for one or more files using two bitmasksAttribs()
Sets or clears attributes for one or more files using two bitmasksBytesTransferredByCopyStep()
Gets the number of bytes transferred during a copy or move operationCompleteOperationL()
Called from RunL to perform tidy up after an operationCopy()
Copies one or more filesCopy()
Copies one or more filesCopy()
Copies from an open file handle to a destination file nameCopy()
Copies from an open file handle to a destination file nameCurrentAction()
Gets the action which CFileMan is currently carrying outDelete()
Deletes one or more filesDelete()
Deletes one or more filesDoOperationL()
Called from RunL to perform the requested operationEAttribs
Setting attributesECopy
Copying filesECopyFromHandle
Copying file from open file handleEDelete
Deleting filesEMove
Moving filesENone
InactiveEOverWrite
Any files in the destination directory that have the same name as the source files in a rename, move or copy operation, will
be overwrittenERecurse
Recursive operationERename
Renaming filesERenameInvalidEntry
Renaming component to VFAT short name (guaranteed to be unique)ERmDir
Deleting a directory and all contentsGetCurrentSource()
Gets the name of the source file or directory for the CFileMan operation currently being carried outGetCurrentTarget()
Gets the name of the target file for the CFileMan operation currently being carried outMove()
Moves one or more filesMove()
Moves one or more filesNewL()
Constructs and allocates memory for a new CFileMan objectNewL()
Constructs and allocates memory for a new CFileMan object with an observerRename()
Renames one or more files, or a directoryRename()
Renames one or more filesRmDir()
Deletes a directory and all files and directories contained in the directory structure below itRmDir()
Deletes a directory and all files and directories contained in the directory structure below itTAction
An enumeration that identifies CFileMan tasksTSwitch
Overwriting and recursion switchInherited from CBase
:
Extension_()
Extension functionoperator new()
Initialises the object to binary zeroesInherited from CFileBase
:
AbbreviatedPath()
Gets the abbreviated path of the file or directory currently being processedConstructL()
Second phase constructorCurrentEntry()
Gets the entry currently being processedFullPath()
Gets the full path of the file or directory currently being processedGetLastError()
Gets the latest error code returned during a CFileMan operationGetMoreInfoAboutError()
Gets additional information about the latest error returned during a CFileMan operationRunInSeparateThreadL()
Creates a separate thread to run the commandRunL()
Executes a commandSetObserver()
Sets the observeriCurrentEntry
iDirList
iErrorInfo
iFManThread
iFs
iFsOld
iLastError
iMatchEntry
iNumberOfFilesProcessed
iObserver
iScanner
iSessionPath
iSrcFile
iStatus
iSwitches
iSynchronizer
MFileManObserver
Provides notification of the progress of synchronous or asynchronous file management operationsstatic IMPORT_C CFileMan *NewL(RFs &aFs);
Constructs and allocates memory for a new CFileMan object.
|
|
static IMPORT_C CFileMan *NewL(RFs &aFs, MFileManObserver *anObserver);
Constructs and allocates memory for a new CFileMan object with an observer.
|
|
IMPORT_C TAction CurrentAction();
Gets the action which CFileMan is currently carrying out.
|
IMPORT_C void GetCurrentTarget(TFileName &aFile);
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.
|
IMPORT_C void GetCurrentSource(TFileName &aFile);
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, moved or deleted.
|
IMPORT_C TInt BytesTransferredByCopyStep();
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.
|
Capability: | Dependent | If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required. |
IMPORT_C TInt Attribs(const TDesC &aName, TUint aSetMask, TUint aClearMask, const TTime &aTime, TUint aSwitch=0);
Sets or clears attributes for one or more files using two bitmasks
This is a synchronous function.
The first bitmask specifies the attributes to be set. The second specifies the attributes to be cleared. The date and time of the files' last modification can also be changed.
The function can operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified in aName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aName will be affected.
Notes:
1. A panic is raised if any attribute is specified in both bitmasks.
2. Attempting to change the attributes for an open file results in an error for that file, as retrieved by CFileBase::GetLastError()
.
3. An attempt to set or clear the KEntryAttDir or KEntryAttVolume attribute for a file or directory will have no effect.
|
|
Capability: | Dependent | If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required. |
IMPORT_C TInt Attribs(const TDesC &aName, TUint aSetMask, TUint aClearMask, const TTime &aTime, TUint aSwitch, TRequestStatus
&aStatus);
Sets or clears attributes for one or more files using two bitmasks.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
Capability: | AllFiles | |
Capability: | Dependent | If the path for anOld begins with /Sys then Tcb capability is required. If the path for anOld begins with /Resource then Tcb capability is required |
IMPORT_C TInt Copy(const TDesC &anOld, const TDesC &aNew, TUint aSwitch=EOverWrite);
Copies one or more files.
This is a synchronous function.
NB the following applies to files greater than or equal to 2GBytes in size (2,147,483,648 bytes) : Only files smaller than
2GBytes will be copied; any larger files will be skipped and processing will continue with the next file. If at least one
file is smaller than 2GBytes, then KErrNone will be returned. If all files are greater than or equal to 2GBytes ,then KErrTooBig
will be returned. One way to detect the presence of any large file(s) is to use an observer: calling CFileBase::GetLastError()
from MFileManObserver::NotifyFileManEnded()
will return KErrToBig for any file >= 2GBytes in size.
Optionally, this function can be set to overwrite any files with the same name which exist in the target directory. If the
flag is set for no overwriting, then 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 aNew which 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 will return KErrPathNotFound.
Notes: 1. This function operates on files only, therefore: 1.1 In contrast to the way CFileMan::Move()
and CFileMan::Rename()
behave, the behaviour of the copy operation does not depend on the presence or absence of a trailing backslash ("\") character.
Therefore it is only possible to copy the content of the source path. It is NOT possible by use of a trailing backslash ("\")
character to request that the last directory level plus its content be copied to the target path.
This means that the following two example copy operations will behave identically
CFileMan fm;
...
fm->Copy(_L("C:\SRC\"), _L("C:\TRG\"), CFileMan::ERecurse);
fm->Copy(_L("C:\SRC"), _L("C:\TRG\"), CFileMan::ERecurse);
because they will be interpreted as follows:
fm->Copy(_L("C:\SRC\*"),_L("C:\TRG\"), CFileMan::ERecurse);
1.2 If there is no file to operate on i.e. if source directory is empty, the function will do nothing and return error code KErrNotFound.
2. Files can be copied across drives.
3. Open files can be copied if they have been opened using the EFileShareReadersOnly file share mode.
4. Read-only, hidden and system files can be copied and the source file's attributes are preserved in the target file.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationCapability: | AllFiles | |
Capability: | Dependent | If the path for aNew begins with /Sys then Tcb capability is required. If the path for aNew begins with /Resource then Tcb capability is required |
IMPORT_C TInt Copy(const TDesC &anOld, const TDesC &aNew, TUint aSwitch, TRequestStatus &aStatus);
Copies one or more files.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
Capability: | Dependent | If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required. |
IMPORT_C TInt Delete(const TDesC &aName, TUint aSwitch=0);
Deletes one or more files.
This is a synchronous function.
This function can operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified in aName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aName will be deleted.
Note that 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 using CFileBase::GetLastError()
.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationKNullDesC
Defines an empty or null literal descriptorCapability: | Dependent | If aName is /Sys then Tcb capability is required. If aName begins with /Private and does not match this process' SID then AllFiles capability is required. If aName is /Resource then Tcb capability is required. |
IMPORT_C TInt Delete(const TDesC &aName, TUint aSwitch, TRequestStatus &aStatus);
Deletes one or more files.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
KNullDesC
Defines an empty or null literal descriptorCapability: | AllFiles | |
Capability: | Dependent | If the path in aNew starts with /Sys then capability Tcb is required If the path in aNew starts with /Resource then capability Tcb is required If the path in anOld starts with /Sys then Tcb capability is required. If the path in anOld starts with /Resource then Tcb capability is required. |
IMPORT_C TInt Move(const TDesC &anOld, const TDesC &aNew, TUint aSwitch=EOverWrite);
Moves one or more files.
This is a synchronous function.
Optionally, this function can be set to overwrite any files with the same name which exist in the target directory. If the
flag is set for no overwriting, then 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()
. 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 by aNew 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.
The behaviour of the move operation is sensitive to the presence (or absence) of a trailing backslash ("\") character on the end of the source path:
if there is a trailing backslash ("\") character, then the operation moves the content of the last directory level only.
if there is no trailing backslash ("\") character, then the operation behaves recursively by default and moves both the last directory level and all of its content. Notice that no trailing backslash ("\") implies moving files recursively automatically.
For example, if the directory level "b" contains the files F1,F2 and F3, then:
CFileMan fm;
...
fm->Move(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse);
results in files F1, F2 and F3 being moved from C:\a\b to C:\x\y, leaving the path C:\a\b unchanged, except that it no longer contains the files F1, F2 and F3.
If there is no trailing backslash character, for example:
CFileMan fm;
...
fm->Move(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);
then both the directory level "b" and its contents are moved. This means that there is no longer a directory "b" under C:\a. Instead there is a new directory structure C:\x\y\b and the files F1, F2, and F3 now exist under C:\x\y\b. Also if "b" contains subdirectories, then these are also moved along with "b".
If there is no trailing backslash character and the switch is not set, i.e. 0 is passed as an argument, the operation behaves
the same way as by passing CFileMan::ERecurse
flag.
for example:
CFileMan fm;
...
fm->Move(_L("C:\a\b"), _L("C:\x\y\"), 0);
The example above produces the same output as:
CFileMan fm;
...
fm->Move(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);
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()
.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationCapability: | AllFiles | |
Capability: | Dependent | If the path in aNew starts with /Sys then capability Tcb is required If the path in aNew starts with /Resource then capability Tcb is required If the path in anOld starts with /Sys then Tcb capability is required. If the path in anOld starts with /Resource then Tcb capability is required. |
IMPORT_C TInt Move(const TDesC &anOld, const TDesC &aNew, TUint aSwitch, TRequestStatus &aStatus);
Moves one or more files.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
Capability: | Dependent | If either aName or aNewName is /Sys then Tcb capability is required. If either aName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required. If either aName or aNewName is /Resource then Tcb capability is required. |
IMPORT_C TInt Rename(const TDesC &anOld, const TDesC &aNew, TUint aSwitch=EOverWrite);
Renames one or more files, or a directory
This is a synchronous function.
The function can also be used to move files by specifying different destination and source directories.
Some rules for using CFileMan::Rename()
:
1. General rules:
1.1. Trailing backslash ("\") in either source path (aName) or target path (aNewName) will be interpreted to "\*.*";
For example, following code should behave identically:
CFileMan fm;
...
fm->Rename(_L("C:\SRC\"), _L("C:\TRG\"));
fm->Rename(_L("C:\SRC\*.*"), _L("C:\TRG\"));
fm->Rename(_L("C:\SRC\"), _L("C:\TRG\*.*"));
fm->Rename(_L("C:\SRC\*.*"), _L("C:\TRG\*.*"));
1.2 The behaviour of the rename operation is sensitive to the presence (or absence) of a trailing backslash ("\") character on the end of the target path (aNewName);
For example, under all other constraints (see rules 2. and 3.),
CFileMan fm;
...
fm->Rename(_L("C:\SRC"), _L("C:\TRG\"));
will result in renaming "C:\SRC" to "C:\TRG\SRC", while
CFileMan fm;
...
fm->Rename(_L("C:\SRC"), _L("C:\TRG"));
will result in renaming "C:\SRC" to "C:\TRG".
2. When renaming file(s):
2.1 Wildcards can be used for renaming multiple files;
2.2 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()
.
2.3 It can only operate non-recursively, so that only the matching files located in the single directory specified by anOld may be renamed.
2.4 Trying to rename file(s) to existing directory(ies) will fail;
For example, giving following direcotry structure:
C:\SRC\ITEM01
C:\SRC\ITEM02
C:\TRG\ITEM01\
C:\TRG\ITEM02\
Following code will fail:
CFileMan fm;
...
fm->Rename(_L("C:\SRC\ITEM01"), _L("C:\TRG\ITEM01"));
fm->Rename(_L("C:\SRC\ITEM*"), _L("C:\TRG\ITEM*"));
fm->Rename(_L("C:\SRC\"), _L("C:\TRG\"));
3. When renamnig a directory:
3.1. Only when the trailing backslash ("\") is missing from the source path (aName), will the source directory be renamed, otherwise, see rule 1.1.
For example, following code will result in moving "C:\SRC" directory including all its contents:
CFileMan fm;
...
fm->Rename(_L("C:\SRC"), _L("C:\TRG"));
fm->Rename(_L("C:\SRC"), _L("C:\TRG\"));
fm->Rename(_L("C:\SRC"), _L("C:\TRG\*.*"));
3.2. Wildcards can not be used for moving directories;
3.3. Overwriting is not permitted;
For example, giving directory structure as following:
C:\SRC\FILE.TXT
C:\TRG\
C:\TRG\SRC\
following code will fail:
CFileMan fm;
...
fm->Rename(_L("C:\SRC"), _L("C:\TRG"));
fm->Rename(_L("C:\SRC"), _L("C:\TRG\"));
fm->Rename(_L("C:\SRC"), _L("C:\TRG\*.*"));
4. Notes:
4.1. The target and source directories must be on the same drive.
4.2. 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()
.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationCapability: | Dependent | If either aName or aNewName is /Sys then Tcb capability is required. If either aName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required. If either aName or aNewName is /Resource then Tcb capability is required. |
IMPORT_C TInt Rename(const TDesC &anOld, const TDesC &aNew, TUint aSwitch, TRequestStatus &aStatus);
Renames one or more files.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
Capability: | Dependent | If aDirName starts with /Sys then Tcb capability is required. If aDirName begins with /Private and does not match this process' SID then AllFiles capability is required. If aDirName starts with /Resource then Tcb capability is required. |
IMPORT_C TInt RmDir(const TDesC &aDirName);
Deletes a directory and all files and directories contained in the directory structure below it.
This is a synchronous function.
The function cannot be used non-recursively. For a non-recursive directory deletion, use RFs::RmDir()
.
Note:
1. 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.
|
|
Capability: | Dependent | If aDirName starts with /Sys then Tcb capability is required. If aDirName begins with /Private and does not match this process' SID then AllFiles capability is required. If aDirName starts with /Resource then Tcb capability is required. |
IMPORT_C TInt RmDir(const TDesC &aDirName, TRequestStatus &aStatus);
Deletes a directory and all files and directories contained in the directory structure below it.
Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.
|
|
Capability: | Dependent | If the path for aNew begins with /Sys then Tcb capability is required. If the path for aNew begins with /Private and does not match this process' SID then AllFiles capability is required. If the path for aNew begins with /Resource then Tcb capability is required. |
IMPORT_C TInt Copy(const RFile &anOld, const TDesC &aNew, TUint aSwitches=EOverWrite);
Copies from an open file handle to a destination file name.
This is a synchronous function.
Optionally, this function can be set to overwrite the target file. If the flag is set for no overwriting and the target file
already exists, then the target file will not be overwritten, and an error (KErrAlreadyExists) will be returned. Error codes
may be retrieved using CFileBase::GetLastError()
.
Notes:
The file can be copied across drives.
Read-only, hidden and system files can be copied and the source file's attributes are preserved in the target file.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationCFileMan::Move()
Moves one or more filesCapability: | Dependent | If the path for aNew begins with /Sys then Tcb capability is required. If the path for aNew begins with /Private and does not match this process' SID then AllFiles capability is required. If the path for aNew begins with /Resource then Tcb capability is required. |
IMPORT_C TInt Copy(const RFile &anOld, const TDesC &aNew, TUint aSwitches, TRequestStatus &aStatus);
Copies from an open file handle to a destination file name.
This is an asycnhronous function. Its behaviour is the same as the synchronous overload.
|
|
CFileBase::GetLastError()
Gets the latest error code returned during a CFileMan operationprivate: virtual void CompleteOperationL();
Called from RunL to perform tidy up after an operation.
private: virtual void DoOperationL();
Called from RunL to perform the requested operation.
TAction
An enumeration that identifies CFileMan tasks. This enumeration is used by CurrentAction()
to identify which task currently being carried out.
|
TSwitch
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.
|