ATL 文本编码函数

  • 项目

这些函数支持文本编码和解码。

函数 说明
AtlGetHexValue 调用此函数可获取十六进制数字的数值。
AtlGetVersion 调用此函数可获取你正在使用的 ATL 库的版本。
AtlHexDecode 将已按十六进制文本进行编码（例如通过对 AtlHexEncode 的先前调用）的一串数据进行解码。
AtlHexDecodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的十六进制编码字符串解码而来的数据。
AtlHexEncode 调用此函数可将某些数据编码为十六进制文本的字符串。
AtlHexEncodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。
AtlHexValue 调用此函数可获取十六进制数字的数值。
AtlUnicodeToUTF8 调用此函数可将 Unicode 字符串转换为 UTF-8。
BEncode 调用此函数可转换使用“B”编码的某些数据。
BEncodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。
EscapeXML 调用此函数可将无法在 XML 中安全使用的字符转换为其安全的等效字符。
GetExtendedChars 调用此函数可获取字符串中的扩展字符的数目。
IsExtendedChar 调用此函数可了解给定字符是否为扩展字符（小于 32、大于 126，并且不是制表符、换行符或回车符）
QEncode 调用此函数可转换使用“Q”编码的某些数据。
QEncodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。
QPDecode 将已采用 Quoted Printable 格式进行编码（例如通过对 QPEncode 的先前调用）的一串数据进行解码。
QPDecodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的 Quoted Printable 编码字符串解码而来的数据。
QPEncode 调用此函数可对某些 Quoted Printable 格式的数据进行编码。
QPEncodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。
UUDecode 将已经过 uuencode 处理（例如通过对 UUEncode 的先前调用）的数据字符串解码。
UUDecodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的已进行 uuencode 的字符串解码而来的数据。
UUEncode 调用此函数可对某些数据进行 uuencode。
UUEncodeGetRequiredLength 调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

要求

标头：atlenc.h

AtlGetHexValue

调用此函数可获取十六进制数字的数值。

inline char AtlGetHexValue(char chIn) throw();

参数

chIn
十六进制字符 '0'-'9'、'A'-'F' 或 'a'-'f'。

返回值

解释为十六进制数字的输入字符的数值。 例如，输入“0”返回值 0，输入“A”返回值 10。 如果输入字符不是十六进制数字，则此函数返回 -1。

AtlGetVersion

调用此函数可获取你正在使用的 ATL 库的版本。

ATLAPI_(DWORD) AtlGetVersion(void* pReserved);

参数

pReserved
保留的指针。

返回值

返回正在编译或运行的 ATL 库版本的 DWORD 整数值。

示例

应按如下方式调用该函数。

DWORD ver;
ver = AtlGetVersion(NULL);

要求

标头：atlbase.h

AtlHexDecode

将已按十六进制文本进行编码（例如通过对 AtlHexEncode 的先前调用）的一串数据进行解码。

inline BOOL AtlHexDecode(
   LPCSTR pSrcData,
   int nSrcLen,
   LPBYTE pbDest,
   int* pnDestLen) throw();

参数

pSrcData
包含要解码的数据的字符串。

nSrcLen
pSrcData 的长度（以字符为单位）。

pbDest
调用方分配的缓冲区，用于接收已解码的数据。

pnDestLen
指向包含 pbDest 长度（以字节为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字节数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字节为单位）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

AtlHexDecodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的十六进制编码字符串解码而来的数据。

inline int AtlHexDecodeGetRequiredLength(int nSrcLen) throw();

参数

nSrcLen
编码字符串中的字符数。

返回值

可以包含 nSrcLen 字符的已解码字符串的缓冲区所需的字节数。

AtlHexEncode

调用此函数可将某些数据编码为十六进制文本的字符串。

inline BOOL AtlHexEncode(
   const BYTE * pbSrcData,
   int nSrcLen,
   LPSTR szDest,
int * pnDestLen) throw();

参数

pbSrcData
包含要编码的数据的缓冲区。

nSrcLen
要编码的数据的长度（以字节为单位）。

szDest
调用方分配的缓冲区，用于接收已编码的数据。

pnDestLen
指向包含 szDest 长度（以字符为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字符数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字符为单位）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

源数据的每个字节将编码为 2 个十六进制字符。

AtlHexEncodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

inline int AtlHexEncodeGetRequiredLength(int nSrcLen) throw();

参数

nSrcLen
要编码的数据的字节数。

返回值

可以包含 nSrcLen 字节的已编码数据的缓冲区所需的字符数。

AtlHexValue

调用此函数可获取十六进制数字的数值。

inline short AtlHexValue(char chIn) throw();

参数

chIn
十六进制字符 '0'-'9'、'A'-'F' 或 'a'-'f'。

返回值

解释为十六进制数字的输入字符的数值。 例如，输入“0”返回值 0，输入“A”返回值 10。 如果输入字符不是十六进制数字，则此函数返回 -1。

AtlUnicodeToUTF8

调用此函数可将 Unicode 字符串转换为 UTF-8。

ATL_NOINLINE inline int AtlUnicodeToUTF8(
   LPCWSTR wszSrc,
   int nSrc,
   LPSTR szDest,
   int nDest) throw();

参数

wszSrc
要转换的 Unicode 字符串

nSrc
Unicode 字符串的长度（以字符为单位）。

szDest
调用方分配的缓冲区，用于接收转换后的字符串。

nDest
缓冲区的长度（以字节为单位）。

返回值

返回转换后的字符串的字符数。

备注

若要确定转换后的字符串所需的缓冲区大小，请调用此函数，并为 szDest 和 nDest 传递 0。

BEncode

调用此函数可转换使用“B”编码的某些数据。

inline BOOL BEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCSTR pszCharSet) throw();

参数

pbSrcData
包含要编码的数据的缓冲区。

nSrcLen
要编码的数据的长度（以字节为单位）。

szDest
调用方分配的缓冲区，用于接收已编码的数据。

pnDestLen
指向包含 szDest 长度（以字符为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字符数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字符为单位）。

pszCharSet
用于转换的字符集。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注解

RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt) 中介绍了“B”编码方案。

BEncodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

inline int BEncodeGetRequiredLength(int nSrcLen, int nCharsetLen) throw();

参数

nSrcLen
要编码的数据的字节数。

nCharsetLen
用于转换的字符集的长度（以字符为单位）。

返回值

可以包含 nSrcLen 字节的已编码数据的缓冲区所需的字符数。

备注

RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt) 中介绍了“B”编码方案。

EscapeXML

调用此函数可将无法在 XML 中安全使用的字符转换为其安全的等效字符。

inline int EscapeXML(
   const wchar_t * szIn,
   int nSrcLen,
   wchar_t * szEsc,
   int nDestLen,
   DWORD dwFlags = ATL_ESC_FLAG_NONE) throw();

参数

szIn
要转换的字符串。

nSrclen
要转换的字符串的长度（以字符为单位）。

szEsc
调用方分配的缓冲区，用于接收转换后的字符串。

nDestLen
调用方分配的缓冲区的长度（以字符为单位）。

dwFlags
ATL_ESC：描述如何执行转换的标志。

  • ATL_ESC_FLAG_NONE：默认行为。 不转换引号和撇号。
  • ATL_ESC_FLAG_ATTR：引号和撇号分别转换为 " 和 '。

返回值

转换后的字符串的长度（以字符为单位）。

备注

下表显示了此函数执行的可能转换：

源 目标
< <
> >
& &
“ '
" "

GetExtendedChars

调用此函数可获取字符串中的扩展字符的数目。

inline int GetExtendedChars(LPCSTR szSrc, int nSrcLen) throw();

参数

szSrc
要分析的字符串。

nSrcLen
字符串的长度（以字符为单位）。

返回值

返回在字符串中找到的扩展字符数，由 IsExtendedChar 确定。

IsExtendedChar

调用此函数可了解给定字符是否为扩展字符（小于 32、大于 126，并且不是制表符、换行符或回车符）

inline int IsExtendedChar(char ch) throw();

参数

ch
要测试的字符

返回值

如果扩展了字符，则返回 TRUE，否则返回 FALSE。

QEncode

调用此函数可转换使用“Q”编码的某些数据。

inline BOOL QEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCSTR pszCharSet,
   int* pnNumEncoded = NULL) throw();

参数

pbSrcData
包含要编码的数据的缓冲区。

nSrcLen
要编码的数据的长度（以字节为单位）。

szDest
调用方分配的缓冲区，用于接收已编码的数据。

pnDestLen
指向包含 szDest 长度（以字符为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字符数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字符为单位）。

pszCharSet
用于转换的字符集。

pnNumEncoded
指向变量的指针，返回时该变量包含必须转换的不安全字符数。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt) 中介绍了“Q”编码方案。

QEncodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

inline int QEncodeGetRequiredLength(int nSrcLen, int nCharsetLen) throw();

参数

nSrcLen
要编码的数据的字节数。

nCharsetLen
用于转换的字符集的长度（以字符为单位）。

返回值

可以包含 nSrcLen 字节的已编码数据的缓冲区所需的字符数。

备注

RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt) 中介绍了“Q”编码方案。

QPDecode

将已采用 Quoted Printable 格式进行编码（例如通过对 QPEncode 的先前调用）的一串数据进行解码。

inline BOOL QPDecode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   DWORD dwFlags = 0) throw();

参数

pbSrcData
[in] 包含要解码的数据的缓冲区。

nSrcLen
[in] pbSrcData 的长度（以字节为单位）。

szDest
[out] 调用方分配的缓冲区，用于接收已解码的数据。

pnDestLen
[out] 指向包含 szDest 长度（以字节为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字节数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字节为单位）。

dwFlags
[in] 描述如何执行转换的 ATLSMTP_QPENCODE 标志。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt) 中介绍了带引号的可打印编码方案。

QPDecodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的 Quoted Printable 编码字符串解码而来的数据。

inline int QPDecodeGetRequiredLength(int nSrcLen) throw();

参数

nSrcLen
编码字符串中的字符数。

返回值

可以包含 nSrcLen 字符的已解码字符串的缓冲区所需的字节数。

注解

RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt) 中介绍了带引号的可打印编码方案。

QPEncode

调用此函数可对某些 Quoted Printable 格式的数据进行编码。

inline BOOL QPEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   DWORD dwFlags = 0) throw ();

参数

pbSrcData
包含要编码的数据的缓冲区。

nSrcLen
要编码的数据的长度（以字节为单位）。

szDest
调用方分配的缓冲区，用于接收已编码的数据。

pnDestLen
指向包含 szDest 长度（以字符为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字符数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字符为单位）。

dwFlags
描述如何执行转换的 ATLSMTP_QPENCODE 标志。

  • ATLSMTP_QPENCODE_DOT：如果句点出现在行首，则将其添加到输出并将其编码。

  • ATLSMTP_QPENCODE_TRAILING_SOFT：将 =\r\n 追加到已编码的字符串。

RFC 2045 中介绍了带引号的可打印编码方案。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt) 中介绍了带引号的可打印编码方案。

QPEncodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

inline int QPEncodeGetRequiredLength(int nSrcLen) throw ();

参数

nSrcLen
要编码的数据的字节数。

返回值

可以包含 nSrcLen 字节的已编码数据的缓冲区所需的字符数。

备注

RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt) 中介绍了带引号的可打印编码方案。

UUDecode

将已经过 uuencode 处理（例如通过对 UUEncode 的先前调用）的数据字符串解码。

inline BOOL UUDecode(
   BYTE* pbSrcData,
   int nSrcLen,
   BYTE* pbDest,
   int* pnDestLen) throw ();

参数

pbSrcData
包含要解码的数据的字符串。

nSrcLen
pbSrcData 的长度（以字节为单位）。

pbDest
调用方分配的缓冲区，用于接收已解码的数据。

pnDestLen
指向包含 pbDest 长度（以字节为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字节数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字节为单位）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

此 uuencoding 实现遵循 POSIX P1003.2b/D11 规范。

UUDecodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字节为单位），该缓冲区可包含从指定长度的已进行 uuencode 的字符串解码而来的数据。

inline int UUDecodeGetRequiredLength(int nSrcLen) throw ();

参数

nSrcLen
编码字符串中的字符数。

返回值

可以包含 nSrcLen 字符的已解码字符串的缓冲区所需的字节数。

备注

此 uuencoding 实现遵循 POSIX P1003.2b/D11 规范。

UUEncode

调用此函数可对某些数据进行 uuencode。

inline BOOL UUEncode(
   const BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCTSTR lpszFile = _T("file"),
   DWORD dwFlags = 0) throw ();

参数

pbSrcData
包含要编码的数据的缓冲区。

nSrcLen
要编码的数据的长度（以字节为单位）。

szDest
调用方分配的缓冲区，用于接收已编码的数据。

pnDestLen
指向包含 szDest 长度（以字符为单位）的变量的指针。 如果函数成功，则该变量将接收写入到缓冲区的字符数。 如果函数失败，则该变量将接收缓冲区所需的长度（以字符为单位）。

lpszFile
在 dwFlags 中指定 ATLSMTP_UUENCODE_HEADER 时要添加到标头的文件。

dwFlags
控制此函数的行为的标志。

  • ATLSMTP_UUENCODE_HEADE：将编码标头。

  • ATLSMTP_UUENCODE_END：将编码末尾。

  • ATLSMTP_UUENCODE_DOT：将执行数据填充。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

此 uuencoding 实现遵循 POSIX P1003.2b/D11 规范。

UUEncodeGetRequiredLength

调用此函数可获取某个缓冲区的大小（以字符为单位），该缓冲区可包含从指定大小的数据编码而来的字符串。

inline int UUEncodeGetRequiredLength(int nSrcLen) throw ();

参数

nSrcLen
要编码的数据的字节数。

返回值

可以包含 nSrcLen 字节的已编码数据的缓冲区所需的字符数。

备注

此 uuencoding 实现遵循 POSIX P1003.2b/D11 规范。

另请参阅

概念
ATL COM 桌面组件