WindowsCreateStringReference 函数 (winstring.h)

  • 项目

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

语法

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

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

返回代码 说明
S_OK
 已成功创建 HSTRING。
E_INVALIDARG
 string 或 hstringHeader 为 NULL，或者 string 不是 null 终止。
E_OUTOFMEMORY
 未能分配新的 HSTRING。
E_POINTER
 sourceString 为 NULL ， 长度 为非零。

注解

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

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

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

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

要求

   
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 winstring.h

另请参阅

WindowsCreateString

WindowsDeleteString