1 /*

     2 * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 #if !defined(__CHARACTERSETCONVERTER_H__)

    20 #define __CHARACTERSETCONVERTER_H__

    21 

    22 #include <e32base.h>

    23 #include <ecom/ecom.h>

    24 

    25 /**

    26 This constant holds the UID of the CharConv Character Set Conversion 

    27 ECOM Interface.

    28 @publishedAll

    29 @released

    30 */

    31 const TUid KCharacterSetConvertorInterfaceUid = {0x101F7F1D};

    32 

    33 /**

    34 This is the base class defining the methods in the CharConv Character Set

    35 Conversion plugin interface. CharConv plugin suppliers would define 

    36 implementation classes inheriting from this interface class to add additional

    37 character set support to CharConv.

    38 @publishedAll

    39 @released

    40 */

    41 NONSHARABLE_CLASS(CCharacterSetConverterPluginInterface) : public CBase

    42 	{

    43 

    44 public:

    45 

    46 /**

    47  *

    48  * A function prototype which must be implemented by a character

    49  * conversion plug-in DLL to return the character (represented by one or

    50  * more byte values) which is used by default as the replacement for

    51  * unconvertible Unicode characters.

    52  *

    53  * This character is used when converting from Unicode into a foreign

    54  * character set, if there is no equivalent for the Unicode character in

    55  * the foreign character set. The default replacement character can be

    56  * overriden by a call to <code>CCnvCharacterSetConverter::SetReplacemen-

    57  * tForUnconvertibleUnicodeCharactersL()</code>.This function is exported

    58  * at ordinal position 1 in the plug-in DLL. It is called by <code>CCnvC-

    59  * haracterSetConverter::PrepareToConvertToOrFromL()</code>.To implement

    60  * this function, you should #include convgeneratedcpp.h in the cpp file.

    61  * This gives access to the

    62  * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code>

    63  * function. This function can then be implemented by calling

    64  * <code>ReplacementForUnconvertibleUnicodeCharacters_internal()</code>.

    65  *

    66  * @since     6.0

    67  * @return   " const TDesC8& "

    68  *            The single character which is to be used to replace

    69  *            unconvertible characters.

    70  */

    71 	virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters() = 0;

    72 

    73 /**

    74  *

    75  * A function prototype which must be implemented by a character

    76  * conversion plug-in DLL to convert from Unicode into a foreign

    77  * character set.

    78  *

    79  * This function is exported at ordinal position 2 in the plug-in DLL. It

    80  * is called by

    81  * <code>CCnvCharacterSetConverter::ConvertFromUnicode()</code>.For many

    82  * non-complex character sets, the implementation of this function is

    83  * trivial. Include convgeneratedcpp.h in the .cpp file to get access to

    84  * the <code>SCnvConversionData</code> object called

    85  * <code>conversionData</code>. Then call

    86  * <code>CCnvCharacterSetConverter::DoConvertFromUnicode()</code>

    87  * specifying <code>conversionData</code> as the first argument and

    88  * passing in all parameters unchanged.For complex character sets, you

    89  * need to create an array of character conversion data objects

    90  * (<code>CnvUtilities::SCharacterSet</code>s), then call

    91  * <code>CnvUtilities::ConvertFromUnicode()</code>.

    92  *

    93  * @since     6.0

    94  * @param     " CCnvCharacterSetConverter::TEndianness

    95 		  aDefaultEndiannessOfForeignCharacters "

    96  *            The default endian-ness to use when writing the

    97  *            characters in the foreign character set.

    98  * @param     " const TDesC8& aReplacementForUnconvertibleUnicodeCharacters

    99 		  "

   100  *            The single character which is used to replace

   101  *            unconvertible characters.

   102  * @param     " TDes8& aForeign "

   103  *            On return, contains the converted text in the target

   104  *            non-Unicode character set.

   105  * @param     " const TDesC16& aUnicode "

   106  *            The source Unicode text to be converted.

   107  * @param     " CCnvCharacterSetConverter::TArrayOfAscendingIndices&

   108 		  aIndicesOfUnconvertibleCharacters "

   109  *            A buffer which on return holds the indices of each

   110  *            Unicode character in the source text which could not

   111  *            be converted (because the target character set does

   112  *            not have an equivalent character).

   113  * @return   " TInt "

   114  *            The number of unconverted characters left at the end

   115  *            of the input descriptor (e.g. because

   116  *            <code>aForeign</code> was not long enough to hold all

   117  *            the text), or a negative error value, as defined in

   118  *            <code>TError</code>.

   119  */

   120 	virtual TInt ConvertFromUnicode(

   121 		CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

   122 		const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, 

   123 		TDes8& aForeign, 

   124 		const TDesC16& aUnicode, 

   125 		CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) = 0;

   126 

   127 /**

   128  *

   129  * A function prototype which must be implemented by a character

   130  * conversion plug-in DLL to convert from a foreign character set into

   131  * Unicode.

   132  *

   133  * This function is exported at ordinal position 3 in the plug-in DLL. It

   134  * is called by

   135  * <code>CCnvCharacterSetConverter::ConvertToUnicode()</code>.For many

   136  * non-complex character sets, the implementation of this function is

   137  * trivial. Include convgeneratedcpp.h in the .cpp file to get access to

   138  * the <code>SCnvConversionData</code> object called

   139  * <code>conversionData</code>. Then call

   140  * <code>CCnvCharacterSetConverter::DoConvertToUnicode()</code>

   141  * specifying <code>conversionData</code> as the first argument and

   142  * passing in all other parameters unchanged.For complex character sets,

   143  * you need to create an array of character conversion methods

   144  * (<code>CnvUtilities::SMethod</code>s or

   145  * <code>CnvUtilities::SState</code>s, depending on whether the complex

   146  * character set encoding is modal or not), then call

   147  * <code>CnvUtilities::ConvertToUnicodeFromHeterogeneousForeign()</code>

   148  * or <code>CnvUtilities::ConvertToUnicodeFromModalForeign()</code>.

   149  *

   150  * @since     6.0

   151  * @param     " CCnvCharacterSetConverter::TEndianness

   152 		  aDefaultEndiannessOfForeignCharacters "

   153  *            The default endian-ness to use when reading characters

   154  *            in the foreign character set.

   155  * @param     " TDes16& aUnicode "

   156  *            On return, contains the text converted into Unicode.

   157  * @param     " const TDesC8& aForeign "

   158  *            The non-Unicode source text to be converted.

   159  * @param     " TInt& aState "

   160  *            Used to save state information across multiple calls

   161  *            to <code>ConvertToUnicode()</code>.

   162  * @param     " TInt& aNumberOfUnconvertibleCharacters "

   163  *            On return, contains the number of bytes which were not

   164  *            converted.

   165  * @param     " TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter "

   166  *            On return, contains the index of the first bytein the

   167  *            input text that could not be converted. A negative

   168  *            value indicates that all the characters were

   169  *            converted.

   170  * @return   " TInt "

   171  *            The number of unconverted bytes left at the end of the

   172  *            input descriptor (e.g. because the output descriptor

   173  *            is not long enough to hold all the text), or one of

   174  *            the error values defined in <code>TError</code>.

   175  */

   176 	virtual TInt ConvertToUnicode(

   177 		CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

   178 		TDes16& aUnicode, 

   179 		const TDesC8& aForeign, 

   180 		TInt& aState, 

   181 		TInt& aNumberOfUnconvertibleCharacters, 

   182 		TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) = 0;

   183 

   184 /**

   185  *

   186  * A function which must be implemented by a character conversion plug-in

   187  * DLL to calculate how probable it is that a sample piece of text is

   188  * encoded in this character set.

   189  *

   190  * This function was added in 6.1 as the 4th-ordinal exported function in

   191  * the plug-in DLL interface. It is called by

   192  * <code>CCnvCharacterSetConverter::AutoDetectCharacterSetL()</code> for

   193  * each character conversion plug-in DLL.

   194  *

   195  * @since     6.1

   196  * @param     "  TBool& aSetToTrue"

   197  *            This value should be set to <code>ETrue</code>. It is

   198  *            used to indicate to <code>CCnvCharacterSetConverter::-

   199  *            AutoDetectCharacterSetL()</code> that the plug-in DLL

   200  *            is implementing a function of this signature and is

   201  *            therefore not the empty, reserved function that was

   202  *            previously exported at the 4th ordinal position in the

   203  *            plug-in DLL in v6.0.

   204  * @param     "TInt& aConfidenceLevel"

   205  *            On return, indicates how confident the function is

   206  *            about its return value. Set to a value between 0 and

   207  *            100. Zero indicates no confidence, (and the return

   208  *            value should be disregarded), 100 indicates total

   209  *            confidence.

   210  * @param     "const TDesC8& aSample"

   211  *            The sample text string, as passed to <code>CCnvCharac-

   212  *            terSetConverter::AutoDetectCharacterSetL()</code>.

   213  * @return   "TBool"

   214  *            <code>ETrue</code> if it is more probable that the

   215  *            sample text is encoded in this character set than not.

   216  *            <code>EFalse</code> if it is more probable that the

   217  *            sample text is not encoded in this character set. The

   218  *            confidence level applies to this value.

   219  */

   220 	virtual TBool IsInThisCharacterSetL(

   221 		TBool& aSetToTrue, 

   222 		TInt& aConfidenceLevel, 

   223 		const TDesC8& aSample) = 0;

   224 

   225 	static CCharacterSetConverterPluginInterface* NewL(TUid aInterfaceImplUid)

   226 		{

   227 		return reinterpret_cast <CCharacterSetConverterPluginInterface*> (

   228 			REComSession::CreateImplementationL(

   229 			aInterfaceImplUid,

   230 			_FOFF(CCharacterSetConverterPluginInterface, iDtor_ID_Key))); 

   231 		};

   232 	

   233 /**

   234 Destroys the Charconv Plug-in interface implementation specified by iDtor_ID_Key

   235 */

   236 	virtual ~CCharacterSetConverterPluginInterface()

   237 		{

   238 		REComSession::DestroyedImplementation(iDtor_ID_Key);

   239 		};

   240 	

   241 

   242 private:

   243 

   244 	TUid iDtor_ID_Key;

   245 

   246 	};

   247 

   248 

   249 #endif //__CHARACTERSETCONVERTER_H__

   250