|
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-2E4C50DE-AF0A-5393-A1FB-F739653EB727" xml:lang="en"><title>Interfacing |
|
13 File Systems to the 64-bit File Server</title><shortdesc>Describes the changes to existing file system interface APIs. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-9F86B97F-2CBB-54DD-AF18-22B4A8C1AC48"><title>Introduction</title><p>64-bit |
|
15 versions of some functions have been added to the plugin framework to allow |
|
16 you to handle large files. Other functions have been modified that they may |
|
17 now handle larger files. Changes you may need to make to existing code are |
|
18 detailed here. </p> <p>This is a list of 32-bit functions that have been replaced |
|
19 with 64-bit equivalents to enable large files to be handled: </p><ul> |
|
20 <li id="GUID-EAFE1663-169F-58C9-BA7E-2CE8ED1AD79C"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E591EB49-0E32-3428-8318-AB34B7469E79"><apiname>CFileCB::Size()</apiname></xref> </p> </li> |
|
21 <li id="GUID-D0232F4A-3CDC-5EA6-8664-304D39D42549"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-DA4988F5-651B-3CBA-BB7A-C435B985B53E"><apiname>CFileCB::SetSize(TInt |
|
22 aSize)</apiname></xref> </p> </li> |
|
23 <li id="GUID-C1B2845F-E1F7-5264-AEFB-B962CEDAA6E6"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-64C7E8C3-44A1-30BC-95D5-B8A919DD4751"><apiname>CFileCB::ReadL(TInt |
|
24 aPos,TInt& aLength,const TAny* aDes,const RMessagePtr2& aMessage)</apiname></xref> </p> </li> |
|
25 <li id="GUID-1989817D-F04E-5659-9F91-CA1782EE0362"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-0D0B98AC-709C-3512-8251-F6BB08E65098"><apiname>CFileCB::WriteL(TInt |
|
26 aPos,TInt& aLength,const TAny* aDes,const RMessagePtr2& aMessage)</apiname></xref> </p> </li> |
|
27 <li id="GUID-82DA2B2C-2DAC-5627-A013-FE45BC38CC3D"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-494116CC-1BF8-3226-89BB-110DE6CA3279"><apiname>CFileCB::SetSizeL(TInt |
|
28 aSize)</apiname></xref> </p> </li> |
|
29 <li id="GUID-2A02A7C7-F45D-52CE-BA5F-D1816D766127"><p> <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-A0CC2AA6-0887-32E5-A067-4A61092861DB"><apiname>CMountCB::ReadSectionL(const |
|
30 TDesC& aName,TInt aPos,TAny* aTrg,TInt aLength,const RMessagePtr2& |
|
31 aMessage)</apiname></xref> </p> </li> |
|
32 </ul> </section> |
|
33 <section id="GUID-71C79849-81B6-56EF-8983-615ADFFD229F"><title>Using the CFileCB |
|
34 functions Size() and SetSize()</title><p>New functions have been added to |
|
35 the class <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita"><apiname>CFileCB</apiname></xref> to allow the handling of 64-bit file |
|
36 sizes. File system plugins using the existing 32-bit functions to support |
|
37 large files should replace these with the 64-bit functions:<ul> |
|
38 <li id="GUID-B99707D7-7DC6-5434-9A66-B33BC6291A44"><p>use <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-C7D33970-B958-333E-B338-E99C6BE6CA64"><apiname>CFileCB::Sze64()</apiname></xref> instead |
|
39 of <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E591EB49-0E32-3428-8318-AB34B7469E79"><apiname>CFileCB::Size()</apiname></xref> </p> </li> |
|
40 <li id="GUID-EAD06C55-4CCB-5974-B22B-7CBA66C4D353"><p>use <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-FC2D5C0E-105E-37F3-9F5F-E24183071A3B"><apiname>CFileCB::SetSize64(TInt64 |
|
41 aSize, TBool aDriveLocked)</apiname></xref> instead of <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-DA4988F5-651B-3CBA-BB7A-C435B985B53E"><apiname>CFileCB::SetSize(TInt |
|
42 aSize)</apiname></xref>. </p> </li> |
|
43 <li id="GUID-803F0BB8-0A85-5296-9088-50EA3FBB2A73"><p>Replace 32-bit function |
|
44 calls by 64-bit function calls and change <codeph>TInt</codeph> variables |
|
45 to <codeph>TInt64</codeph>. <codeblock id="GUID-991F4BF5-984B-5799-8A1D-B89BFEA5C59C" xml:space="preserve">CFileCB file; |
|
46 TInt64 iSize; |
|
47 ... |
|
48 file->SetSize64(iSize, EFalse);</codeblock></p></li> |
|
49 </ul></p> <p> The 32-bit versions of these functions are used widely by the |
|
50 file server and the file system. Alter calls to the 32-bit versions of these |
|
51 functions to handle large files. </p> </section> |
|
52 <section id="GUID-BF5DB004-7BBC-5960-8726-1CAF98CE2790"><title>Using the CFileCB |
|
53 functions ReadL(), WriteL() and SetSizeL()</title><p>If you use the <codeph>ReadL()</codeph>, <codeph>WriteL()</codeph> and <codeph>SetSize()</codeph> functions, you must modify the implementation to replace them with their |
|
54 64-bit versions: </p><ul> |
|
55 <li id="GUID-119274EC-FDC6-54C1-8725-C3ACEB37ED67"><p> <xref href="GUID-463972E3-5932-3AC1-84F7-BE865ECE57C7.dita"><apiname>ReadL(TInt64 |
|
56 aPos, TInt& aLength, TDes8* aDes, const RMessagePtr2& aMessage, TInt |
|
57 aOffset)</apiname></xref> </p> </li> |
|
58 <li id="GUID-A73F8B1E-C7E2-5789-86BF-4AEDDDF1D175"><p> <xref href="GUID-7137C656-D259-3DF6-A9B8-78821DD26B3A.dita"><apiname>WriteL(TInt64 |
|
59 aPos, TInt& aLength, const TDesC8* aDes, const RMessagePtr2& aMessage, |
|
60 TInt aOffset)</apiname></xref> </p> </li> |
|
61 <li id="GUID-CEFC6B27-5ECE-5F2B-AEEC-2C2A02DEA54F"><p> <xref href="GUID-198B428B-06C2-3CC8-A692-9C8AB944FF6C.dita"><apiname>SetSizeL(TInt64 |
|
62 aSize)</apiname></xref> </p> </li> |
|
63 </ul>The file system plugin developer must implement the extended interface |
|
64 class <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref> to perform 64-bit |
|
65 file accesses.<p>The file server retrieves the extended interface by calling <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-CBCFC605-C942-3D4E-8ABA-2EF454E5A44B"><apiname>CFileCB::GetInterface()</apiname></xref> with <codeph>EExtendedFileInterface</codeph> as an argument. Sub-classes of <codeph>CFileCB</codeph> that support large |
|
66 file access will need to inherit this class and implement the interface. </p> <ol id="GUID-CE9AD3AD-2CD6-5894-BFAA-BF247EC88625"> |
|
67 <li id="GUID-36045756-CA8F-515D-9B98-76981D57BF8D"><p>Derive <codeph>CYourFileSystemFileCB</codeph> from |
|
68 the classes <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita"><apiname>CFileCB</apiname></xref> and <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref>. </p> <p><codeblock id="GUID-81EFD4A3-46DF-5082-8DF8-9287A7D5BDCB" xml:space="preserve">class CYourFileSystemFileCB : public CFileCB, |
|
69 ... |
|
70 public CFileCB::MExtendedFileInterface |
|
71 { |
|
72 public: |
|
73 // Implement this function to return the CFileCB::MExtendedFileInterface |
|
74 // interface pointer to the file server. |
|
75 |
|
76 virtual TInt GetInterface(TInt aInterfaceId, |
|
77 TAny*& aInterface, |
|
78 TAny* aInput); |
|
79 |
|
80 public: |
|
81 // Implement the CFileCB::MExtendedFileInterface interface extension functions |
|
82 // for 64-bit Read, Write and SetSize. |
|
83 virtual void ReadL(TInt64 aPos, |
|
84 TInt& aLength, |
|
85 TDes8* aDes, |
|
86 const RMessagePtr2& aMessage, |
|
87 TInt aOffset); |
|
88 virtual void WriteL(TInt64 aPos, |
|
89 TInt& aLength, |
|
90 const TDesC8* aDes, |
|
91 const RMessagePtr2& aMessage, |
|
92 TInt aOffset); |
|
93 virtual void SetSizeL(TInt64 aSize); |
|
94 ... |
|
95 }</codeblock> </p> </li> |
|
96 <li id="GUID-70154DA9-F20B-5434-BFDA-4CD132394EE1"><p>In the function <codeph>CYourFileSystemFileCB::GetInterface()</codeph>, |
|
97 return the pointer to a <codeph>CYourFileSystemFileCB</codeph> object through |
|
98 the <codeph>aInterface</codeph> output parameter when the input parameter <codeph>aInterfaceId</codeph> is <xref href="GUID-AC7AF411-725C-33C5-AE33-5F41701705B6.dita#GUID-AC7AF411-725C-33C5-AE33-5F41701705B6/GUID-2FC24879-6235-3063-BB4B-CB57E4465E6E"><apiname>CFileCB::TInterfaceId::EExtendedFileInterface</apiname></xref>. This enables the file server to invoke the 64-bit functions for file access. </p> <p><codeblock id="GUID-ED0A64F5-9EFF-5963-A884-8E5F44896C5E" xml:space="preserve">TInt CYourFileSystemFileCB::GetInterface(TInt aInterfaceId, |
|
99 TAny*& aInterface, |
|
100 TAny* aInput) |
|
101 { |
|
102 switch(aInterfaceId) |
|
103 { |
|
104 // For supporting large file ReadFileSection |
|
105 case CFileCB::EExtendedFileInterface: |
|
106 aInterface = (CFileCB::MExtendedFileInterface*) (this); |
|
107 return KErrNone; |
|
108 ... |
|
109 default: |
|
110 return(CFileCB::GetInterface(aInterfaceId, aInterface, aInput)); |
|
111 } |
|
112 }</codeblock> </p> </li> |
|
113 <li id="GUID-68E292D2-8D32-59C4-879F-F092F18F1C89"><p>Implement the <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref> functions <codeph>ReadL()</codeph>, <codeph>WriteL()</codeph> and <codeph>SetSizeL()</codeph> in <codeph>CYourFileSystemFileCB</codeph> class |
|
114 to provide the 64-bit file access functionality. </p> <p><codeblock id="GUID-5375842E-6856-5EEB-B164-4A005B7AD879" xml:space="preserve">void CYourFileSystemFileCB::ReadL(TInt64 aPos, |
|
115 TInt& aLength, |
|
116 TDes8* aDes, |
|
117 const RMessagePtr2& aMessage, |
|
118 TInt aOffset) |
|
119 { |
|
120 // 64-bit Read implementation. |
|
121 ... |
|
122 } |
|
123 |
|
124 void CYourFileSystemFileCB::WriteL(TInt64 aPos, |
|
125 TInt& aLength, |
|
126 const TDesC8* aDes, |
|
127 const RMessagePtr2& aMessage, |
|
128 TInt aOffset) |
|
129 { |
|
130 // 64-bit Write implementation. |
|
131 ... |
|
132 } |
|
133 |
|
134 void CYourFileSystemFileCB::SetSizeL(TInt64 aSize) |
|
135 { |
|
136 // 64-bit Set Size implementation. |
|
137 ... |
|
138 }</codeblock> </p> </li> |
|
139 </ol><note> <p>The <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref> also |
|
140 supports fair scheduling. Implementations of the functions <xref href="GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655.dita#GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655/GUID-A89B2E8F-4DEA-355E-9DCD-A4AACE016A10"><apiname>CFileCB::MExtendedFileInterface::ReadL()</apiname></xref> and <xref href="GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655.dita#GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655/GUID-DE844202-026F-3BE3-90D5-2E426E1A0D7D"><apiname>CFileCB::MExtendedFileInterface::WriteL()</apiname></xref> should also support <xref href="GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita#GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F/GUID-CBF527A2-EF30-5D4D-9BF4-631748315BE9">Fair |
|
141 scheduling</xref>.</p></note> </section> |
|
142 <section id="GUID-43DF580B-45D3-501B-A014-5CDF0B0B3FE2"><title>Using the CMountCB |
|
143 function ReadSectionL()</title><p>To enable large files access, calls to the |
|
144 32-bit <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-E5D9D0D9-2748-3F95-9E33-4127195A3FE6"><apiname>CMountCB::ReadSectionL()</apiname></xref> function should be replaced |
|
145 by calls to the 64-bit <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-B6078FAE-CC95-3DE0-B4C7-1B957CC650A2"><apiname>CMountCB::ReadSection64L()</apiname></xref> function. </p><codeblock xml:space="preserve">ReadSection64L(const TDesC& aName, TInt64 aPos, TAny* aTrg, TInt aLength, const RMessagePtr2& aMessage)</codeblock> <p>To enable 64-bit file access, you must implement the extended interface |
|
146 class <codeph>CMountCB::MFileExtendedInterface</codeph>. </p> <p>The file |
|
147 server retrieves the interface by calling <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-CABEF8F6-637C-3223-80C6-FBC8B7247030"><apiname>CMountCB::GetInterface()</apiname></xref> with <codeph>EFileExtendedInterface</codeph> as |
|
148 an argument. Sub-classes of <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita"><apiname>CMountCB</apiname></xref> that support large |
|
149 file accesses need to inherit this class and implement the interface. </p> <ol id="GUID-6298E69C-4275-5626-A3BE-799B780BD6EE"> |
|
150 <li id="GUID-83E32E94-CDCF-5410-8915-B59618EC150D"><p>Derive <codeph>CYourFileSystemMountCB</codeph> from |
|
151 the classes <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-75BD3B63-51EB-3FCB-A96F-DE65C73E3983"><apiname>CMountCB::MFileAccessor</apiname></xref> and <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita"><apiname>CMountCB</apiname></xref>. </p> <p><codeblock id="GUID-CB2471A8-2373-5C2C-949B-152A203E9639" xml:space="preserve">class CYourFileSystemMountCB : public CMountCB, public CMountCB::MFileAccessor |
|
152 { |
|
153 ... |
|
154 |
|
155 public: |
|
156 // Implement this function to return the CMountCB::MFileExtendedInterface |
|
157 // interface pointer to file server. |
|
158 virtual TInt GetInterface(TInt aInterfaceId, |
|
159 TAny*& aInterface, |
|
160 TAny* aInput); |
|
161 ... |
|
162 |
|
163 public: |
|
164 // The CMountCB::MFileExtendedInterface interface extension function |
|
165 // for 64-bit read file section implementation |
|
166 virtual void ReadSection64L(const TDesC& aName, |
|
167 TInt64 aPos, |
|
168 TAny* aTrg, |
|
169 TInt aLength, |
|
170 const RMessagePtr2& aMessage); |
|
171 ... |
|
172 }</codeblock> </p> </li> |
|
173 <li id="GUID-A560B3AF-296F-5B8F-943C-FDB3ED1C8C8F"><p>When your implementation |
|
174 of <codeph>GetInterface()</codeph> is passed <xref href="GUID-8B0D74A4-37CC-3ED5-851A-C677161EC0C1.dita#GUID-8B0D74A4-37CC-3ED5-851A-C677161EC0C1/GUID-DD96F07B-9F44-39AF-B217-8FB7DECC932E"><apiname>TInterfaceIds::EFileAccessor</apiname></xref> through |
|
175 the <codeph>aInterfaceId</codeph> parameter, return a pointer to the <codeph>CYourFileSystemMountCB</codeph> object |
|
176 through the <codeph>aInterface</codeph> output parameter. </p> <p><codeblock id="GUID-AB4D1F74-73C3-5C54-8CF5-42C5471AA657" xml:space="preserve">TInt CYourFileSystemMountCB::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* aInput) |
|
177 { |
|
178 switch(aInterfaceId) |
|
179 { |
|
180 case (CMountCB::EFileAccessor): |
|
181 ((CMountCB::MFileAccessor*&) aInterface) = this; |
|
182 return KErrNone; |
|
183 ... |
|
184 default: |
|
185 return(CMountCB::GetInterface(aInterfaceId, aInterface, aInput)); |
|
186 } |
|
187 }</codeblock> </p> </li> |
|
188 <li id="GUID-F4D62E80-382F-5D25-9A11-6D6AB2044EBD"><p>Implement <codeph>CYourFileSystemMountCB::ReadSection64L()</codeph> to |
|
189 perform a 64-bit read from a file. </p> <p><codeblock id="GUID-79DED59B-B1E9-58BC-8394-974D0DA16DE7" xml:space="preserve">void CYourFileSystemMountCB::ReadSection64L(const TDesC& aName, |
|
190 TInt64 aPos, |
|
191 TAny* aTrg, |
|
192 TInt aLength, |
|
193 const RMessagePtr2& aMessage) |
|
194 { |
|
195 // 64-bit Read File Section implementation. |
|
196 ... |
|
197 }</codeblock> </p> </li> |
|
198 </ol> </section> |
|
199 </conbody></concept> |