1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/charconvfw/charconv_fw/inc/charactersetconverter.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,250 @@
1.4 +/*
1.5 +* Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#if !defined(__CHARACTERSETCONVERTER_H__)
1.23 +#define __CHARACTERSETCONVERTER_H__
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <ecom/ecom.h>
1.27 +
1.28 +/**
1.29 +This constant holds the UID of the CharConv Character Set Conversion
1.30 +ECOM Interface.
1.31 +@publishedAll
1.32 +@released
1.33 +*/
1.34 +const TUid KCharacterSetConvertorInterfaceUid = {0x101F7F1D};
1.35 +
1.36 +/**
1.37 +This is the base class defining the methods in the CharConv Character Set
1.38 +Conversion plugin interface. CharConv plugin suppliers would define
1.39 +implementation classes inheriting from this interface class to add additional
1.40 +character set support to CharConv.
1.41 +@publishedAll
1.42 +@released
1.43 +*/
1.44 +NONSHARABLE_CLASS(CCharacterSetConverterPluginInterface) : public CBase
1.45 + {
1.46 +
1.47 +public:
1.48 +
1.49 +/**
1.50 + *
1.51 + * A function prototype which must be implemented by a character
1.52 + * conversion plug-in DLL to return the character (represented by one or
1.53 + * more byte values) which is used by default as the replacement for
1.54 + * unconvertible Unicode characters.
1.55 + *
1.56 + * This character is used when converting from Unicode into a foreign
1.57 + * character set, if there is no equivalent for the Unicode character in
1.58 + * the foreign character set. The default replacement character can be
1.59 + * overriden by a call to <code>CCnvCharacterSetConverter::SetReplacemen-
1.60 + * tForUnconvertibleUnicodeCharactersL()</code>.This function is exported
1.61 + * at ordinal position 1 in the plug-in DLL. It is called by <code>CCnvC-
1.62 + * haracterSetConverter::PrepareToConvertToOrFromL()</code>.To implement
1.63 + * this function, you should #include convgeneratedcpp.h in the cpp file.
1.64 + * This gives access to the
1.65 + * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code>
1.66 + * function. This function can then be implemented by calling
1.67 + * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code>.
1.68 + *
1.69 + * @since 6.0
1.70 + * @return " const TDesC8& "
1.71 + * The single character which is to be used to replace
1.72 + * unconvertible characters.
1.73 + */
1.74 + virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters() = 0;
1.75 +
1.76 +/**
1.77 + *
1.78 + * A function prototype which must be implemented by a character
1.79 + * conversion plug-in DLL to convert from Unicode into a foreign
1.80 + * character set.
1.81 + *
1.82 + * This function is exported at ordinal position 2 in the plug-in DLL. It
1.83 + * is called by
1.84 + * <code>CCnvCharacterSetConverter::ConvertFromUnicode()</code>.For many
1.85 + * non-complex character sets, the implementation of this function is
1.86 + * trivial. Include convgeneratedcpp.h in the .cpp file to get access to
1.87 + * the <code>SCnvConversionData</code> object called
1.88 + * <code>conversionData</code>. Then call
1.89 + * <code>CCnvCharacterSetConverter::DoConvertFromUnicode()</code>
1.90 + * specifying <code>conversionData</code> as the first argument and
1.91 + * passing in all parameters unchanged.For complex character sets, you
1.92 + * need to create an array of character conversion data objects
1.93 + * (<code>CnvUtilities::SCharacterSet</code>s), then call
1.94 + * <code>CnvUtilities::ConvertFromUnicode()</code>.
1.95 + *
1.96 + * @since 6.0
1.97 + * @param " CCnvCharacterSetConverter::TEndianness
1.98 + aDefaultEndiannessOfForeignCharacters "
1.99 + * The default endian-ness to use when writing the
1.100 + * characters in the foreign character set.
1.101 + * @param " const TDesC8& aReplacementForUnconvertibleUnicodeCharacters
1.102 + "
1.103 + * The single character which is used to replace
1.104 + * unconvertible characters.
1.105 + * @param " TDes8& aForeign "
1.106 + * On return, contains the converted text in the target
1.107 + * non-Unicode character set.
1.108 + * @param " const TDesC16& aUnicode "
1.109 + * The source Unicode text to be converted.
1.110 + * @param " CCnvCharacterSetConverter::TArrayOfAscendingIndices&
1.111 + aIndicesOfUnconvertibleCharacters "
1.112 + * A buffer which on return holds the indices of each
1.113 + * Unicode character in the source text which could not
1.114 + * be converted (because the target character set does
1.115 + * not have an equivalent character).
1.116 + * @return " TInt "
1.117 + * The number of unconverted characters left at the end
1.118 + * of the input descriptor (e.g. because
1.119 + * <code>aForeign</code> was not long enough to hold all
1.120 + * the text), or a negative error value, as defined in
1.121 + * <code>TError</code>.
1.122 + */
1.123 + virtual TInt ConvertFromUnicode(
1.124 + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters,
1.125 + const TDesC8& aReplacementForUnconvertibleUnicodeCharacters,
1.126 + TDes8& aForeign,
1.127 + const TDesC16& aUnicode,
1.128 + CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) = 0;
1.129 +
1.130 +/**
1.131 + *
1.132 + * A function prototype which must be implemented by a character
1.133 + * conversion plug-in DLL to convert from a foreign character set into
1.134 + * Unicode.
1.135 + *
1.136 + * This function is exported at ordinal position 3 in the plug-in DLL. It
1.137 + * is called by
1.138 + * <code>CCnvCharacterSetConverter::ConvertToUnicode()</code>.For many
1.139 + * non-complex character sets, the implementation of this function is
1.140 + * trivial. Include convgeneratedcpp.h in the .cpp file to get access to
1.141 + * the <code>SCnvConversionData</code> object called
1.142 + * <code>conversionData</code>. Then call
1.143 + * <code>CCnvCharacterSetConverter::DoConvertToUnicode()</code>
1.144 + * specifying <code>conversionData</code> as the first argument and
1.145 + * passing in all other parameters unchanged.For complex character sets,
1.146 + * you need to create an array of character conversion methods
1.147 + * (<code>CnvUtilities::SMethod</code>s or
1.148 + * <code>CnvUtilities::SState</code>s, depending on whether the complex
1.149 + * character set encoding is modal or not), then call
1.150 + * <code>CnvUtilities::ConvertToUnicodeFromHeterogeneousForeign()</code>
1.151 + * or <code>CnvUtilities::ConvertToUnicodeFromModalForeign()</code>.
1.152 + *
1.153 + * @since 6.0
1.154 + * @param " CCnvCharacterSetConverter::TEndianness
1.155 + aDefaultEndiannessOfForeignCharacters "
1.156 + * The default endian-ness to use when reading characters
1.157 + * in the foreign character set.
1.158 + * @param " TDes16& aUnicode "
1.159 + * On return, contains the text converted into Unicode.
1.160 + * @param " const TDesC8& aForeign "
1.161 + * The non-Unicode source text to be converted.
1.162 + * @param " TInt& aState "
1.163 + * Used to save state information across multiple calls
1.164 + * to <code>ConvertToUnicode()</code>.
1.165 + * @param " TInt& aNumberOfUnconvertibleCharacters "
1.166 + * On return, contains the number of bytes which were not
1.167 + * converted.
1.168 + * @param " TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter "
1.169 + * On return, contains the index of the first bytein the
1.170 + * input text that could not be converted. A negative
1.171 + * value indicates that all the characters were
1.172 + * converted.
1.173 + * @return " TInt "
1.174 + * The number of unconverted bytes left at the end of the
1.175 + * input descriptor (e.g. because the output descriptor
1.176 + * is not long enough to hold all the text), or one of
1.177 + * the error values defined in <code>TError</code>.
1.178 + */
1.179 + virtual TInt ConvertToUnicode(
1.180 + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters,
1.181 + TDes16& aUnicode,
1.182 + const TDesC8& aForeign,
1.183 + TInt& aState,
1.184 + TInt& aNumberOfUnconvertibleCharacters,
1.185 + TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) = 0;
1.186 +
1.187 +/**
1.188 + *
1.189 + * A function which must be implemented by a character conversion plug-in
1.190 + * DLL to calculate how probable it is that a sample piece of text is
1.191 + * encoded in this character set.
1.192 + *
1.193 + * This function was added in 6.1 as the 4th-ordinal exported function in
1.194 + * the plug-in DLL interface. It is called by
1.195 + * <code>CCnvCharacterSetConverter::AutoDetectCharacterSetL()</code> for
1.196 + * each character conversion plug-in DLL.
1.197 + *
1.198 + * @since 6.1
1.199 + * @param " TBool& aSetToTrue"
1.200 + * This value should be set to <code>ETrue</code>. It is
1.201 + * used to indicate to <code>CCnvCharacterSetConverter::-
1.202 + * AutoDetectCharacterSetL()</code> that the plug-in DLL
1.203 + * is implementing a function of this signature and is
1.204 + * therefore not the empty, reserved function that was
1.205 + * previously exported at the 4th ordinal position in the
1.206 + * plug-in DLL in v6.0.
1.207 + * @param "TInt& aConfidenceLevel"
1.208 + * On return, indicates how confident the function is
1.209 + * about its return value. Set to a value between 0 and
1.210 + * 100. Zero indicates no confidence, (and the return
1.211 + * value should be disregarded), 100 indicates total
1.212 + * confidence.
1.213 + * @param "const TDesC8& aSample"
1.214 + * The sample text string, as passed to <code>CCnvCharac-
1.215 + * terSetConverter::AutoDetectCharacterSetL()</code>.
1.216 + * @return "TBool"
1.217 + * <code>ETrue</code> if it is more probable that the
1.218 + * sample text is encoded in this character set than not.
1.219 + * <code>EFalse</code> if it is more probable that the
1.220 + * sample text is not encoded in this character set. The
1.221 + * confidence level applies to this value.
1.222 + */
1.223 + virtual TBool IsInThisCharacterSetL(
1.224 + TBool& aSetToTrue,
1.225 + TInt& aConfidenceLevel,
1.226 + const TDesC8& aSample) = 0;
1.227 +
1.228 + static CCharacterSetConverterPluginInterface* NewL(TUid aInterfaceImplUid)
1.229 + {
1.230 + return reinterpret_cast <CCharacterSetConverterPluginInterface*> (
1.231 + REComSession::CreateImplementationL(
1.232 + aInterfaceImplUid,
1.233 + _FOFF(CCharacterSetConverterPluginInterface, iDtor_ID_Key)));
1.234 + };
1.235 +
1.236 +/**
1.237 +Destroys the Charconv Plug-in interface implementation specified by iDtor_ID_Key
1.238 +*/
1.239 + virtual ~CCharacterSetConverterPluginInterface()
1.240 + {
1.241 + REComSession::DestroyedImplementation(iDtor_ID_Key);
1.242 + };
1.243 +
1.244 +
1.245 +private:
1.246 +
1.247 + TUid iDtor_ID_Key;
1.248 +
1.249 + };
1.250 +
1.251 +
1.252 +#endif //__CHARACTERSETCONVERTER_H__
1.253 +