williamr@4: /* williamr@4: * Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: williamr@4: * williamr@4: */ williamr@4: williamr@2: williamr@2: #if !defined(__CONVUTILS_H__) williamr@2: #define __CONVUTILS_H__ williamr@2: williamr@2: #if !defined(__E32STD_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #if !defined(__E32BASE_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #if !defined(__CHARCONV_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: struct SCnvConversionData; williamr@2: williamr@2: williamr@2: class CnvUtilities williamr@2: /** williamr@2: Provides static character conversion utilities for complex encodings. Its functions williamr@2: may be called from a plug-in DLL's implementation of ConvertFromUnicode() williamr@2: and ConvertToUnicode(). williamr@2: williamr@2: These utility functions are provided for use when converting to/from complex williamr@2: character set encodings, including modal encodings. Modal encodings are those williamr@2: where the interpretation of a given byte of data is dependent on the current williamr@2: mode; mode changing is performed by escape sequences which occur in the byte williamr@2: stream. A non-modal complex encoding is one in which characters are encoded williamr@2: using variable numbers of bytes. The number of bytes used to encode a character williamr@2: depends on the value of the initial byte. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: // type definitions for converting from Unicode williamr@2: williamr@2: /** A pointer to a function which "mangles" text when converting from williamr@2: Unicode into a complex modal or non-modal foreign character set williamr@2: encoding. williamr@2: williamr@2: It might insert a shifting character, escape sequence, or other williamr@2: special characters.If the target character set encoding is modal, the williamr@2: implementation of this function may call the williamr@2: CnvUtilities::ConvertFromIntermediateBufferInPlace() williamr@2: utility function which is provided because many modal character sets williamr@2: require an identical implementation of this function. williamr@2: williamr@2: " convutils.lib " */ williamr@2: typedef void (*FConvertFromIntermediateBufferInPlace)(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut); williamr@2: struct SCharacterSet williamr@2: /** Stores information about a non-Unicode character set. The information williamr@2: is used to locate the conversion information required by williamr@2: ConvertFromUnicode() and ConvertToUnicode(). williamr@2: williamr@2: An array of these structs that contains all available character sets williamr@2: can be generated by CreateArrayOfCharacterSetsAvailableLC() and williamr@2: CreateArrayOfCharacterSetsAvailableL(), and is used by one of the williamr@2: overloads of PrepareToConvertToOrFromL(). */ williamr@2: { williamr@2: /** The conversion data. */ williamr@2: const SCnvConversionData* iConversionData; // must *not* be set to NULL williamr@2: /** A pointer to a function which "mangles" the text in a way williamr@2: appropriate to the target complex character set. For instance it williamr@2: might insert a shifting character, escape sequence, or other special williamr@2: characters. */ williamr@2: FConvertFromIntermediateBufferInPlace iConvertFromIntermediateBufferInPlace; // must *not* be set to NULL williamr@2: /** The escape sequence which introduces the character set, i.e. it williamr@2: identifies this character set as the next one to use. Must not be NULL. williamr@2: If the character set is non-modal, this should be set to an empty williamr@2: descriptor. */ williamr@2: const TDesC8* iEscapeSequence; // must *not* be set to NULL williamr@2: }; williamr@2: // type definitions for converting to Unicode williamr@2: williamr@2: /** A pointer to a function which calculates the number of consecutive williamr@2: bytes in the remainder of the foreign descriptor which can be williamr@2: converted using the current character set's conversion data. williamr@2: williamr@2: Called when converting from a non-modal complex character set encoding williamr@2: into Unicode. It may return a negative williamr@2: CCnvCharacterSetConverter::TError value to indicate an williamr@2: error in the encoding. williamr@2: williamr@2: " convutils.lib " */ williamr@2: typedef TInt (*FNumberOfBytesAbleToConvert)(const TDesC8& aDescriptor); // may return negative CCnvCharacterSetConverter::TError values williamr@2: williamr@2: /** A pointer to a function which prepares the text for conversion into williamr@2: Unicode. williamr@2: williamr@2: For instance it might remove any shifting or other special characters. williamr@2: Called when converting from a non-modal complex character set encoding williamr@2: into Unicode. williamr@2: williamr@2: " convutils.lib " */ williamr@2: typedef void (*FConvertToIntermediateBufferInPlace)(TDes8& aDescriptor); williamr@2: williamr@2: struct SState williamr@2: /** Character conversion data for one of the character sets which is williamr@2: specified in a modal character set encoding. An array of these structs williamr@2: is used when converting from a modal character set into Unicode, using williamr@2: CnvUtilities::ConvertToUnicodeFromModalForeign(). Neither of the members williamr@2: may be NULL. */ williamr@2: { williamr@2: /** The escape sequence which introduces the character set, i.e. it williamr@2: identifies this character set as the next one to use. This must begin williamr@2: with KControlCharacterEscape. */ williamr@2: const TDesC8* iEscapeSequence; // must *not* be set to NULL and must begin with 0x1b williamr@2: /** The conversion data. */ williamr@2: const SCnvConversionData* iConversionData; // must *not* be set to NULL williamr@2: }; williamr@2: struct SMethod williamr@2: { williamr@2: /** A pointer to a function which calculates the number of consecutive williamr@2: bytes in the remainder of the foreign descriptor which can be converted williamr@2: using the current character set's conversion data. It may return a williamr@2: negative CCnvCharacterSetConverter::TError value to indicate an error williamr@2: in the encoding. */ williamr@2: FNumberOfBytesAbleToConvert iNumberOfBytesAbleToConvert; // must *not* be set to NULL williamr@2: /** A pointer to a function which prepares the text for conversion williamr@2: into Unicode. For instance it might remove any shifting or other williamr@2: special characters. */ williamr@2: FConvertToIntermediateBufferInPlace iConvertToIntermediateBufferInPlace; // must *not* be set to NULL williamr@2: /** The conversion data. */ williamr@2: const SCnvConversionData* iConversionData; // must *not* be set to NULL williamr@2: /** The number of bytes per character. */ williamr@2: TInt16 iNumberOfBytesPerCharacter; williamr@2: /** The number of core bytes per character. */ williamr@2: TInt16 iNumberOfCoreBytesPerCharacter; williamr@2: }; williamr@2: public: williamr@2: // these functions may *not* have CCnvCharacterSetConverter::EInputConversionFlagStopAtFirstUnconvertibleCharacter set in aInputConversionFlags williamr@2: IMPORT_C static TInt ConvertFromUnicode(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, TDes8& aForeign, const TDesC16& aUnicode, CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters, const TArray& aArrayOfCharacterSets); williamr@2: IMPORT_C static TInt ConvertFromUnicode(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, TDes8& aForeign, const TDesC16& aUnicode, CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters, const TArray& aArrayOfCharacterSets, TUint& aOutputConversionFlags, TUint aInputConversionFlags); williamr@2: IMPORT_C static void ConvertFromIntermediateBufferInPlace(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut, const TDesC8& aEscapeSequence, TInt aNumberOfBytesPerCharacter); williamr@2: IMPORT_C static TInt ConvertToUnicodeFromModalForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aState, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray& aArrayOfStates); // the first element of aArrayOfStates is taken to be the default state williamr@2: IMPORT_C static TInt ConvertToUnicodeFromModalForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aState, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray& aArrayOfStates, TUint& aOutputConversionFlags, TUint aInputConversionFlags); // the first element of aArrayOfStates is taken to be the default state williamr@2: IMPORT_C static TInt ConvertToUnicodeFromHeterogeneousForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray& aArrayOfMethods); williamr@2: IMPORT_C static TInt ConvertToUnicodeFromHeterogeneousForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray& aArrayOfMethods, TUint& aOutputConversionFlags, TUint aInputConversionFlags); williamr@2: private: williamr@2: static void CheckArrayOfCharacterSets(const TArray& aArrayOfCharacterSets); williamr@2: static void CheckArrayOfStates(const TArray& aArrayOfStates); williamr@2: static void CheckArrayOfMethods(const TArray& aArrayOfMethods); williamr@2: static TInt LengthOfUnicodeCharacter(const TDesC16& aUnicode, TInt aIndex); williamr@2: static TBool NextHomogeneousForeignRun(const SCnvConversionData*& aConversionData, TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TArray& aArrayOfStates, TUint& aOutputConversionFlags); williamr@2: static TBool MatchesEscapeSequence(TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TDesC8& aEscapeSequence); williamr@2: static TBool IsStartOf(const TDesC8& aStart, const TDesC8& aPotentiallyLongerDescriptor); williamr@2: inline static TInt ReduceToNearestMultipleOf(TInt aNumber1, TInt aNumber2) {return (aNumber1/aNumber2)*aNumber2;} williamr@2: }; williamr@2: williamr@2: #endif williamr@4: