1 charactersetconverter.h |
1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #if !defined(__CHARACTERSETCONVERTER_H__) |
|
17 #define __CHARACTERSETCONVERTER_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <ecom/ecom.h> |
|
21 |
|
22 /** |
|
23 This constant holds the UID of the CharConv Character Set Conversion |
|
24 ECOM Interface. |
|
25 @publishedAll |
|
26 @released |
|
27 */ |
|
28 const TUid KCharacterSetConvertorInterfaceUid = {0x101F7F1D}; |
|
29 |
|
30 /** |
|
31 This is the base class defining the methods in the CharConv Character Set |
|
32 Conversion plugin interface. CharConv plugin suppliers would define |
|
33 implementation classes inheriting from this interface class to add additional |
|
34 character set support to CharConv. |
|
35 @publishedAll |
|
36 @released |
|
37 */ |
|
38 NONSHARABLE_CLASS(CCharacterSetConverterPluginInterface) : public CBase |
|
39 { |
|
40 |
|
41 public: |
|
42 |
|
43 /** |
|
44 * |
|
45 * A function prototype which must be implemented by a character |
|
46 * conversion plug-in DLL to return the character (represented by one or |
|
47 * more byte values) which is used by default as the replacement for |
|
48 * unconvertible Unicode characters. |
|
49 * |
|
50 * This character is used when converting from Unicode into a foreign |
|
51 * character set, if there is no equivalent for the Unicode character in |
|
52 * the foreign character set. The default replacement character can be |
|
53 * overriden by a call to <code>CCnvCharacterSetConverter::SetReplacemen- |
|
54 * tForUnconvertibleUnicodeCharactersL()</code>.This function is exported |
|
55 * at ordinal position 1 in the plug-in DLL. It is called by <code>CCnvC- |
|
56 * haracterSetConverter::PrepareToConvertToOrFromL()</code>.To implement |
|
57 * this function, you should #include convgeneratedcpp.h in the cpp file. |
|
58 * This gives access to the |
|
59 * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code> |
|
60 * function. This function can then be implemented by calling |
|
61 * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code>. |
|
62 * |
|
63 * @since 6.0 |
|
64 * @return " const TDesC8& " |
|
65 * The single character which is to be used to replace |
|
66 * unconvertible characters. |
|
67 */ |
|
68 virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters() = 0; |
|
69 |
|
70 /** |
|
71 * |
|
72 * A function prototype which must be implemented by a character |
|
73 * conversion plug-in DLL to convert from Unicode into a foreign |
|
74 * character set. |
|
75 * |
|
76 * This function is exported at ordinal position 2 in the plug-in DLL. It |
|
77 * is called by |
|
78 * <code>CCnvCharacterSetConverter::ConvertFromUnicode()</code>.For many |
|
79 * non-complex character sets, the implementation of this function is |
|
80 * trivial. Include convgeneratedcpp.h in the .cpp file to get access to |
|
81 * the <code>SCnvConversionData</code> object called |
|
82 * <code>conversionData</code>. Then call |
|
83 * <code>CCnvCharacterSetConverter::DoConvertFromUnicode()</code> |
|
84 * specifying <code>conversionData</code> as the first argument and |
|
85 * passing in all parameters unchanged.For complex character sets, you |
|
86 * need to create an array of character conversion data objects |
|
87 * (<code>CnvUtilities::SCharacterSet</code>s), then call |
|
88 * <code>CnvUtilities::ConvertFromUnicode()</code>. |
|
89 * |
|
90 * @since 6.0 |
|
91 * @param " CCnvCharacterSetConverter::TEndianness |
|
92 aDefaultEndiannessOfForeignCharacters " |
|
93 * The default endian-ness to use when writing the |
|
94 * characters in the foreign character set. |
|
95 * @param " const TDesC8& aReplacementForUnconvertibleUnicodeCharacters |
|
96 " |
|
97 * The single character which is used to replace |
|
98 * unconvertible characters. |
|
99 * @param " TDes8& aForeign " |
|
100 * On return, contains the converted text in the target |
|
101 * non-Unicode character set. |
|
102 * @param " const TDesC16& aUnicode " |
|
103 * The source Unicode text to be converted. |
|
104 * @param " CCnvCharacterSetConverter::TArrayOfAscendingIndices& |
|
105 aIndicesOfUnconvertibleCharacters " |
|
106 * A buffer which on return holds the indices of each |
|
107 * Unicode character in the source text which could not |
|
108 * be converted (because the target character set does |
|
109 * not have an equivalent character). |
|
110 * @return " TInt " |
|
111 * The number of unconverted characters left at the end |
|
112 * of the input descriptor (e.g. because |
|
113 * <code>aForeign</code> was not long enough to hold all |
|
114 * the text), or a negative error value, as defined in |
|
115 * <code>TError</code>. |
|
116 */ |
|
117 virtual TInt ConvertFromUnicode( |
|
118 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
119 const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, |
|
120 TDes8& aForeign, |
|
121 const TDesC16& aUnicode, |
|
122 CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) = 0; |
|
123 |
|
124 /** |
|
125 * |
|
126 * A function prototype which must be implemented by a character |
|
127 * conversion plug-in DLL to convert from a foreign character set into |
|
128 * Unicode. |
|
129 * |
|
130 * This function is exported at ordinal position 3 in the plug-in DLL. It |
|
131 * is called by |
|
132 * <code>CCnvCharacterSetConverter::ConvertToUnicode()</code>.For many |
|
133 * non-complex character sets, the implementation of this function is |
|
134 * trivial. Include convgeneratedcpp.h in the .cpp file to get access to |
|
135 * the <code>SCnvConversionData</code> object called |
|
136 * <code>conversionData</code>. Then call |
|
137 * <code>CCnvCharacterSetConverter::DoConvertToUnicode()</code> |
|
138 * specifying <code>conversionData</code> as the first argument and |
|
139 * passing in all other parameters unchanged.For complex character sets, |
|
140 * you need to create an array of character conversion methods |
|
141 * (<code>CnvUtilities::SMethod</code>s or |
|
142 * <code>CnvUtilities::SState</code>s, depending on whether the complex |
|
143 * character set encoding is modal or not), then call |
|
144 * <code>CnvUtilities::ConvertToUnicodeFromHeterogeneousForeign()</code> |
|
145 * or <code>CnvUtilities::ConvertToUnicodeFromModalForeign()</code>. |
|
146 * |
|
147 * @since 6.0 |
|
148 * @param " CCnvCharacterSetConverter::TEndianness |
|
149 aDefaultEndiannessOfForeignCharacters " |
|
150 * The default endian-ness to use when reading characters |
|
151 * in the foreign character set. |
|
152 * @param " TDes16& aUnicode " |
|
153 * On return, contains the text converted into Unicode. |
|
154 * @param " const TDesC8& aForeign " |
|
155 * The non-Unicode source text to be converted. |
|
156 * @param " TInt& aState " |
|
157 * Used to save state information across multiple calls |
|
158 * to <code>ConvertToUnicode()</code>. |
|
159 * @param " TInt& aNumberOfUnconvertibleCharacters " |
|
160 * On return, contains the number of bytes which were not |
|
161 * converted. |
|
162 * @param " TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter " |
|
163 * On return, contains the index of the first bytein the |
|
164 * input text that could not be converted. A negative |
|
165 * value indicates that all the characters were |
|
166 * converted. |
|
167 * @return " TInt " |
|
168 * The number of unconverted bytes left at the end of the |
|
169 * input descriptor (e.g. because the output descriptor |
|
170 * is not long enough to hold all the text), or one of |
|
171 * the error values defined in <code>TError</code>. |
|
172 */ |
|
173 virtual TInt ConvertToUnicode( |
|
174 CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, |
|
175 TDes16& aUnicode, |
|
176 const TDesC8& aForeign, |
|
177 TInt& aState, |
|
178 TInt& aNumberOfUnconvertibleCharacters, |
|
179 TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) = 0; |
|
180 |
|
181 /** |
|
182 * |
|
183 * A function which must be implemented by a character conversion plug-in |
|
184 * DLL to calculate how probable it is that a sample piece of text is |
|
185 * encoded in this character set. |
|
186 * |
|
187 * This function was added in 6.1 as the 4th-ordinal exported function in |
|
188 * the plug-in DLL interface. It is called by |
|
189 * <code>CCnvCharacterSetConverter::AutoDetectCharacterSetL()</code> for |
|
190 * each character conversion plug-in DLL. |
|
191 * |
|
192 * @since 6.1 |
|
193 * @param " TBool& aSetToTrue" |
|
194 * This value should be set to <code>ETrue</code>. It is |
|
195 * used to indicate to <code>CCnvCharacterSetConverter::- |
|
196 * AutoDetectCharacterSetL()</code> that the plug-in DLL |
|
197 * is implementing a function of this signature and is |
|
198 * therefore not the empty, reserved function that was |
|
199 * previously exported at the 4th ordinal position in the |
|
200 * plug-in DLL in v6.0. |
|
201 * @param "TInt& aConfidenceLevel" |
|
202 * On return, indicates how confident the function is |
|
203 * about its return value. Set to a value between 0 and |
|
204 * 100. Zero indicates no confidence, (and the return |
|
205 * value should be disregarded), 100 indicates total |
|
206 * confidence. |
|
207 * @param "const TDesC8& aSample" |
|
208 * The sample text string, as passed to <code>CCnvCharac- |
|
209 * terSetConverter::AutoDetectCharacterSetL()</code>. |
|
210 * @return "TBool" |
|
211 * <code>ETrue</code> if it is more probable that the |
|
212 * sample text is encoded in this character set than not. |
|
213 * <code>EFalse</code> if it is more probable that the |
|
214 * sample text is not encoded in this character set. The |
|
215 * confidence level applies to this value. |
|
216 */ |
|
217 virtual TBool IsInThisCharacterSetL( |
|
218 TBool& aSetToTrue, |
|
219 TInt& aConfidenceLevel, |
|
220 const TDesC8& aSample) = 0; |
|
221 |
|
222 static CCharacterSetConverterPluginInterface* NewL(TUid aInterfaceImplUid) |
|
223 { |
|
224 return reinterpret_cast <CCharacterSetConverterPluginInterface*> ( |
|
225 REComSession::CreateImplementationL( |
|
226 aInterfaceImplUid, |
|
227 _FOFF(CCharacterSetConverterPluginInterface, iDtor_ID_Key))); |
|
228 }; |
|
229 |
|
230 /** |
|
231 Destroys the Charconv Plug-in interface implementation specified by iDtor_ID_Key |
|
232 */ |
|
233 virtual ~CCharacterSetConverterPluginInterface() |
|
234 { |
|
235 REComSession::DestroyedImplementation(iDtor_ID_Key); |
|
236 }; |
|
237 |
|
238 |
|
239 private: |
|
240 |
|
241 TUid iDtor_ID_Key; |
|
242 |
|
243 }; |
|
244 |
|
245 |
|
246 #endif //__CHARACTERSETCONVERTER_H__ |