sl@0: /* sl@0: * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: * All rights reserved. sl@0: * This component and the accompanying materials are made available sl@0: * under the terms of "Eclipse Public License v1.0" sl@0: * which accompanies this distribution, and is available sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: * sl@0: * Initial Contributors: sl@0: * Nokia Corporation - initial contribution. sl@0: * sl@0: * Contributors: sl@0: * sl@0: * Description: sl@0: * sl@0: */ sl@0: sl@0: sl@0: #if !defined(__CHARACTERSETCONVERTER_H__) sl@0: #define __CHARACTERSETCONVERTER_H__ sl@0: sl@0: #include sl@0: #include sl@0: sl@0: /** sl@0: This constant holds the UID of the CharConv Character Set Conversion sl@0: ECOM Interface. sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: const TUid KCharacterSetConvertorInterfaceUid = {0x101F7F1D}; sl@0: sl@0: /** sl@0: This is the base class defining the methods in the CharConv Character Set sl@0: Conversion plugin interface. CharConv plugin suppliers would define sl@0: implementation classes inheriting from this interface class to add additional sl@0: character set support to CharConv. sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: NONSHARABLE_CLASS(CCharacterSetConverterPluginInterface) : public CBase sl@0: { sl@0: sl@0: public: sl@0: sl@0: /** sl@0: * sl@0: * A function prototype which must be implemented by a character sl@0: * conversion plug-in DLL to return the character (represented by one or sl@0: * more byte values) which is used by default as the replacement for sl@0: * unconvertible Unicode characters. sl@0: * sl@0: * This character is used when converting from Unicode into a foreign sl@0: * character set, if there is no equivalent for the Unicode character in sl@0: * the foreign character set. The default replacement character can be sl@0: * overriden by a call to CCnvCharacterSetConverter::SetReplacemen- sl@0: * tForUnconvertibleUnicodeCharactersL().This function is exported sl@0: * at ordinal position 1 in the plug-in DLL. It is called by CCnvC- sl@0: * haracterSetConverter::PrepareToConvertToOrFromL().To implement sl@0: * this function, you should #include convgeneratedcpp.h in the cpp file. sl@0: * This gives access to the sl@0: * ReplacementForUnconvertibleUnicodeCharacters_internal() sl@0: * function. This function can then be implemented by calling sl@0: * ReplacementForUnconvertibleUnicodeCharacters_internal(). sl@0: * sl@0: * @since 6.0 sl@0: * @return " const TDesC8& " sl@0: * The single character which is to be used to replace sl@0: * unconvertible characters. sl@0: */ sl@0: virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters() = 0; sl@0: sl@0: /** sl@0: * sl@0: * A function prototype which must be implemented by a character sl@0: * conversion plug-in DLL to convert from Unicode into a foreign sl@0: * character set. sl@0: * sl@0: * This function is exported at ordinal position 2 in the plug-in DLL. It sl@0: * is called by sl@0: * CCnvCharacterSetConverter::ConvertFromUnicode().For many sl@0: * non-complex character sets, the implementation of this function is sl@0: * trivial. Include convgeneratedcpp.h in the .cpp file to get access to sl@0: * the SCnvConversionData object called sl@0: * conversionData. Then call sl@0: * CCnvCharacterSetConverter::DoConvertFromUnicode() sl@0: * specifying conversionData as the first argument and sl@0: * passing in all parameters unchanged.For complex character sets, you sl@0: * need to create an array of character conversion data objects sl@0: * (CnvUtilities::SCharacterSets), then call sl@0: * CnvUtilities::ConvertFromUnicode(). sl@0: * sl@0: * @since 6.0 sl@0: * @param " CCnvCharacterSetConverter::TEndianness sl@0: aDefaultEndiannessOfForeignCharacters " sl@0: * The default endian-ness to use when writing the sl@0: * characters in the foreign character set. sl@0: * @param " const TDesC8& aReplacementForUnconvertibleUnicodeCharacters sl@0: " sl@0: * The single character which is used to replace sl@0: * unconvertible characters. sl@0: * @param " TDes8& aForeign " sl@0: * On return, contains the converted text in the target sl@0: * non-Unicode character set. sl@0: * @param " const TDesC16& aUnicode " sl@0: * The source Unicode text to be converted. sl@0: * @param " CCnvCharacterSetConverter::TArrayOfAscendingIndices& sl@0: aIndicesOfUnconvertibleCharacters " sl@0: * A buffer which on return holds the indices of each sl@0: * Unicode character in the source text which could not sl@0: * be converted (because the target character set does sl@0: * not have an equivalent character). sl@0: * @return " TInt " sl@0: * The number of unconverted characters left at the end sl@0: * of the input descriptor (e.g. because sl@0: * aForeign was not long enough to hold all sl@0: * the text), or a negative error value, as defined in sl@0: * TError. sl@0: */ sl@0: virtual TInt ConvertFromUnicode( sl@0: CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, sl@0: const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, sl@0: TDes8& aForeign, sl@0: const TDesC16& aUnicode, sl@0: CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) = 0; sl@0: sl@0: /** sl@0: * sl@0: * A function prototype which must be implemented by a character sl@0: * conversion plug-in DLL to convert from a foreign character set into sl@0: * Unicode. sl@0: * sl@0: * This function is exported at ordinal position 3 in the plug-in DLL. It sl@0: * is called by sl@0: * CCnvCharacterSetConverter::ConvertToUnicode().For many sl@0: * non-complex character sets, the implementation of this function is sl@0: * trivial. Include convgeneratedcpp.h in the .cpp file to get access to sl@0: * the SCnvConversionData object called sl@0: * conversionData. Then call sl@0: * CCnvCharacterSetConverter::DoConvertToUnicode() sl@0: * specifying conversionData as the first argument and sl@0: * passing in all other parameters unchanged.For complex character sets, sl@0: * you need to create an array of character conversion methods sl@0: * (CnvUtilities::SMethods or sl@0: * CnvUtilities::SStates, depending on whether the complex sl@0: * character set encoding is modal or not), then call sl@0: * CnvUtilities::ConvertToUnicodeFromHeterogeneousForeign() sl@0: * or CnvUtilities::ConvertToUnicodeFromModalForeign(). sl@0: * sl@0: * @since 6.0 sl@0: * @param " CCnvCharacterSetConverter::TEndianness sl@0: aDefaultEndiannessOfForeignCharacters " sl@0: * The default endian-ness to use when reading characters sl@0: * in the foreign character set. sl@0: * @param " TDes16& aUnicode " sl@0: * On return, contains the text converted into Unicode. sl@0: * @param " const TDesC8& aForeign " sl@0: * The non-Unicode source text to be converted. sl@0: * @param " TInt& aState " sl@0: * Used to save state information across multiple calls sl@0: * to ConvertToUnicode(). sl@0: * @param " TInt& aNumberOfUnconvertibleCharacters " sl@0: * On return, contains the number of bytes which were not sl@0: * converted. sl@0: * @param " TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter " sl@0: * On return, contains the index of the first bytein the sl@0: * input text that could not be converted. A negative sl@0: * value indicates that all the characters were sl@0: * converted. sl@0: * @return " TInt " sl@0: * The number of unconverted bytes left at the end of the sl@0: * input descriptor (e.g. because the output descriptor sl@0: * is not long enough to hold all the text), or one of sl@0: * the error values defined in TError. sl@0: */ sl@0: virtual TInt ConvertToUnicode( sl@0: CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, sl@0: TDes16& aUnicode, sl@0: const TDesC8& aForeign, sl@0: TInt& aState, sl@0: TInt& aNumberOfUnconvertibleCharacters, sl@0: TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) = 0; sl@0: sl@0: /** sl@0: * sl@0: * A function which must be implemented by a character conversion plug-in sl@0: * DLL to calculate how probable it is that a sample piece of text is sl@0: * encoded in this character set. sl@0: * sl@0: * This function was added in 6.1 as the 4th-ordinal exported function in sl@0: * the plug-in DLL interface. It is called by sl@0: * CCnvCharacterSetConverter::AutoDetectCharacterSetL() for sl@0: * each character conversion plug-in DLL. sl@0: * sl@0: * @since 6.1 sl@0: * @param " TBool& aSetToTrue" sl@0: * This value should be set to ETrue. It is sl@0: * used to indicate to CCnvCharacterSetConverter::- sl@0: * AutoDetectCharacterSetL() that the plug-in DLL sl@0: * is implementing a function of this signature and is sl@0: * therefore not the empty, reserved function that was sl@0: * previously exported at the 4th ordinal position in the sl@0: * plug-in DLL in v6.0. sl@0: * @param "TInt& aConfidenceLevel" sl@0: * On return, indicates how confident the function is sl@0: * about its return value. Set to a value between 0 and sl@0: * 100. Zero indicates no confidence, (and the return sl@0: * value should be disregarded), 100 indicates total sl@0: * confidence. sl@0: * @param "const TDesC8& aSample" sl@0: * The sample text string, as passed to CCnvCharac- sl@0: * terSetConverter::AutoDetectCharacterSetL(). sl@0: * @return "TBool" sl@0: * ETrue if it is more probable that the sl@0: * sample text is encoded in this character set than not. sl@0: * EFalse if it is more probable that the sl@0: * sample text is not encoded in this character set. The sl@0: * confidence level applies to this value. sl@0: */ sl@0: virtual TBool IsInThisCharacterSetL( sl@0: TBool& aSetToTrue, sl@0: TInt& aConfidenceLevel, sl@0: const TDesC8& aSample) = 0; sl@0: sl@0: static CCharacterSetConverterPluginInterface* NewL(TUid aInterfaceImplUid) sl@0: { sl@0: return reinterpret_cast ( sl@0: REComSession::CreateImplementationL( sl@0: aInterfaceImplUid, sl@0: _FOFF(CCharacterSetConverterPluginInterface, iDtor_ID_Key))); sl@0: }; sl@0: sl@0: /** sl@0: Destroys the Charconv Plug-in interface implementation specified by iDtor_ID_Key sl@0: */ sl@0: virtual ~CCharacterSetConverterPluginInterface() sl@0: { sl@0: REComSession::DestroyedImplementation(iDtor_ID_Key); sl@0: }; sl@0: sl@0: sl@0: private: sl@0: sl@0: TUid iDtor_ID_Key; sl@0: sl@0: }; sl@0: sl@0: sl@0: #endif //__CHARACTERSETCONVERTER_H__ sl@0: