LONG LocalizeText(
	LPCTSTR lpszInput,
	LONG cchInput,
	LPBYTE lpOutput,
	LONG cbOutput,
	UINT nCharacterSet
);

The LocalizeText method converts a Unicode string to its ANSI equivalent using the specified character set.

Parameters

lpszInput

A pointer to a null terminated string which contains the Unicode text which should be localized. If the ANSI version of this function is called, the input text must be in UTF-8 format or the function will fail. This parameter cannot be a NULL pointer.

cchInput

An integer value which specifies the number of characters of text in the input string which should be localized. If this value is -1, the entire length of the string up to the terminating null will be decoded.

lpOutput

A pointer to a byte buffer which will contain the localized ANSI version of the input text. This parameter cannot be a NULL pointer.

cbOutput

An integer value which specifies the maximum number of bytes which can be copied into the output buffer. The buffer must be large enough to store all of the localized text. This value must be greater than zero.

nCharacterSet

An optional numeric identifier which specifies the character set to use when localizing the text. If this parameter is omitted, the locale for the current thread will be used when localizing the text.

Return Value

If the input text can be successfully localized, the return value is the number of bytes copied into the output buffer. If the function returns zero, then no text was localized. If the function fails, the return value is MIME_ERROR. To get extended error information, call GetLastError.

Remarks

The LocalizeText method enables the application to localize a Unicode string, returning the ANSI version of that text using the specified character set. Because library handles all text as Unicode internally, the ANSI functions in this library will always return UTF-8 encoded text. This method allows you to easily convert that UTF-8 text to another supported character set.

If the ANSI version of this function is called, the input text must use UTF-8 character encoding or the method will fail with the last error set to ST_ERROR_INVALID_CHARACTER_SET.

If the nCharacterSet parameter is MIME_CHARSET_DEFAULT or MIME_CHARSET_UNKNOWN the input text will be converted to the default ANSI code page for the current thread locale. If there are characters in the Unicode input text which cannot be converted to an ANSI equivalent using the specified character set, those characters will be replaced by the default character for your locale, typically a question mark symbol. You cannot specify MIME_CHARSET_UTF16 as the character set.

This method will always attempt to ensure that the output buffer is terminated with an extra null byte so it is easier to work with as a standard C-style null terminated string. However, if the output buffer is not large enough to accommodate the extra null byte, it will not be copied. It is always recommended that your output buffer be somewhat larger than the length of the original input text to account for multi-byte character sequences. If the output buffer is not large enough to contain the entire localized text, no bytes will be copied to the output buffer and the function will fail with the last error set to ST_ERROR_BUFFER_TOO_SMALL.

This function is only required if your application needs to localize the UTF-8 text returned by another function and convert it to a specific 8-bit ANSI character set. For example, if you have an application which calls the ANSI version of MimeGetMessageText, it will return the message contents as UTF-8 text. If you need to display that text as localized ANSI, you can call this function to convert the UTF-8 text to your current locale or a specific character set.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: csmsgv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

MimeDecodeTextEx, MimeEncodeText, MimeEncodeTextEx, MimeGetMessageText, MimeSetMessageText

Copyright © 2023 Catalyst Development Corporation. All rights reserved.