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