|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-204627D4-3818-5DE7-8969-C335DBA5B153" xml:lang="en"><title>File |
|
13 management with CFileMan</title><shortdesc>This topic describes the overview, how to use cFileman and few |
|
14 important points about file management.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <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 |
|
16 provides file management functionality, but unlike the corresponding functionality |
|
17 provided by class <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref>, <codeph>CFileMan</codeph> can operate |
|
18 on files and directories located throughout a directory hierarchy. </p> <p> <codeph>CFileMan</codeph> lets |
|
19 you: </p> <ul> |
|
20 <li id="GUID-009066F1-2047-5BEF-A3A0-FB4FC341753D"><p>copy files </p> </li> |
|
21 <li id="GUID-4777CAC8-8537-5AF6-87D0-D9C2AAE9DAB4"><p>move files </p> </li> |
|
22 <li id="GUID-7DA9BBBD-49E8-59F4-8A7C-B6C8D06FA981"><p>delete files </p> </li> |
|
23 <li id="GUID-03AF9640-CAC3-58F0-9FB3-A9227505D50B"><p>rename files </p> </li> |
|
24 <li id="GUID-44356ACA-0562-5B1D-BFE6-3ED20275FFBA"><p>delete directories and |
|
25 their contained files and sub-directories </p> </li> |
|
26 <li id="GUID-7703AEF1-64EE-54C5-8DD5-6F5D67B59A68"><p>set and clear file attributes. </p> </li> |
|
27 </ul> <p>The functions provided by the class accept the use of wildcards, |
|
28 and means that some operations may take time to complete. The class, however, |
|
29 provides both synchronous and asynchronous variants. </p> <p>All of the file |
|
30 manipulation functions except <codeph>Rename()</codeph> can operate recursively, |
|
31 and all can operate non-recursively. When operating recursively, these functions |
|
32 will act on all matching files located throughout the source directory's hierarchy. |
|
33 When operating non-recursively, these functions act upon files contained in |
|
34 the single top level source directory only. Recursion is set or unset using |
|
35 the switch parameter to these functions. </p> </section> |
|
36 <section id="GUID-EC9DAE8B-FB85-5E7F-925F-B03D2F1D584D"><title>Using CFileMan</title> <p>Typically, |
|
37 a <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref> operation can result in a number of file/directory |
|
38 manipulation operations, especially if wild cards are used. Some operations, |
|
39 such as copying files, can take a (relatively) long time, especially if such |
|
40 files are large. </p> <p>Symbian platform provides a file notification observer |
|
41 interface that you can implement to provide notification of events resulting |
|
42 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, |
|
43 and you provide an implementation for the functions: </p> <ul> |
|
44 <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> |
|
45 <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> |
|
46 <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> |
|
47 </ul> <p>Symbian platform calls the notification functions before or after |
|
48 each file or directory entry has been processed, or during a file copy or |
|
49 move operation. You can use the notification to provide information about |
|
50 the state of the operation, such as error codes, the names of the target and |
|
51 destination files, and the number of bytes transferred during a copy operation. |
|
52 This information is available to your implementation by calling the public |
|
53 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> |
|
54 <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> |
|
55 <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> |
|
56 <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> |
|
57 <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> |
|
58 <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> |
|
59 <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> |
|
60 </ul> <p>You can also use the notification function to cancel, retry or continue |
|
61 processing a file or directory, or to abort the whole operation, by returning |
|
62 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 |
|
63 mechanism provides a way for an application to provide feedback, or to give |
|
64 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 |
|
65 might use this. It is not a complete example, but it gives you an idea of |
|
66 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, |
|
67 and you would probably need the use of active objects, especially if using |
|
68 the asynchronous versions of the <codeph>CFileMan</codeph> functions. </p> <codeblock id="GUID-F23E9F4C-750D-5019-A38A-5A5EAF27DA48" xml:space="preserve"> ... |
|
69 _LIT(KSourcePath,"C:\\path1\\*.*"); |
|
70 _LIT(KDestinationPath,"C:\\path2"); |
|
71 |
|
72 // Connect session |
|
73 RFs fsSession; |
|
74 User::LeaveIfError(fsSession.Connect()); |
|
75 |
|
76 // Create file management object |
|
77 CFileMan* fileMan = CFileMan::NewL(fsSession); |
|
78 CleanupStack::PushL(fileMan); |
|
79 |
|
80 // Create file management notification object and set to observe |
|
81 TFileCopyProgressMonitor fileCopyProgressMonitor(*fileMan); |
|
82 fileMan->SetObserver(&fileCopyProgressMonitor); |
|
83 |
|
84 // Do copy (here synchronously) |
|
85 fileMan->Copy(KSourcePath,KDestinationPath); |
|
86 |
|
87 // Clean up |
|
88 CleanupStack::PopAndDestroy(); |
|
89 |
|
90 // close file server session |
|
91 fsSession.Close(); |
|
92 ... |
|
93 </codeblock> <codeblock id="GUID-FD9D41C0-EF79-5F5A-92FE-E4128E652B5A" xml:space="preserve">class TFileCopyProgressMonitor : public MFileManObserver |
|
94 { |
|
95 public : |
|
96 TFileCopyProgressMonitor(CFileMan& aFileMan); |
|
97 public : // implement the interface |
|
98 TControl NotifyFileManStarted(); |
|
99 TControl NotifyFileManOperation(); |
|
100 TControl NotifyFileManEnded(); |
|
101 public : |
|
102 CFileMan& iFileMan; |
|
103 } |
|
104 </codeblock> <codeblock id="GUID-3DFCEC35-FDCE-57AC-B940-4F6A5467246D" xml:space="preserve">TFileCopyProgressMonitor::TFileCopyProgressMonitor(CFileMan& aFileMan) |
|
105 :iFileMan(aFileMan) |
|
106 { |
|
107 } |
|
108 |
|
109 // Called when a copy operation started |
|
110 MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManStarted() |
|
111 { |
|
112 TFileName& aFile |
|
113 |
|
114 // Get name of file we are copying. |
|
115 // you might want to do something with this, such as display in a UI, |
|
116 // or save in a data member of this object for later use. |
|
117 iFileMan.GetCurrentSource(aFile); |
|
118 |
|
119 // Allow the operation to continue. |
|
120 return EContinue; |
|
121 } |
|
122 |
|
123 // Called while a copy operation is in progress |
|
124 MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManOperation() |
|
125 { |
|
126 TInt bytesTransferred; |
|
127 |
|
128 // number of bytes copied so far for the file. |
|
129 bytesbytesTransferred = iFileMan.BytesTransferredByCopyStep(); |
|
130 |
|
131 // Allow the operation to continue. |
|
132 // You would choose to do something different; for example, you could |
|
133 // return ECancel to cancel the operation if you had a reason to do so, |
|
134 return EContinue; |
|
135 } |
|
136 |
|
137 // Called when a copy operation is complete |
|
138 MFileManObserver::TControl TFileCopyProgressMonitor::NotifyFileManEnded() |
|
139 { |
|
140 TInt lasterror; |
|
141 |
|
142 // Allow operations to continue if all is well. |
|
143 lasterror = iFileMan.GetLastError(); |
|
144 if (lasterror == KErrNone) |
|
145 { |
|
146 return EContinue; |
|
147 } |
|
148 |
|
149 // Operation has not completed properly, so you might want to get |
|
150 // more information, and proceed accordingly. |
|
151 TFileManError filemanerror; |
|
152 |
|
153 filemanerror = iFileMan.GetMoreInfoAboutError(); |
|
154 if (filemanerror==ESrcOpenFailed) |
|
155 { |
|
156 ... |
|
157 return EAbort; |
|
158 } |
|
159 |
|
160 if (filemanerror==ETrgOpenFailed) |
|
161 { |
|
162 ... |
|
163 return EAbort; |
|
164 } |
|
165 |
|
166 ... // you might want to check for other conditions etc. |
|
167 } |
|
168 </codeblock> <p><b>Example |
|
169 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\\"); |
|
170 ... |
|
171 fileMan.Attribs(KDirText,KEntryAttHidden|KEntryAttReadOnly, |
|
172 KEntryAttArchive,TTime(0),CFileMan::ERecurse); |
|
173 ...</codeblock> <p>This sets the hidden and read-only attributes, and clears |
|
174 the archive attribute for all files located in the hierarchy below <filepath>\TopDir\</filepath>. |
|
175 The time of their last modification will be unchanged. </p> </section> |
|
176 <section id="GUID-41F2D8B1-8350-533F-B8BA-4583A6E1C695"><title>Notes</title> <ol id="GUID-D1790FF2-8C3C-55ED-98D8-D095227D5B83"> |
|
177 <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>, |
|
178 be aware that the behaviour of this operation is sensitive to the presence |
|
179 (or absence) of a trailing backslash ("\") character on the end of the source |
|
180 path: </p> <ul> |
|
181 <li id="GUID-E542B9BE-888B-55DE-95A1-A9B00810FD11"><p>if there is a trailing |
|
182 backslash ("\") character, then the operation moves the content of the last |
|
183 directory level only. </p> </li> |
|
184 <li id="GUID-C6A158E1-612C-596D-8C26-88377E3B7AC1"><p>if there is no trailing |
|
185 backslash ("\") character, then the operation moves both the last directory |
|
186 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 |
|
187 the switches passed to the function. </p> </li> |
|
188 </ul> <p>For example, if the directory level "b" contains the files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath>, |
|
189 then: </p> <codeblock id="GUID-A08081B3-213E-527D-B413-42A05B54CF0D" xml:space="preserve">CFileMan fm; |
|
190 ... |
|
191 fm->Move(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> <p>results |
|
192 in files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath> being |
|
193 moved from <filepath>C:\a\b</filepath> to <filepath>C:\x\y</filepath>, leaving |
|
194 the path <filepath>C:\a\b</filepath> unchanged, except that it no longer contains |
|
195 the files <filepath>F1</filepath>, <filepath>F2</filepath> and <filepath>F3</filepath>. </p> <p>If |
|
196 there is no trailing backslash character, for example: </p> <codeblock id="GUID-6A5A2B8F-67C4-5278-9A43-FDFC5D849C78" xml:space="preserve">CFileMan fm; |
|
197 ... |
|
198 fm->Move(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> <p>then |
|
199 both the directory level "b" and its contents are moved. This means that there |
|
200 is no longer a directory "b" under <filepath>C:\\a</filepath>. Instead there |
|
201 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, |
|
202 then these are also moved along with "b". </p> </li> |
|
203 <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>, |
|
204 the behaviour of this function does <i>not</i> depend on the presence or absence |
|
205 of a trailing backslash ("\") character on the end of the source path. This |
|
206 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>. |
|
207 You can only copy the content of the source path. You cannot request that |
|
208 the last directory level plus its content be copied to the target path, by |
|
209 adding a trailing backslash ("\") character onto the end of the source path. |
|
210 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; |
|
211 ... |
|
212 fm->Copy(_L("C:\a\b\"), _L("C:\x\y\"), CFileMan::ERecurse); |
|
213 fm->Copy(_L("C:\a\b"), _L("C:\x\y\"), CFileMan::ERecurse);</codeblock> </li> |
|
214 <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>, |
|
215 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 |
|
216 as the path name. Although you might expect these functions to treat this |
|
217 as a null request, i.e. to delete nothing, they interpret the null descriptor |
|
218 as the string <filepath>\*.*</filepath>. </p> </li> |
|
219 </ol> </section> |
|
220 </conbody></concept> |