File -management with CFileMan

Overview

The CFileMan class -provides file management functionality, but unlike the corresponding functionality -provided by class RFs, CFileMan can operate -on files and directories located throughout a directory hierarchy.

CFileMan lets -you:

copy files
move files
delete files
rename files
delete directories and -their contained files and sub-directories
set and clear file attributes.

The functions provided by the class accept the use of wildcards, -and means that some operations may take time to complete. The class, however, -provides both synchronous and asynchronous variants.

All of the file -manipulation functions except Rename() can 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.

Using CFileMan

Typically, -a CFileMan operation can result in a number of file/directory -manipulation operations, especially if wild cards are used. Some operations, -such as copying files, can take a (relatively) long time, especially if such -files are large.

Symbian platform provides a file notification observer -interface that you can implement to provide notification of events resulting -from CFileMan operations. The interface is defined by the MFileManObserver class, -and you provide an implementation for the functions:

MFileManObserver::NotifyFileManStarted()
MFileManObserver::NotifyFileManOperation()
MFileManObserver::NotifyFileManEnded().

Symbian platform calls the notification functions before or after -each file or directory entry has been processed, or during a file copy or -move operation. You can use the notification to provide information about -the state of the operation, such as error codes, the names of the target and -destination files, and the number of bytes transferred during a copy operation. -This information is available to your implementation by calling the public -functions in CFileMan and its base class CFileBase:

CFileBase::GetLastError()
CFileBase::GetMoreInfoAboutError()
CFileMan::CurrentAction()
CFileMan::GetCurrentTarget()
CFileMan::GetCurrentSource()
CFileMan::BytesTransferredByCopyStep()

You can also use the notification function to cancel, retry or continue -processing a file or directory, or to abort the whole operation, by returning -a suitable MFileManObserver::TControl value.

This -mechanism provides a way for an application to provide feedback, or to give -control over such operations to an end-user through its user interface.

Example code (1)

The following example code shows how you -might use this. It is not a complete example, but it gives you an idea of -what's possible. The example attempts to copy all files from directory C:\path1 to c:\path2 synchronously.

You would need to elaborate on this to make it part of a real application, -and you would probably need the use of active objects, especially if using -the asynchronous versions of the CFileMan functions.

... - _LIT(KSourcePath,"C:\\path1\\*.*"); - _LIT(KDestinationPath,"C:\\path2"); - - // Connect session - RFs fsSession; - User::LeaveIfError(fsSession.Connect()); - - // Create file management object - CFileMan* fileMan = CFileMan::NewL(fsSession); - CleanupStack::PushL(fileMan); - - // Create file management notification object and set to observe - TFileCopyProgressMonitor fileCopyProgressMonitor(*fileMan); - fileMan->SetObserver(&fileCopyProgressMonitor); - - // Do copy (here synchronously) - fileMan->Copy(KSourcePath,KDestinationPath); - - // Clean up - CleanupStack::PopAndDestroy(); - - // close file server session - fsSession.Close(); - ... - class TFileCopyProgressMonitor : public MFileManObserver - { -public : - TFileCopyProgressMonitor(CFileMan& aFileMan); -public : // implement the interface - TControl NotifyFileManStarted(); - TControl NotifyFileManOperation(); - TControl NotifyFileManEnded(); -public : - CFileMan& iFileMan; - } - TFileCopyProgressMonitor::TFileCopyProgressMonitor(CFileMan& aFileMan) - :iFileMan(aFileMan) - { - } - -// Called when a copy operation started -MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManStarted() - { - TFileName& aFile - - // Get name of file we are copying. - // you might want to do something with this, such as display in a UI, - // or save in a data member of this object for later use. - iFileMan.GetCurrentSource(aFile); - - // Allow the operation to continue. - return EContinue; - } - -// Called while a copy operation is in progress -MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManOperation() - { - TInt bytesTransferred; - - // number of bytes copied so far for the file. - bytesbytesTransferred = iFileMan.BytesTransferredByCopyStep(); - - // Allow the operation to continue. - // You would choose to do something different; for example, you could - // return ECancel to cancel the operation if you had a reason to do so, - return EContinue; - } - -// Called when a copy operation is complete -MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManEnded() - { - TInt lasterror; - - // Allow operations to continue if all is well. - lasterror = iFileMan.GetLastError(); - if (lasterror == KErrNone) - { - return EContinue; - } - - // Operation has not completed properly, so you might want to get - // more information, and proceed accordingly. - TFileManError filemanerror; - - filemanerror = iFileMan.GetMoreInfoAboutError(); - if (filemanerror==ESrcOpenFailed) - { - ... - return EAbort; - } - - if (filemanerror==ETrgOpenFailed) - { - ... - return EAbort; - } - - ... // you might want to check for other conditions etc. - } -

Example -code (1)

This code fragment shows a use of the CFileMan::Attribs() functions.

_LIT(KDirText,"\\TopDir\\"); -... -fileMan.Attribs(KDirText,KEntryAttHidden|KEntryAttReadOnly, - KEntryAttArchive,TTime(0),CFileMan::ERecurse); -...

This sets the hidden and read-only attributes, and clears -the archive attribute for all files located in the hierarchy below \TopDir\. -The time of their last modification will be unchanged.

Notes

If you use CFileMan::Move(), -be aware that the behaviour of this 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 moves both the last directory -level and its content, but note that you also need to specify CFileMan::ERecurse in -the switches passed to the function.
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 you use CFileMan::Copy(), -the behaviour of this function does not depend on the presence or absence -of a trailing backslash ("\") character on the end of the source path. This -pattern of behaviour is in contrast to that of CFileMan::Move(). -You can only copy the content of the source path. You cannot request that -the last directory level plus its content be copied to the target path, by -adding a trailing backslash ("\") character onto the end of the source path. -This means that both of the following copy operations produce identical results:
CFileMan fm; -... -fm->Copy(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse); -fm->Copy(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);
It is possible to pass KNullDesC, -the null (or empty) descriptor, to the CFileMan::Delete() functions -as the path name. Although you might expect these functions to treat this -as a null request, i.e. to delete nothing, they interpret the null descriptor -as the string \*.*.

+ + + + + +File +management with CFileManThis topic describes the overview, how to use cFileman and few +important points about file management. +

Overview

The CFileMan class +provides file management functionality, but unlike the corresponding functionality +provided by class RFs, CFileMan can operate +on files and directories located throughout a directory hierarchy.

CFileMan lets +you:

copy files
move files
delete files
rename files
delete directories and +their contained files and sub-directories
set and clear file attributes.

The functions provided by the class accept the use of wildcards, +and means that some operations may take time to complete. The class, however, +provides both synchronous and asynchronous variants.

All of the file +manipulation functions except Rename() can 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.

Using CFileMan

Typically, +a CFileMan operation can result in a number of file/directory +manipulation operations, especially if wild cards are used. Some operations, +such as copying files, can take a (relatively) long time, especially if such +files are large.

Symbian platform provides a file notification observer +interface that you can implement to provide notification of events resulting +from CFileMan operations. The interface is defined by the MFileManObserver class, +and you provide an implementation for the functions:

MFileManObserver::NotifyFileManStarted()
MFileManObserver::NotifyFileManOperation()
MFileManObserver::NotifyFileManEnded().

Symbian platform calls the notification functions before or after +each file or directory entry has been processed, or during a file copy or +move operation. You can use the notification to provide information about +the state of the operation, such as error codes, the names of the target and +destination files, and the number of bytes transferred during a copy operation. +This information is available to your implementation by calling the public +functions in CFileMan and its base class CFileBase:

CFileBase::GetLastError()
CFileBase::GetMoreInfoAboutError()
CFileMan::CurrentAction()
CFileMan::GetCurrentTarget()
CFileMan::GetCurrentSource()
CFileMan::BytesTransferredByCopyStep()

You can also use the notification function to cancel, retry or continue +processing a file or directory, or to abort the whole operation, by returning +a suitable MFileManObserver::TControl value.

This +mechanism provides a way for an application to provide feedback, or to give +control over such operations to an end-user through its user interface.

Example code (1)

The following example code shows how you +might use this. It is not a complete example, but it gives you an idea of +what's possible. The example attempts to copy all files from directory C:\path1 to c:\path2 synchronously.

You would need to elaborate on this to make it part of a real application, +and you would probably need the use of active objects, especially if using +the asynchronous versions of the CFileMan functions.

... + _LIT(KSourcePath,"C:\\path1\\*.*"); + _LIT(KDestinationPath,"C:\\path2"); + + // Connect session + RFs fsSession; + User::LeaveIfError(fsSession.Connect()); + + // Create file management object + CFileMan* fileMan = CFileMan::NewL(fsSession); + CleanupStack::PushL(fileMan); + + // Create file management notification object and set to observe + TFileCopyProgressMonitor fileCopyProgressMonitor(*fileMan); + fileMan->SetObserver(&fileCopyProgressMonitor); + + // Do copy (here synchronously) + fileMan->Copy(KSourcePath,KDestinationPath); + + // Clean up + CleanupStack::PopAndDestroy(); + + // close file server session + fsSession.Close(); + ... + class TFileCopyProgressMonitor : public MFileManObserver + { +public : + TFileCopyProgressMonitor(CFileMan& aFileMan); +public : // implement the interface + TControl NotifyFileManStarted(); + TControl NotifyFileManOperation(); + TControl NotifyFileManEnded(); +public : + CFileMan& iFileMan; + } + TFileCopyProgressMonitor::TFileCopyProgressMonitor(CFileMan& aFileMan) + :iFileMan(aFileMan) + { + } + +// Called when a copy operation started +MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManStarted() + { + TFileName& aFile + + // Get name of file we are copying. + // you might want to do something with this, such as display in a UI, + // or save in a data member of this object for later use. + iFileMan.GetCurrentSource(aFile); + + // Allow the operation to continue. + return EContinue; + } + +// Called while a copy operation is in progress +MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManOperation() + { + TInt bytesTransferred; + + // number of bytes copied so far for the file. + bytesbytesTransferred = iFileMan.BytesTransferredByCopyStep(); + + // Allow the operation to continue. + // You would choose to do something different; for example, you could + // return ECancel to cancel the operation if you had a reason to do so, + return EContinue; + } + +// Called when a copy operation is complete +MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManEnded() + { + TInt lasterror; + + // Allow operations to continue if all is well. + lasterror = iFileMan.GetLastError(); + if (lasterror == KErrNone) + { + return EContinue; + } + + // Operation has not completed properly, so you might want to get + // more information, and proceed accordingly. + TFileManError filemanerror; + + filemanerror = iFileMan.GetMoreInfoAboutError(); + if (filemanerror==ESrcOpenFailed) + { + ... + return EAbort; + } + + if (filemanerror==ETrgOpenFailed) + { + ... + return EAbort; + } + + ... // you might want to check for other conditions etc. + } +

Example +code (1)

This code fragment shows a use of the CFileMan::Attribs() functions.

_LIT(KDirText,"\\TopDir\\"); +... +fileMan.Attribs(KDirText,KEntryAttHidden|KEntryAttReadOnly, + KEntryAttArchive,TTime(0),CFileMan::ERecurse); +...

This sets the hidden and read-only attributes, and clears +the archive attribute for all files located in the hierarchy below \TopDir\. +The time of their last modification will be unchanged.

Notes

If you use CFileMan::Move(), +be aware that the behaviour of this 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 moves both the last directory +level and its content, but note that you also need to specify CFileMan::ERecurse in +the switches passed to the function.
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 you use CFileMan::Copy(), +the behaviour of this function does not depend on the presence or absence +of a trailing backslash ("\") character on the end of the source path. This +pattern of behaviour is in contrast to that of CFileMan::Move(). +You can only copy the content of the source path. You cannot request that +the last directory level plus its content be copied to the target path, by +adding a trailing backslash ("\") character onto the end of the source path. +This means that both of the following copy operations produce identical results:
CFileMan fm; +... +fm->Copy(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse); +fm->Copy(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);
It is possible to pass KNullDesC, +the null (or empty) descriptor, to the CFileMan::Delete() functions +as the path name. Although you might expect these functions to treat this +as a null request, i.e. to delete nothing, they interpret the null descriptor +as the string \*.*.

\ No newline at end of file