1 /*

     2 * Copyright (c) 2004 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 

    20 #if !defined(__CHARACTERSETCONVERTER_H__)

    21 #define __CHARACTERSETCONVERTER_H__

    22 

    23 #include <e32base.h>

    24 #include <ecom/eCom.h>

    25 

    26 /**

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

    28 ECOM Interface.

    29 @publishedAll

    30 @released

    31 */

    32 const TUid KCharacterSetConvertorInterfaceUid = {0x101F7F1D};

    33 

    34 /**

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

    36 Conversion plugin interface. CharConv plugin suppliers would define 

    37 implementation classes inheriting from this interface class to add additional

    38 character set support to CharConv.

    39 @publishedAll

    40 @released

    41 */

    42 NONSHARABLE_CLASS(CCharacterSetConverterPluginInterface) : public CBase

    43 	{

    44 

    45 public:

    46 

    47 /**

    48  *

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

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

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

    52  * unconvertible Unicode characters.

    53  *

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

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

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

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

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

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

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

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

    62  * This gives access to the

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

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

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

    66  *

    67  * @since     6.0

    68  * @return   " const TDesC8& "

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

    70  *            unconvertible characters.

    71  */

    72 	virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters() = 0;

    73 

    74 /**

    75  *

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

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

    78  * character set.

    79  *

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

    81  * is called by

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

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

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

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

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

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

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

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

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

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

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

    93  *

    94  * @since     6.0

    95  * @param     " CCnvCharacterSetConverter::TEndianness

    96 		  aDefaultEndiannessOfForeignCharacters "

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

    98  *            characters in the foreign character set.

    99  * @param     " const TDesC8& aReplacementForUnconvertibleUnicodeCharacters

   100 		  "

   101  *            The single character which is used to replace

   102  *            unconvertible characters.

   103  * @param     " TDes8& aForeign "

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

   105  *            non-Unicode character set.

   106  * @param     " const TDesC16& aUnicode "

   107  *            The source Unicode text to be converted.

   108  * @param     " CCnvCharacterSetConverter::TArrayOfAscendingIndices&

   109 		  aIndicesOfUnconvertibleCharacters "

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

   111  *            Unicode character in the source text which could not

   112  *            be converted (because the target character set does

   113  *            not have an equivalent character).

   114  * @return   " TInt "

   115  *            The number of unconverted characters left at the end

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

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

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

   119  *            <code>TError</code>.

   120  */

   121 	virtual TInt ConvertFromUnicode(

   122 		CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

   123 		const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, 

   124 		TDes8& aForeign, 

   125 		const TDesC16& aUnicode, 

   126 		CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) = 0;

   127 

   128 /**

   129  *

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

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

   132  * Unicode.

   133  *

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

   135  * is called by

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   150  *

   151  * @since     6.0

   152  * @param     " CCnvCharacterSetConverter::TEndianness

   153 		  aDefaultEndiannessOfForeignCharacters "

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

   155  *            in the foreign character set.

   156  * @param     " TDes16& aUnicode "

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

   158  * @param     " const TDesC8& aForeign "

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

   160  * @param     " TInt& aState "

   161  *            Used to save state information across multiple calls

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

   163  * @param     " TInt& aNumberOfUnconvertibleCharacters "

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

   165  *            converted.

   166  * @param     " TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter "

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

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

   169  *            value indicates that all the characters were

   170  *            converted.

   171  * @return   " TInt "

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

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

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

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

   176  */

   177 	virtual TInt ConvertToUnicode(

   178 		CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, 

   179 		TDes16& aUnicode, 

   180 		const TDesC8& aForeign, 

   181 		TInt& aState, 

   182 		TInt& aNumberOfUnconvertibleCharacters, 

   183 		TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) = 0;

   184 

   185 /**

   186  *

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

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

   189  * encoded in this character set.

   190  *

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

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

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

   194  * each character conversion plug-in DLL.

   195  *

   196  * @since     6.1

   197  * @param     "  TBool& aSetToTrue"

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

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

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

   201  *            is implementing a function of this signature and is

   202  *            therefore not the empty, reserved function that was

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

   204  *            plug-in DLL in v6.0.

   205  * @param     "TInt& aConfidenceLevel"

   206  *            On return, indicates how confident the function is

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

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

   209  *            value should be disregarded), 100 indicates total

   210  *            confidence.

   211  * @param     "const TDesC8& aSample"

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

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

   214  * @return   "TBool"

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

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

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

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

   219  *            confidence level applies to this value.

   220  */

   221 	virtual TBool IsInThisCharacterSetL(

   222 		TBool& aSetToTrue, 

   223 		TInt& aConfidenceLevel, 

   224 		const TDesC8& aSample) = 0;

   225 

   226 	static CCharacterSetConverterPluginInterface* NewL(TUid aInterfaceImplUid);

   227 

   228 	virtual ~CCharacterSetConverterPluginInterface();

   229 

   230 private:

   231 

   232 	TUid iDtor_ID_Key;

   233 

   234 	};

   235 

   236 #include <CharacterSetConverter.inl>

   237 

   238 #endif //__CHARACTERSETCONVERTER_H__

   239