|
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 xml:lang="en" id="GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8"><title>Creating a Charconv Plug-in DLL</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This section describes how to create a Charconv plug-in DLL. </p> <section><title>Introduction</title> <p>The flowchart below shows the steps to create a Charconv plug-in DLL. </p> <fig id="GUID-B145D4B6-8385-5DC9-8958-2350C86EBE2B"><image href="GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e405012_href.png" placement="inline"/></fig> </section> <section><title>Procedure</title> <p>An example is used to explain the procedure for creating a Charconv plug-in DLL. This plug-in converts between the cp850 character set and Unicode. </p> <ol id="GUID-AC4B8539-C41C-5631-A8F7-8C9646951897"><li id="GUID-C75F84C2-C83A-567C-8AC6-788848EEE85E"><p>Create a cnvtool source file using a text editor and save it as, for example <filepath>d:\charconvfiles\data\cp850.txt</filepath>. This file contains pairs of hexadecimal numbers. The first number in each pair is the encoding of a character in cp850and the second is the Unicode encoding of the same character. </p> <codeblock id="GUID-9541977F-8BBA-5838-ACD1-DAB896C00D8C" xml:space="preserve">... |
|
13 0x00 0x0000 #NULL |
|
14 0x01 0x0001 #START OF HEADING |
|
15 0x02 0x0002 #START OF TEXT |
|
16 0x03 0x0003 #END OF TEXT |
|
17 0x04 0x0004 #END OF TRANSMISSION |
|
18 0x05 0x0005 #ENQUIRY |
|
19 0x06 0x0006 #ACKNOWLEDGE |
|
20 ...</codeblock> <p>For more information about the syntax of a cnvtool source file, refer to <xref href="GUID-6796BA71-47A7-5465-89F2-BD0AEF2E4EE7.dita">Cnvtool Source File</xref>. </p> </li> <li id="GUID-62F3284F-1686-5869-A849-373A8092209F"><p>Create a cnvtool control file using a text editor and save it as, for example <filepath>d:\charconvfiles\data\cp850.ctl</filepath>. This file specifies the conversion algorithms to convert both ways between ranges of characters, and other information. </p> <codeblock id="GUID-EC3C3757-655C-5E7E-873A-0D2620FFE09E" xml:space="preserve">Endianness FixedBigEndian |
|
21 ReplacementForUnconvertibleUnicodeCharacters 0x1a # ASCII "substitute" character - must be a single character, and must be little-endian if the "Endianness" above is "Unspecified", otherwise in the same endianness as specified |
|
22 |
|
23 StartForeignVariableByteData |
|
24 # FirstInitialByteValueInRange LastInitialByteValueInRange NumberOfSubsequentBytes |
|
25 0x00 0xff 0 |
|
26 EndForeignVariableByteData |
|
27 |
|
28 StartForeignToUnicodeData |
|
29 # IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm Parameters |
|
30 2 2 0x00 0x7f Direct {} # ASCII |
|
31 1 1 0x80 0xff KeyedTable16OfIndexedTables16 {} # CP850 |
|
32 EndForeignToUnicodeData |
|
33 |
|
34 StartUnicodeToForeignData |
|
35 # IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm SizeOfOutputCharacterCodeInBytes Parameters |
|
36 2 2 0x0000 0x007f Direct 1 {} # ASCII |
|
37 1 1 0x00A0 0x25A0 KeyedTable1616 1 {} # CP850 |
|
38 EndUnicodeToForeignData |
|
39 </codeblock> <p>For more information about the syntax of a cnvtool control file, refer to <xref href="GUID-2624060D-A5E7-590A-9FA0-471AE42A9BE9.dita">Cnvtool Control File</xref>. </p> </li> <li id="GUID-A15AE20D-57A2-5D66-80C6-6CC0CFE5A409"><p>Start a command prompt to run <filepath>cnvtool</filepath> on the source and control files as follows: </p> <p><userinput>cd d:\Symbian\epoc32\tools</userinput> </p> <p><userinput>cnvtool.bat -generateSourceCode d:\charconvfiles\data\cp850.txt d:\charconvfiles\data\cp850.ctl d:\charconvfiles\data\g_cp850.cpp</userinput> </p> <p>This process generates a C++ source code file called <filepath>g_cp850.cpp</filepath>. It is referred to as the <filepath>cnvtool</filepath> -generated cpp file. It contains the <codeph>SCnvConversionData</codeph> data structure. </p> <codeblock id="GUID-0E9F220F-F77C-54D7-A4F1-76672A16625B" xml:space="preserve"> |
|
40 #include <e32std.h> |
|
41 #include <CONVDATA.H> |
|
42 #include <CONVGENERATEDCPP.H> |
|
43 |
|
44 #define ARRAY_LENGTH(aArray) (sizeof(aArray)/sizeof((aArray)[0])) |
|
45 |
|
46 |
|
47 _LIT8(KLit8ReplacementForUnconvertibleUnicodeCharacters, "\x1a"); |
|
48 |
|
49 GLDEF_C const TDesC8& ReplacementForUnconvertibleUnicodeCharacters_internal() |
|
50 { |
|
51 return KLit8ReplacementForUnconvertibleUnicodeCharacters; |
|
52 } |
|
53 |
|
54 LOCAL_D const TUint16 keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1[]= |
|
55 { |
|
56 0x00c7, |
|
57 0x00fc, |
|
58 ... |
|
59 } |
|
60 |
|
61 |
|
62 LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable16OfIndexedTables16::SKeyedEntry keyedTables16OfIndexedTables16_keyedEntries_foreignToUnicode_1[]= |
|
63 { |
|
64 { |
|
65 0x80, |
|
66 0xff, |
|
67 keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1 |
|
68 } |
|
69 }; |
|
70 |
|
71 LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable1616::SEntry keyedTable1616_unicodeToForeign_1[]= |
|
72 { |
|
73 { |
|
74 0x00a0, |
|
75 0xff |
|
76 }, |
|
77 ... |
|
78 } |
|
79 LOCAL_D const SCnvConversionData::SVariableByteData::SRange foreignVariableByteDataRanges[]= |
|
80 { |
|
81 { |
|
82 0x00, |
|
83 0xff, |
|
84 0, |
|
85 0 |
|
86 } |
|
87 }; |
|
88 |
|
89 .... |
|
90 |
|
91 GLDEF_D const SCnvConversionData conversionData= |
|
92 { |
|
93 SCnvConversionData::EFixedBigEndian, |
|
94 { |
|
95 ARRAY_LENGTH(foreignVariableByteDataRanges), |
|
96 foreignVariableByteDataRanges |
|
97 }, |
|
98 { |
|
99 ARRAY_LENGTH(foreignToUnicodeDataRanges), |
|
100 foreignToUnicodeDataRanges |
|
101 }, |
|
102 { |
|
103 ARRAY_LENGTH(unicodeToForeignDataRanges), |
|
104 unicodeToForeignDataRanges |
|
105 }, |
|
106 NULL, |
|
107 NULL |
|
108 }; |
|
109 |
|
110 </codeblock> <p>For more information about the command syntax of cnvtool, refer to <xref href="GUID-214A7085-185B-5D40-A613-E82E68968AAB.dita">Cnvtool Command Syntax</xref>. </p> </li> <li id="GUID-03FF26E6-8AA2-5E31-A9A9-8A366FDBCD7F"><p>Create a cpp file which implements the <xref href="GUID-F58308AA-7072-370D-BE6A-1E8236060FC4.dita"><apiname>CCharacterSetConverterPluginInterface</apiname></xref> class. </p> <p>All of the functions defined in the interface must be implemented by the plug-in DLL. The implementations of <codeph>ConvertFromUnicode()</codeph> and <codeph>ConvertToUnicode()</codeph> must fulfil the following behavioural requirements: </p> <ul><li id="GUID-E6E2B609-A110-5607-8203-6E5C25C8B952"><p>They must return a negative error code (see <codeph>CCnvCharacterSetConverter::TError</codeph>), or the number of elements remaining in the input descriptor which have not been converted. </p> </li> <li id="GUID-2640AA42-5CA9-54B8-BCF8-40896D1BCA36"><p>They must not return an error when the output descriptor is too short or there is a truncated sequence at the end of the input descriptor. </p> <ul><li id="GUID-3A715936-4164-5493-A826-BB10448BD004"><p>If the output descriptor is full, the input descriptor cannot be fully converted. </p> </li> <li id="GUID-8D962732-8CAE-5D39-A2EA-FEA6D50E920E"><p>If the input descriptor ends with a truncated sequence, such as the first half of a Unicode surrogate pair, the first byte of a multi-byte foreign character set character code, or a truncated escape sequence of a modal foreign character set, it cannot be fully converted. </p> </li> </ul> </li> <li id="GUID-50C3341A-1319-5B57-A6B4-A527B48788E5"><p>If the input descriptor consists purely of a truncated sequence they must return <codeph>CCnvCharacterSetConverter::EErrorIllFormedInput</codeph>. </p> </li> </ul> <p>For non-complex character sets, they can call <codeph>CCnvCharacterSetConverter::DoConvertFromUnicode()</codeph> and <codeph>CCnvCharacterSetConverter::DoConvertToUnicode()</codeph> functions respectively. </p> <p>For complex character sets, for example JIS or Shift-JIS, the <xref href="GUID-2FC99DA0-F1C0-3A5E-B990-5DC3F7EAA31C.dita"><apiname>CnvUtilities</apiname></xref> class provides some utility functions. </p> <p>To access the two (const) global objects implemented in the cnvtool-generated cpp file, you must include the <filepath>convgeneratedcpp.h</filepath> header file. The <xref href="GUID-1A6BF3E3-31BF-3BC9-A010-26FF72F39F0B.dita"><apiname>SCnvConversionData</apiname></xref> object generated can then be used to implement the <codeph>ConvertFromUnicode()</codeph> and <codeph>ConvertToUnicode()</codeph> functions. </p> <p> <b>Example implementation</b> </p> <codeblock id="GUID-E899A8AE-73D4-591D-B5A1-6777986D9361" xml:space="preserve">#include <e32std.h> |
|
111 #include <charconv.h> |
|
112 #include <convgeneratedcpp.h> |
|
113 #include <ecom/implementationproxy.h> |
|
114 #include <charactersetconverter.h> |
|
115 |
|
116 class CCP850ConverterImpl : public CCharacterSetConverterPluginInterface |
|
117 { |
|
118 |
|
119 public: |
|
120 virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters(); |
|
121 |
|
122 virtual TInt ConvertFromUnicode( |
|
123 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
124 const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, |
|
125 TDes8& aForeign, |
|
126 const TDesC16& aUnicode, |
|
127 CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters); |
|
128 |
|
129 virtual TInt ConvertToUnicode( |
|
130 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
131 TDes16& aUnicode, |
|
132 const TDesC8& aForeign, |
|
133 TInt& aState, |
|
134 TInt& aNumberOfUnconvertibleCharacters, |
|
135 TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter); |
|
136 |
|
137 virtual TBool IsInThisCharacterSetL( |
|
138 TBool& aSetToTrue, |
|
139 TInt& aConfidenceLevel, |
|
140 const TDesC8& aSample); |
|
141 |
|
142 static CCP850ConverterImpl* NewL(); |
|
143 virtual ~CCP850ConverterImpl(); |
|
144 |
|
145 private: |
|
146 CCP850ConverterImpl(); |
|
147 |
|
148 }; |
|
149 |
|
150 |
|
151 const TDesC8& CCP850ConverterImpl::ReplacementForUnconvertibleUnicodeCharacters() |
|
152 { |
|
153 return ReplacementForUnconvertibleUnicodeCharacters_internal(); |
|
154 } |
|
155 |
|
156 TInt CCP850ConverterImpl::ConvertFromUnicode( |
|
157 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
158 const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, |
|
159 TDes8& aForeign, |
|
160 const TDesC16& aUnicode, |
|
161 CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) |
|
162 { |
|
163 return CCnvCharacterSetConverter::DoConvertFromUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aReplacementForUnconvertibleUnicodeCharacters, aForeign, aUnicode, aIndicesOfUnconvertibleCharacters); |
|
164 } |
|
165 |
|
166 TInt CCP850ConverterImpl::ConvertToUnicode( |
|
167 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
168 TDes16& aUnicode, |
|
169 const TDesC8& aForeign, |
|
170 TInt& /*aState*/, |
|
171 TInt& aNumberOfUnconvertibleCharacters, |
|
172 TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) |
|
173 { |
|
174 return CCnvCharacterSetConverter::DoConvertToUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aUnicode, aForeign, aNumberOfUnconvertibleCharacters, aIndexOfFirstByteOfFirstUnconvertibleCharacter); |
|
175 } |
|
176 |
|
177 TBool CCP850ConverterImpl::IsInThisCharacterSetL( |
|
178 TBool& aSetToTrue, |
|
179 TInt& aConfidenceLevel, |
|
180 const TDesC8& /*aSample*/) |
|
181 { |
|
182 aSetToTrue=ETrue; |
|
183 aConfidenceLevel=0; |
|
184 return EFalse; |
|
185 } |
|
186 |
|
187 CCP850ConverterImpl* CCP850ConverterImpl::NewL() |
|
188 { |
|
189 CCP850ConverterImpl* self = new(ELeave) CCP850ConverterImpl(); |
|
190 return self; |
|
191 } |
|
192 |
|
193 CCP850ConverterImpl::~CCP850ConverterImpl() |
|
194 { |
|
195 } |
|
196 |
|
197 CCP850ConverterImpl::CCP850ConverterImpl() |
|
198 { |
|
199 } |
|
200 |
|
201 const TImplementationProxy ImplementationTable[] = |
|
202 { |
|
203 IMPLEMENTATION_PROXY_ENTRY(0x102825AD, CCP850ConverterImpl::NewL) |
|
204 }; |
|
205 |
|
206 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) |
|
207 { |
|
208 aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); |
|
209 |
|
210 return ImplementationTable; |
|
211 } |
|
212 </codeblock> </li> <li id="GUID-D6584918-0542-5164-B339-658D52E041BF"><p>Create an ECom registry resource file using a text editor. </p> <p>102825ac.rss </p> <codeblock id="GUID-0652DC46-A32A-5730-A0B0-211C45A016B5" xml:space="preserve">#include "ecom/registryinfo.rh" |
|
213 |
|
214 RESOURCE REGISTRY_INFO theInfo |
|
215 { |
|
216 dll_uid = 0x102825AC; // UID acquired from Symbian |
|
217 interfaces = |
|
218 { |
|
219 INTERFACE_INFO |
|
220 { |
|
221 interface_uid = 0x101F7F1D; // fixed UID for Charconv plug-ins |
|
222 implementations = |
|
223 { |
|
224 IMPLEMENTATION_INFO |
|
225 { |
|
226 implementation_uid = 0x102825AD; // UID acquired from Symbian |
|
227 version_no = 1; |
|
228 display_name = "CP850"; |
|
229 default_data = "CP850"; |
|
230 opaque_data = ""; |
|
231 } |
|
232 }; |
|
233 } |
|
234 }; |
|
235 } |
|
236 </codeblock> </li> <li id="GUID-58F16B35-BB07-5C51-AE43-92E9D3D76FE8"><p>Create an mmp file which is used to build the plug-in DLL. </p> <codeblock id="GUID-AB46B407-D465-5AA1-BF7D-78FC11816A45" xml:space="preserve">TARGET cp850.dll |
|
237 TARGETTYPE PLUGIN |
|
238 |
|
239 CAPABILITY All -Tcb |
|
240 |
|
241 UID 0x10009D8D 0x102825AC |
|
242 VENDORID 0x70000001 |
|
243 |
|
244 SYSTEMINCLUDE /epoc32/include |
|
245 |
|
246 SOURCEPATH ../src/plugins |
|
247 SOURCE cp850.cpp |
|
248 |
|
249 SOURCEPATH /epoc32/build/generatedcpp/charconv |
|
250 SOURCE g_cp850.cpp |
|
251 |
|
252 SOURCEPATH ../resource |
|
253 START RESOURCE cp850.rss |
|
254 TARGETPATH /resource/charconv |
|
255 LANG sc |
|
256 END |
|
257 |
|
258 START RESOURCE 102825ac.rss |
|
259 TARGET cp850.rsc |
|
260 END |
|
261 |
|
262 LIBRARY euser.lib |
|
263 LIBRARY charconv.lib |
|
264 LIBRARY ecom.lib |
|
265 </codeblock> </li> </ol> <p>Build the plug-in DLL and install it into the <filepath>\system\charconv\</filepath> directory. The DLL is then available to be loaded when <codeph>CCnvCharacterSetConverter::PrepareToConvertToOrFromL()</codeph> is invoked. </p> </section> </conbody></concept> |