epoc32/include/utf.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     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
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
williamr@2
    16
#if !defined(__UTF_H__)
williamr@2
    17
#define __UTF_H__
williamr@2
    18
williamr@2
    19
#if !defined(__E32STD_H__)
williamr@2
    20
#include <e32std.h>
williamr@2
    21
#endif
williamr@2
    22
williamr@2
    23
williamr@2
    24
class CnvUtfConverter
williamr@2
    25
/** 
williamr@2
    26
Converts text between Unicode (UCS-2) and the two Unicode transformation 
williamr@2
    27
formats UTF-7 and UTF-8. There are no functions to convert directly between 
williamr@2
    28
UTF-7 and UTF-8.
williamr@2
    29
williamr@2
    30
Objects of this class do not need to be created because all the member functions 
williamr@2
    31
are static. The four functions are passed text in the second argument and 
williamr@2
    32
output the resulting text in the first argument. Sixteen-bit descriptors are 
williamr@2
    33
used to hold text encoded in UCS-2 (i.e. normal 16 bit Unicode), and eight-bit 
williamr@2
    34
descriptors are used to hold text encoded in either of the transformation 
williamr@2
    35
formats.
williamr@2
    36
williamr@2
    37
The conversion functions return the number of characters which were not converted 
williamr@2
    38
because the output descriptor was not long enough to hold all of the converted 
williamr@2
    39
text. This allows users of this class to perform partial conversions on an 
williamr@2
    40
input descriptor, handling the case when the input descriptor is truncated 
williamr@2
    41
mid way through a multi-byte character. The caller does not have to guess 
williamr@2
    42
how big to make the output descriptor for a given input descriptor- they 
williamr@2
    43
can simply do the conversion in a loop using a small output descriptor. The 
williamr@2
    44
ability to handle truncated descriptors is particularly useful if the caller 
williamr@2
    45
is receiving information in chunks from an external source. 
williamr@2
    46
@publishedAll
williamr@2
    47
@released
williamr@2
    48
*/
williamr@2
    49
	{
williamr@2
    50
public:
williamr@2
    51
	/** Conversion error flags. At this stage there is only one error flag 
williamr@2
    52
	- others may be added in the future. */
williamr@2
    53
	enum TError
williamr@2
    54
		{
williamr@2
    55
 		/** The input descriptor contains a single corrupt character. This 
williamr@2
    56
 		might occur when the input descriptor only contains some of the bytes 
williamr@2
    57
 		of a single multi-byte character. */
williamr@2
    58
		EErrorIllFormedInput=KErrCorrupt
williamr@2
    59
		};
williamr@2
    60
	 
williamr@2
    61
	 /** Initial value for the state argument in a set of related calls to
williamr@2
    62
	ConvertToUnicode(). */
williamr@2
    63
	enum {KStateDefault=0}; 
williamr@2
    64
public:
williamr@2
    65
	// the conversion functions return either one of the TError values above, or the number of unconverted elements left at the end of the input descriptor
williamr@2
    66
	IMPORT_C static TInt ConvertFromUnicodeToUtf7(TDes8& aUtf7, const TDesC16& aUnicode, TBool aEncodeOptionalDirectCharactersInBase64);
williamr@2
    67
	static TInt ConvertFromUnicodeToUtf7(TDes8& aUtf7, const TDesC16& aUnicode, TBool aIsImapUtf7, TBool aEncodeOptionalDirectCharactersInBase64);
williamr@2
    68
	IMPORT_C static TInt ConvertFromUnicodeToUtf8(TDes8& aUtf8, const TDesC16& aUnicode);
williamr@2
    69
	static TInt ConvertFromUnicodeToUtf8(TDes8& aUtf8, const TDesC16& aUnicode, TBool aGenerateJavaConformantUtf8);
williamr@2
    70
	IMPORT_C static TInt ConvertToUnicodeFromUtf7(TDes16& aUnicode, const TDesC8& aUtf7, TInt& aState);
williamr@2
    71
	static TInt ConvertToUnicodeFromUtf7(TDes16& aUnicode, const TDesC8& aUtf7, TBool aIsImapUtf7, TInt& aState);
williamr@2
    72
	IMPORT_C static TInt ConvertToUnicodeFromUtf8(TDes16& aUnicode, const TDesC8& aUtf8);
williamr@2
    73
	static TInt ConvertToUnicodeFromUtf8(TDes16& aUnicode, const TDesC8& aUtf8, TBool aGenerateJavaConformantUtf8);
williamr@2
    74
	static TInt ConvertToUnicodeFromUtf8(TDes16& aUnicode, const TDesC8& aUtf8, TBool aGenerateJavaConformantUtf8,
williamr@2
    75
			TInt& aNumberOfUnconvertibleCharacters, TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter);
williamr@2
    76
williamr@2
    77
	IMPORT_C static HBufC8* ConvertFromUnicodeToUtf7L(const TDesC16& aUnicode,TBool aEncodeOptionalDirectCharactersInBase64);
williamr@2
    78
	IMPORT_C static HBufC8* ConvertFromUnicodeToUtf8L(const TDesC16& aUnicode);
williamr@2
    79
	IMPORT_C static HBufC16* ConvertToUnicodeFromUtf7L(const TDesC8& aUtf7); 
williamr@2
    80
	IMPORT_C static HBufC16* ConvertToUnicodeFromUtf8L(const TDesC8& aUtf8);
williamr@2
    81
williamr@2
    82
williamr@2
    83
	};
williamr@2
    84
williamr@2
    85
#endif