/*
* Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*
*/


#if !defined(__CONVUTILS_H__)
#define __CONVUTILS_H__

#if !defined(__E32STD_H__)
#include <e32std.h>
#endif

#if !defined(__E32BASE_H__)
#include <e32base.h>
#endif

#if !defined(__CHARCONV_H__)
#include <charconv.h>
#endif

struct SCnvConversionData;

 
class CnvUtilities
/** 
Provides static character conversion utilities for complex encodings. Its functions 
may be called from a plug-in DLL's implementation of ConvertFromUnicode() 
and ConvertToUnicode().

These utility functions are provided for use when converting to/from complex 
character set encodings, including modal encodings. Modal encodings are those 
where the interpretation of a given byte of data is dependent on the current 
mode; mode changing is performed by escape sequences which occur in the byte 
stream. A non-modal complex encoding is one in which characters are encoded 
using variable numbers of bytes. The number of bytes used to encode a character 
depends on the value of the initial byte.
@publishedAll 
@released
*/
	{
public:
	// type definitions for converting from Unicode
	
	/**  A pointer to a function which "mangles" text when converting from
	Unicode into a complex modal or non-modal foreign character set
	encoding.

	It might insert a shifting character, escape sequence, or other
	special characters.If the target character set encoding is modal, the
	implementation of this function may call the
	CnvUtilities::ConvertFromIntermediateBufferInPlace()
	utility function which is provided because many modal character sets
	require an identical implementation of this function.

	" convutils.lib " */
    typedef void (*FConvertFromIntermediateBufferInPlace)(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut);
	struct SCharacterSet
	/** Stores information about a non-Unicode character set. The information 
	is used to locate the conversion information required by 
	ConvertFromUnicode() and ConvertToUnicode().

	An array of these structs  that contains all available character sets  
	can be generated by CreateArrayOfCharacterSetsAvailableLC() and 
	CreateArrayOfCharacterSetsAvailableL(), and is used by one of the 
	overloads of PrepareToConvertToOrFromL(). */
		{
		/** The conversion data. */
		const SCnvConversionData* iConversionData; // must *not* be set to NULL
		/** A pointer to a function which "mangles" the text in a way 
		appropriate to the target complex character set. For instance it 
		might insert a shifting character, escape sequence, or other special 
		characters. */
		FConvertFromIntermediateBufferInPlace iConvertFromIntermediateBufferInPlace; // must *not* be set to NULL
		/** The escape sequence which introduces the character set, i.e. it 
		identifies this character set as the next one to use. Must not be NULL.
		If the character set is non-modal, this should be set to an empty 
		descriptor. */
		const TDesC8* iEscapeSequence; // must *not* be set to NULL
		};
	// type definitions for converting to Unicode

	/** A pointer to a function which calculates the number of consecutive
	bytes in the remainder of the foreign descriptor which can be
	converted using the current character set's conversion data.

	Called when converting from a non-modal complex character set encoding
	into Unicode. It may return a negative
	CCnvCharacterSetConverter::TError value to indicate an
	error in the encoding.

	" convutils.lib " */
	typedef TInt (*FNumberOfBytesAbleToConvert)(const TDesC8& aDescriptor); // may return negative CCnvCharacterSetConverter::TError values
	
	/** A pointer to a function which prepares the text for conversion into
	Unicode.

	For instance it might remove any shifting or other special characters.
	Called when converting from a non-modal complex character set encoding
	into Unicode.

	" convutils.lib " */
 	typedef void (*FConvertToIntermediateBufferInPlace)(TDes8& aDescriptor);

	struct SState
	/** Character conversion data for one of the character sets which is 
	specified in a modal character set encoding. An array of these structs 
	is used when converting from a modal character set into Unicode, using 
	CnvUtilities::ConvertToUnicodeFromModalForeign(). Neither of the members 
	may be NULL. */
		{
		/** The escape sequence which introduces the character set, i.e. it 
		identifies this character set as the next one to use. This must begin 
		with KControlCharacterEscape. */
		const TDesC8* iEscapeSequence; // must *not* be set to NULL and must begin with 0x1b
		/** The conversion data. */
		const SCnvConversionData* iConversionData; // must *not* be set to NULL
		};
	struct SMethod
		{
		/** A pointer to a function which calculates the number of consecutive 
		bytes in the remainder of the foreign descriptor which can be converted 
		using the current character set's conversion data. It may return a 
		negative CCnvCharacterSetConverter::TError value to indicate an error 
		in the encoding. */
		FNumberOfBytesAbleToConvert iNumberOfBytesAbleToConvert; // must *not* be set to NULL
		/** A pointer to a function which prepares the text for conversion 
		into Unicode. For instance it might remove any shifting or other 
		special characters. */
		FConvertToIntermediateBufferInPlace iConvertToIntermediateBufferInPlace; // must *not* be set to NULL
		/** The conversion data. */
		const SCnvConversionData* iConversionData; // must *not* be set to NULL
		/** The number of bytes per character. */
		TInt16 iNumberOfBytesPerCharacter;
		/** The number of core bytes per character. */
		TInt16 iNumberOfCoreBytesPerCharacter;
		};
public:
	// these functions may *not* have CCnvCharacterSetConverter::EInputConversionFlagStopAtFirstUnconvertibleCharacter set in aInputConversionFlags
	IMPORT_C static TInt ConvertFromUnicode(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, TDes8& aForeign, const TDesC16& aUnicode, CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters, const TArray<SCharacterSet>& aArrayOfCharacterSets);
	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);
	IMPORT_C static void ConvertFromIntermediateBufferInPlace(TInt aStartPositionInDescriptor, TDes8& aDescriptor, TInt& aNumberOfCharactersThatDroppedOut, const TDesC8& aEscapeSequence, TInt aNumberOfBytesPerCharacter);
	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
	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
	IMPORT_C static TInt ConvertToUnicodeFromHeterogeneousForeign(CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, TDes16& aUnicode, const TDesC8& aForeign, TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter, const TArray<SMethod>& aArrayOfMethods);
	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);
private:
	static void CheckArrayOfCharacterSets(const TArray<SCharacterSet>& aArrayOfCharacterSets);
	static void CheckArrayOfStates(const TArray<SState>& aArrayOfStates);
	static void CheckArrayOfMethods(const TArray<SMethod>& aArrayOfMethods);
	static TInt LengthOfUnicodeCharacter(const TDesC16& aUnicode, TInt aIndex);
	static TBool NextHomogeneousForeignRun(const SCnvConversionData*& aConversionData, TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TArray<SState>& aArrayOfStates, TUint& aOutputConversionFlags);
	static TBool MatchesEscapeSequence(TInt& aNumberOfForeignBytesConsumed, TPtrC8& aHomogeneousRun, TPtrC8& aRemainderOfForeign, const TDesC8& aEscapeSequence);
	static TBool IsStartOf(const TDesC8& aStart, const TDesC8& aPotentiallyLongerDescriptor);
	inline static TInt ReduceToNearestMultipleOf(TInt aNumber1, TInt aNumber2) {return (aNumber1/aNumber2)*aNumber2;}
	};

#endif