--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-204627D4-3818-5DE7-8969-C335DBA5B153.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-204627D4-3818-5DE7-8969-C335DBA5B153" xml:lang="en"><title>File
+management with CFileMan</title><shortdesc>This topic describes the overview, how to use cFileman and few
+important points about file management.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-BE295C9C-37BC-5CCE-9957-4DD5D0DF0672"><title>Overview</title> <p>The <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref> class
+provides file management functionality, but unlike the corresponding functionality
+provided by class <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref>, <codeph>CFileMan</codeph> can operate
+on files and directories located throughout a directory hierarchy. </p> <p> <codeph>CFileMan</codeph> lets
+you: </p> <ul>
+<li id="GUID-009066F1-2047-5BEF-A3A0-FB4FC341753D"><p>copy files </p> </li>
+<li id="GUID-4777CAC8-8537-5AF6-87D0-D9C2AAE9DAB4"><p>move files </p> </li>
+<li id="GUID-7DA9BBBD-49E8-59F4-8A7C-B6C8D06FA981"><p>delete files </p> </li>
+<li id="GUID-03AF9640-CAC3-58F0-9FB3-A9227505D50B"><p>rename files </p> </li>
+<li id="GUID-44356ACA-0562-5B1D-BFE6-3ED20275FFBA"><p>delete directories and
+their contained files and sub-directories </p> </li>
+<li id="GUID-7703AEF1-64EE-54C5-8DD5-6F5D67B59A68"><p>set and clear file attributes. </p> </li>
+</ul> <p>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. </p> <p>All of the file
+manipulation functions except <codeph>Rename()</codeph> 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. </p> </section>
+<section id="GUID-EC9DAE8B-FB85-5E7F-925F-B03D2F1D584D"><title>Using CFileMan</title> <p>Typically,
+a <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref> 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. </p> <p>Symbian platform provides a file notification observer
+interface that you can implement to provide notification of events resulting
+from <codeph>CFileMan</codeph> operations. The interface is defined by the <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita"><apiname>MFileManObserver</apiname></xref> class,
+and you provide an implementation for the functions: </p> <ul>
+<li id="GUID-EFEAD891-17C8-56E9-9D1B-89E26CC60AD4"><p> <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita#GUID-E608485F-B3E3-3310-A80E-169D8B9D2234/GUID-54D77B42-2AD9-3F82-89A7-3E651FAC2670"><apiname>MFileManObserver::NotifyFileManStarted()</apiname></xref>  </p> </li>
+<li id="GUID-012EAF53-723B-5A60-822B-B33F8BEE3F1B"><p> <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita#GUID-E608485F-B3E3-3310-A80E-169D8B9D2234/GUID-8D17D294-DE4A-3382-A832-9D318F522DE6"><apiname>MFileManObserver::NotifyFileManOperation()</apiname></xref>  </p> </li>
+<li id="GUID-41626506-7665-5931-A3BA-931A863486AC"><p> <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita#GUID-E608485F-B3E3-3310-A80E-169D8B9D2234/GUID-A73812AF-0877-3322-90C9-8A8F43708C8E"><apiname>MFileManObserver::NotifyFileManEnded()</apiname></xref>. </p> </li>
+</ul> <p>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 <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref> and its base class <xref href="GUID-C1C0C7F9-2665-3475-B70F-61C41291BB4D.dita"><apiname>CFileBase</apiname></xref>: </p> <ul>
+<li id="GUID-F374F903-8456-57E0-B990-50ADEDB62CC8"><p> <xref href="GUID-C1C0C7F9-2665-3475-B70F-61C41291BB4D.dita#GUID-C1C0C7F9-2665-3475-B70F-61C41291BB4D/GUID-5EAB13D4-F93B-388B-92DE-F1987FBF2967"><apiname>CFileBase::GetLastError()</apiname></xref>  </p> </li>
+<li id="GUID-473260BD-F9E1-54B2-BB2B-6D0DB397B774"><p> <xref href="GUID-C1C0C7F9-2665-3475-B70F-61C41291BB4D.dita#GUID-C1C0C7F9-2665-3475-B70F-61C41291BB4D/GUID-96D7B25A-DFF6-3D30-86E0-1393EE0EA301"><apiname>CFileBase::GetMoreInfoAboutError()</apiname></xref>  </p> </li>
+<li id="GUID-86E140C6-A65E-524D-B40C-8D22A3174217"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-4D489875-CAAB-3022-BE81-DF53B961BD9E"><apiname>CFileMan::CurrentAction()</apiname></xref>  </p> </li>
+<li id="GUID-18116CCF-BEF7-5B47-B6C8-F08C8E2DE8D2"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-9DB0E0B7-7100-3FB1-81FA-1075E6E9E609"><apiname>CFileMan::GetCurrentTarget()</apiname></xref>  </p> </li>
+<li id="GUID-F3100AE7-4234-5B9C-9F29-C46EC74B6408"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-CF653BC4-8480-3774-AD87-05E4DDCBC1DE"><apiname>CFileMan::GetCurrentSource()</apiname></xref>  </p> </li>
+<li id="GUID-F2C0B561-6E6C-5223-8428-026D56125807"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-351464A4-E108-39C4-9F40-6C099DC89F0A"><apiname>CFileMan::BytesTransferredByCopyStep()</apiname></xref>  </p> </li>
+</ul> <p>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 <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita#GUID-E608485F-B3E3-3310-A80E-169D8B9D2234/GUID-077D82DD-0D4F-38DB-B2F9-EDE6806DBA7A"><apiname>MFileManObserver::TControl</apiname></xref> value. </p> <p>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. </p> <p><b>Example code (1)</b> </p> <p>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 <filepath>C:\path1</filepath> to <filepath>c:\path2</filepath> synchronously. </p> <p>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 <codeph>CFileMan</codeph> functions. </p> <codeblock id="GUID-F23E9F4C-750D-5019-A38A-5A5EAF27DA48" xml:space="preserve">    ...
+    _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-&gt;SetObserver(&amp;fileCopyProgressMonitor);
+    
+    // Do copy (here synchronously)
+    fileMan-&gt;Copy(KSourcePath,KDestinationPath);
+    
+    // Clean up
+    CleanupStack::PopAndDestroy(); 
+    
+    // close file server session
+    fsSession.Close();
+    ...
+    </codeblock> <codeblock id="GUID-FD9D41C0-EF79-5F5A-92FE-E4128E652B5A" xml:space="preserve">class TFileCopyProgressMonitor : public MFileManObserver
+    {
+public :
+    TFileCopyProgressMonitor(CFileMan&amp; aFileMan);
+public : // implement the interface
+    TControl NotifyFileManStarted();
+    TControl NotifyFileManOperation();
+    TControl NotifyFileManEnded();
+public :
+    CFileMan&amp; iFileMan;
+    }
+     </codeblock> <codeblock id="GUID-3DFCEC35-FDCE-57AC-B940-4F6A5467246D" xml:space="preserve">TFileCopyProgressMonitor::TFileCopyProgressMonitor(CFileMan&amp; aFileMan)
+    :iFileMan(aFileMan)
+    {    
+    }
+
+// Called when a copy operation started
+MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManStarted()
+    {
+    TFileName&amp; 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.
+    }
+     </codeblock> <p><b>Example
+code (1)</b> </p> <p>This code fragment shows a use of the <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-53411800-9145-38CA-8C8C-B8C6F97E8FEE"><apiname>CFileMan::Attribs()</apiname></xref> functions. </p> <codeblock id="GUID-DFE5FD10-DDCC-5882-A8C1-256B3CB5E42B" xml:space="preserve">_LIT(KDirText,"\\TopDir\\");
+...
+fileMan.Attribs(KDirText,KEntryAttHidden|KEntryAttReadOnly,
+    KEntryAttArchive,TTime(0),CFileMan::ERecurse);
+...</codeblock> <p>This sets the hidden and read-only attributes, and clears
+the archive attribute for all files located in the hierarchy below <filepath>\TopDir\</filepath>.
+The time of their last modification will be unchanged. </p> </section>
+<section id="GUID-41F2D8B1-8350-533F-B8BA-4583A6E1C695"><title>Notes</title> <ol id="GUID-D1790FF2-8C3C-55ED-98D8-D095227D5B83">
+<li id="GUID-602606F3-D537-580F-BEB7-1E25F1760B8A"><p>If you use <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-9456C8B9-C975-356C-B3A4-755928DE2AC3"><apiname>CFileMan::Move()</apiname></xref>,
+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: </p> <ul>
+<li id="GUID-E542B9BE-888B-55DE-95A1-A9B00810FD11"><p>if there is a trailing
+backslash ("\") character, then the operation moves the content of the last
+directory level only. </p> </li>
+<li id="GUID-C6A158E1-612C-596D-8C26-88377E3B7AC1"><p>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 <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-8FD6F114-0D4C-3701-ACCF-4748129B1F79"><apiname>CFileMan::ERecurse</apiname></xref> in
+the switches passed to the function. </p> </li>
+</ul> <p>For example, if the directory level "b" contains the files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath>,
+then: </p> <codeblock id="GUID-A08081B3-213E-527D-B413-42A05B54CF0D" xml:space="preserve">CFileMan fm;
+...
+fm-&gt;Move(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> <p>results
+in files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath> being
+moved from <filepath>C:\a\b</filepath> to <filepath>C:\x\y</filepath>, leaving
+the path <filepath>C:\a\b</filepath> unchanged, except that it no longer contains
+the files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath>. </p> <p>If
+there is no trailing backslash character, for example: </p> <codeblock id="GUID-6A5A2B8F-67C4-5278-9A43-FDFC5D849C78" xml:space="preserve">CFileMan fm;
+...
+fm-&gt;Move(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> <p>then
+both the directory level "b" and its contents are moved. This means that there
+is no longer a directory "b" under <filepath>C:\\a</filepath>. Instead there
+is a new directory structure <filepath>C:\x\y\b</filepath> and the files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath> now exist under <filepath>C:\x\y\b</filepath>. Also if "b" contains subdirectories,
+then these are also moved along with "b". </p> </li>
+<li id="GUID-3CAC4CA6-AB36-56AC-81AB-032DF70D99B7"><p>If you use <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-633C2FF5-4077-346D-B7B6-4CC04F887D7B"><apiname>CFileMan::Copy()</apiname></xref>,
+the behaviour of this function does <i>not</i> depend on the presence or absence
+of a trailing backslash ("\") character on the end of the source path. This
+pattern of behaviour is in <i>contrast</i> to that of <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-9456C8B9-C975-356C-B3A4-755928DE2AC3"><apiname>CFileMan::Move()</apiname></xref>.
+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: </p> <codeblock id="GUID-75B4FA7B-BB08-5322-A8C6-ACFD4C860D1D" xml:space="preserve">CFileMan fm;
+...
+fm-&gt;Copy(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse);
+fm-&gt;Copy(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> </li>
+<li id="GUID-A17CB3FD-39BA-5D57-816B-1AB70C746E3F"><p>It is possible to pass <xref href="GUID-5A096F1A-B316-3B40-BB4B-F9F12099DC91.dita"><apiname>KNullDesC</apiname></xref>,
+the null (or empty) descriptor, to the <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita#GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7/GUID-71056B22-AC2A-3E91-8896-8A6F2FB9B619"><apiname>CFileMan::Delete()</apiname></xref> 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 <filepath>\*.*</filepath>. </p> </li>
+</ol> </section>
+</conbody></concept>
\ No newline at end of file