<?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->SetObserver(&fileCopyProgressMonitor);

    // Do copy (here synchronously)

    fileMan->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& aFileMan);

public : // implement the interface

    TControl NotifyFileManStarted();

    TControl NotifyFileManOperation();

    TControl NotifyFileManEnded();

public :

    CFileMan& 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& 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->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>