1 convutils.h

     1 // Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #if !defined(__CONVUTILS_H__)

    17 #define __CONVUTILS_H__

    18 

    19 #if !defined(__E32STD_H__)

    20 #include <e32std.h>

    21 #endif

    22 

    23 #if !defined(__E32BASE_H__)

    24 #include <e32base.h>

    25 #endif

    26 

    27 #if !defined(__CHARCONV_H__)

    28 #include <charconv.h>

    29 #endif

    30 

    31 struct SCnvConversionData;

    32 

    33  

    34 class CnvUtilities

    35 /** 

    36 Provides static character conversion utilities for complex encodings. Its functions 

    37 may be called from a plug-in DLL's implementation of ConvertFromUnicode() 

    38 and ConvertToUnicode().

    39 

    40 These utility functions are provided for use when converting to/from complex 

    41 character set encodings, including modal encodings. Modal encodings are those 

    42 where the interpretation of a given byte of data is dependent on the current 

    43 mode; mode changing is performed by escape sequences which occur in the byte 

    44 stream. A non-modal complex encoding is one in which characters are encoded 

    45 using variable numbers of bytes. The number of bytes used to encode a character 

    46 depends on the value of the initial byte.

    47 @publishedAll 

    48 @released

    49 */

    50 	{

    51 public:

    52 	// type definitions for converting from Unicode

    53 	

    54 	/**  A pointer to a function which "mangles" text when converting from

    55 	Unicode into a complex modal or non-modal foreign character set

    56 	encoding.

    57 

    58 	It might insert a shifting character, escape sequence, or other

    59 	special characters.If the target character set encoding is modal, the

    60 	implementation of this function may call the

    61 	CnvUtilities::ConvertFromIntermediateBufferInPlace()

    62 	utility function which is provided because many modal character sets

    63 	require an identical implementation of this function.

    64 

    65 	" convutils.lib " */

    66     typedef void (*FConvertFromIntermediateBufferInPlace)(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut);

    67 	struct SCharacterSet

    68 	/** Stores information about a non-Unicode character set. The information 

    69 	is used to locate the conversion information required by 

    70 	ConvertFromUnicode() and ConvertToUnicode().

    71 

    72 	An array of these structs  that contains all available character sets  

    73 	can be generated by CreateArrayOfCharacterSetsAvailableLC() and 

    74 	CreateArrayOfCharacterSetsAvailableL(), and is used by one of the 

    75 	overloads of PrepareToConvertToOrFromL(). */

    76 		{

    77 		/** The conversion data. */

    78 		const SCnvConversionData* iConversionData; // must *not* be set to NULL

    79 		/** A pointer to a function which "mangles" the text in a way 

    80 		appropriate to the target complex character set. For instance it 

    81 		might insert a shifting character, escape sequence, or other special 

    82 		characters. */

    83 		FConvertFromIntermediateBufferInPlace iConvertFromIntermediateBufferInPlace; // must *not* be set to NULL

    84 		/** The escape sequence which introduces the character set, i.e. it 

    85 		identifies this character set as the next one to use. Must not be NULL.

    86 		If the character set is non-modal, this should be set to an empty 

    87 		descriptor. */

    88 		const TDesC8* iEscapeSequence; // must *not* be set to NULL

    89 		};

    90 	// type definitions for converting to Unicode

    91 

    92 	/** A pointer to a function which calculates the number of consecutive

    93 	bytes in the remainder of the foreign descriptor which can be

    94 	converted using the current character set's conversion data.

    95 

    96 	Called when converting from a non-modal complex character set encoding

    97 	into Unicode. It may return a negative

    98 	CCnvCharacterSetConverter::TError value to indicate an

    99 	error in the encoding.

   100 

   101 	" convutils.lib " */

   102 	typedef TInt (*FNumberOfBytesAbleToConvert)(const TDesC8& aDescriptor); // may return negative CCnvCharacterSetConverter::TError values

   103 	

   104 	/** A pointer to a function which prepares the text for conversion into

   105 	Unicode.

   106 

   107 	For instance it might remove any shifting or other special characters.

   108 	Called when converting from a non-modal complex character set encoding

   109 	into Unicode.

   110 

   111 	" convutils.lib " */

   112  	typedef void (*FConvertToIntermediateBufferInPlace)(TDes8& aDescriptor);

   113 

   114 	struct SState

   115 	/** Character conversion data for one of the character sets which is 

   116 	specified in a modal character set encoding. An array of these structs 

   117 	is used when converting from a modal character set into Unicode, using 

   118 	CnvUtilities::ConvertToUnicodeFromModalForeign(). Neither of the members 

   119 	may be NULL. */

   120 		{

   121 		/** The escape sequence which introduces the character set, i.e. it 

   122 		identifies this character set as the next one to use. This must begin 

   123 		with KControlCharacterEscape. */

   124 		const TDesC8* iEscapeSequence; // must *not* be set to NULL and must begin with 0x1b

   125 		/** The conversion data. */

   126 		const SCnvConversionData* iConversionData; // must *not* be set to NULL

   127 		};

   128 	struct SMethod

   129 		{

   130 		/** A pointer to a function which calculates the number of consecutive 

   131 		bytes in the remainder of the foreign descriptor which can be converted 

   132 		using the current character set's conversion data. It may return a 

   133 		negative CCnvCharacterSetConverter::TError value to indicate an error 

   134 		in the encoding. */

   135 		FNumberOfBytesAbleToConvert iNumberOfBytesAbleToConvert; // must *not* be set to NULL

   136 		/** A pointer to a function which prepares the text for conversion 

   137 		into Unicode. For instance it might remove any shifting or other 

   138 		special characters. */

   139 		FConvertToIntermediateBufferInPlace iConvertToIntermediateBufferInPlace; // must *not* be set to NULL

   140 		/** The conversion data. */

   141 		const SCnvConversionData* iConversionData; // must *not* be set to NULL

   142 		/** The number of bytes per character. */

   143 		TInt16 iNumberOfBytesPerCharacter;

   144 		/** The number of core bytes per character. */

   145 		TInt16 iNumberOfCoreBytesPerCharacter;

   146 		};

   147 public:

   148 	// these functions may *not* have CCnvCharacterSetConverter::EInputConversionFlagStopAtFirstUnconvertibleCharacter set in aInputConversionFlags

   149 	IMPORT_C static TInt ConvertFromUnicode(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, TDes8& aForeign, const TDesC16& aUnicode, CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters, const TArray<SCharacterSet>& aArrayOfCharacterSets);

   150 	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);

   151 	IMPORT_C static void ConvertFromIntermediateBufferInPlace(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut, const TDesC8& aEscapeSequence, TInt aNumberOfBytesPerCharacter);

   152 	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

   153 	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

   154 	IMPORT_C static TInt ConvertToUnicodeFromHeterogeneousForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray<SMethod>& aArrayOfMethods);

   155 	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);

   156 private:

   157 	static void CheckArrayOfCharacterSets(const TArray<SCharacterSet>& aArrayOfCharacterSets);

   158 	static void CheckArrayOfStates(const TArray<SState>& aArrayOfStates);

   159 	static void CheckArrayOfMethods(const TArray<SMethod>& aArrayOfMethods);

   160 	static TInt LengthOfUnicodeCharacter(const TDesC16& aUnicode, TInt aIndex);

   161 	static TBool NextHomogeneousForeignRun(const SCnvConversionData*& aConversionData, TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TArray<SState>& aArrayOfStates, TUint& aOutputConversionFlags);

   162 	static TBool MatchesEscapeSequence(TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TDesC8& aEscapeSequence);

   163 	static TBool IsStartOf(const TDesC8& aStart, const TDesC8& aPotentiallyLongerDescriptor);

   164 	inline static TInt ReduceToNearestMultipleOf(TInt aNumber1, TInt aNumber2) {return (aNumber1/aNumber2)*aNumber2;}

   165 	};

   166 

   167 #endif