RtlUnicodeStringInit function

RtlUnicodeStringInit function

RtlUnicodeStringInit 函数初始化一个 UNICODE_STRING 结构.

Syntax

 

NTSTATUS RtlUnicodeStringInit(
  _Out_    PUNICODE_STRING  DestinationString,
  _In_opt_ NTSTRSAFE_PCWSTR pszSrc
);
 

Parameters

DestinationString [out]

指向需要初始化的UNICODE_STRING 结构的指针。

 pszSrc指针拷贝到目的字符串参数UNICODE_STRING 结构体中. pszSrc 指向的字符串允许的最大字符数为NTSTRSAFE_UNICODE_STRING_MAX_CCH.

pszSrc [in, optional]

可选的参数，一个指向null-terminated 字符串常量， 字符串指针将被拷贝到DestinationString 参数指向的UNICODE_STRING结构体中的Buffer 成员。此参数可以为 NULL.

Return value

RtlUnicodeStringInit 返回以下 NTSTATUS 中的一个。

Return code	Description
STATUS_SUCCESS	这个‘成功’状态意味着源数据存在，字符已经没有截断地拷贝，因此目标缓冲区是以null结尾
STATUS_INVALID_PARAMETER	这个‘错误’状态意味着函数接收到了错误的参数，更多信息见以下列表。

 

当以下情况之一发生时，RtlUnicodeStringInit 返回 STATUS_INVALID_PARAMETER:

· pszSrc参数指向的字符串长度超过了NTSTRSAFE_UNICODE_STRING_MAX_CCH 

· DestinationString 为 NULL, 但pszSrc 不是 NULL.

获取更多关于如何测试NTSTATUS 的值的信息, see Using NTSTATUS Values.

Remarks

RtlUnicodeStringInit 做以下事情:

· 

以字节为单位，设置DestinationString参数指向的UNICODE_STRING 结构体的 Length 成员为pszSrc指向的字符串的长度。

· 

以字节为单位，设置 UNICODE_STRING 的MaximumLength 值为pszSrc长度加上2.

· 

设置UNICODE_STRING的Buffer 为pszSrc的地址。

 

DestinationString 指针不应为0，如果你需要指定NULL给DestinationString 参数，使用RtlUnicodeStringInitEx 函数。

更多关于安全字符串函数的信息见 Using Safe String Functions.

Requirements

Target platform	Desktop
Version	Available starting with Windows XP with Service Pack 1 (SP1).
Header	Ntstrsafe.h (include Ntstrsafe.h)
Library	Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

See also

RtlUnicodeStringInitEx

UNICODE_STRING