WindowsCreateStringReference 函数 （winstring.h）

基于指定的字符串创建新的字符串引用。

Syntax

HRESULT WindowsCreateStringReference(
  PCWSTR         sourceString,
  UINT32         length,
  HSTRING_HEADER *hstringHeader,
  HSTRING        *string
);

参数

sourceString

类型：[in] PCWSTR

一个以 null 结尾的字符串，用作新 HSTRING 的源。

如果长度为 0，则 NULL 值表示空字符串。 应在堆栈帧上分配。

length

类型：[in] UINT32

SourceString 的长度（以 Unicode 字符为单位）。 如果 sourceString 为 NULL，则必须为 0。 如果大于 0，sourceString 必须具有终止 null 字符。

hstringHeader

类型：[out] HSTRING_HEADER*

指向 Windows 运行时用来将字符串标识为 字符串 引用或快速传递字符串的结构的指针。

string

类型：[out] HSTRING*

指向新创建的字符串的指针;如果发生错误，则为 NULL 。 将覆盖 字符串 中的任何现有内容。 HSTRING 是一种标准句柄类型。

返回值

类型：HRESULT

此函数可以返回其中一个值。

注解

使用 WindowsCreateStringReference 函数从现有字符串创建 HSTRING 。 此类 HSTRING 命名为 快速传递字符串。 与 WindowsCreateString 函数创建的 HSTRING 不同，新 HSTRING 中后盾缓冲区的生存期不受 Windows 运行时管理。 调用方在堆栈帧上分配 sourceString 以及未初始化 的HSTRING_HEADER，以避免堆分配并消除内存泄漏的风险。 调用方必须确保在附加的 HSTRING 的生存期内，sourceString 和 hstringHeader 的内容保持不变。

无需调用 WindowsDeleteString 函数来取消分配由 WindowsCreateStringReference 函数创建的快速传递 HSTRING。

若要创建空的 HSTRING，请为 sourceString 传递 NULL，并为长度传递 0。

Windows 运行时使用 HSTRING_HEADER 结构跟踪快速传递字符串，该结构在 hstringHeader out 参数中返回。 请勿更改 HSTRING_HEADER的内容。

要求

另请参阅

WindowsCreateString

WindowsDeleteString