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