LONG DecodeText(
	LPCTSTR lpszInput,
	LONG cchInput,
	LPTSTR lpszOutput,
	LONG cchOutput,
	UINT nCharacterSet,
	UINT nEncodingType
);

LONG DecodeText(
	LPCTSTR lpszInput,
	LONG cchInput,
	CString& strOutput,
	UINT nCharacterSet,
	UINT nEncodingType
);

The DecodeText method decodes a string that was previously encoded using base64 or quoted-printable encoding.

Parameters

lpszInput

A pointer to a null terminated string which contains the encoded text. 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 decoded. If this parameter is omitted or the value is -1, the entire length of the string up to the terminating null will be decoded.

lpszOutput

A pointer to a string buffer that will contain the decoded text. This buffer must be large enough to store all of the characters in the decoded text, including the terminating null character. This parameter cannot be NULL. An alternate version of this method accepts a CString object instead of a fixed-length string buffer.

cchOutput

An integer value which specifies the maximum number of characters which can be copied into the output string buffer. The buffer must be large enough to store all of the decoded text and terminating null character. This value must be greater than zero. This parameter is not used if output buffer is specified as a CString object.

nCharacterSet

A numeric identifier which specifies the character set to use when decoding the input text. A value of zero specifies the character set is undefined and no Unicode text conversion is performed when the input string is decoded. If this value does not match the character set used when the text was originally encoded, the resulting output text may be invalid. This parameter may be omitted, in which case the method will default to using the UTF-8 character set.

nEncodingType

An integer value that specifies the encoding method used. This parameter may be omitted, or it may be one of the following values:

Constant	Description
MIME_ENCODING_QUOTED	Quoted-printable encoding is designed for textual messages where most of the characters are represented by the ASCII character set and is generally human-readable. Non-printable characters or 8-bit characters with the high bit set are encoded as hexadecimal values and represented as 7-bit text. Quoted-printable encoding is typically used for messages which use character sets such as ISO-8859-1, as well as those which use HTML.
MIME_ENCODING_BASE64	Base64 encoding converts binary or text data to ASCII by translating it so each base64 digit represents 6 bits of data. This encoding method is commonly used with messages that contain binary data (such as binary file attachments), or when text uses extended characters that cannot be represented by 7-bit ASCII. It is recommended that you use base64 encoding with Unicode text. This is the default encoding type used by this method.

Return Value

If the input buffer can be successfully decoded, the return value is the length of the decoded output string. If the method returns zero, then no text was decoded and the output string buffer will be empty. If the method fails, the return value is MIME_ERROR. To get extended error information, call GetLastError.

Remarks

This method provides a means to decode text that was previously encoded using either base64 or quoted-printable encoding. In most cases, it is not necessary to use this method because the message parser will detect which character set and encoding was used, then automatically decode the message text if necessary.

The value of the nCharacterSet parameter does not affect the resulting output text, it is only used when decoding the input text. If the Unicode version of this method is called, the output text will be converted to UTF-16 and returned to the caller. If the ANSI version of this method is used, the decoded output will always be returned to the caller using the UTF-8 character set.

If the nCharacterSet parameter is specified as MIME_CHARSET_UTF16, the encoding type must be MIME_ENCODING_BASE64. Other encoding methods are not supported for Unicode strings and will cause the method to fail. In most cases, it is preferable to use MIME_ENCODING_BASE64 as the encoding method, with quoted-printable encoding only used for legacy support.

If an unsupported encoding type is specified, this method will return MIME_ERROR and the output text string will be empty. This method cannot be used to decode uuencoded text.

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

EncodeText, GetText, SetText

Copyright © 2023 Catalyst Development Corporation. All rights reserved.