rtlAnsiStringToUnicodeString 函数 (wdm.h)

项目
02/27/2024

RtlAnsiStringToUnicodeString 将给定的 ANSI 源字符串转换为 Unicode 字符串。

语法

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

参数

[in, out] DestinationString

指向 UNICODE_STRING 结构的指针，用于保存转换后的 Unicode 字符串。如果 AllocateDestinationString 为 TRUE，则例程分配一个新缓冲区来保存字符串数据，并将 DestinationString 的 Buffer 成员更新为指向新缓冲区。否则，例程使用当前指定的缓冲区来保存字符串。

[in] SourceString

指向要转换为 Unicode 的 ANSI 字符串的指针。

[in] AllocateDestinationString

指定此例程是否应为目标字符串分配缓冲区空间。如果存在，调用方必须通过调用 RtlFreeUnicodeString 解除分配缓冲区。

返回值

如果转换成功， RtlAnsiStringToUnicodeString 将返回STATUS_SUCCESS。失败时，例程不会分配任何内存。

注解

转换符合当前系统区域设置信息。

如果调用方将 AllocateDestinationString 设置为 TRUE，则例程会将 DestinationString 的 Buffer 成员替换为指向它分配的缓冲区的指针。即使例程返回错误状态代码，也可以覆盖旧值。

此例程未在头文件中声明。但是，可以将以下声明复制到源代码：

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

可以使用以下例程将单字节和双字节字符转换为 Unicode 字符：

有关这些例程和其他字符串处理例程的详细信息，请参阅 Run-Time Library (RTL) 例程。

RtlAnsiCharToUnicodeChar 存在安全缺陷。请考虑改用 RtlAnsiStringToUnicodeString 例程。

如果输入时，SourceCharacter 指向包含双字节字符代码的第一个字节的单字节缓冲区， 则 RtlAnsiCharToUnicodeChar 在尝试读取第二个字节时将覆盖该缓冲区。

在系统启动时，操作系统根据区域设置确定用户语言，并安装相应的系统 ANSI 代码页。 RtlAnsiCharToUnicodeChar 使用此代码页将单字节或双字节字符转换为相应的 Unicode 字符。

如果系统 ANSI 代码页定义单字节字符集 (即 ANSI 字符集 ) ，RtlAnsiCharToUnicodeChar 只需将0x00范围内的 ANSI 字符零扩展为零，0x7f生成相应的 Unicode 字符，从而加快转换操作的速度。该例程0x5c将 ANSI 值转换为反斜杠字符 (“\”) ，即使单字节代码页将此字符定义为日元符号也是如此。

如果输入时*SourceCharacter 指向无效字符代码， 则 RtlAnsiCharToUnicodeChar 将返回 Unicode 空格字符代码，0x0020。以下列表显示了无效字符代码的示例：