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 字符为单位)。 如果 sourceStringNULL,则必须为 0。 如果大于 0,sourceString 必须具有终止 null 字符。

hstringHeader

类型:[out] HSTRING_HEADER*

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

string

类型:[out] HSTRING*

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

返回值

类型: HRESULT

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

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

注解

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