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
此函数可以返回其中一个值。
返回代码 | 说明 |
---|---|
|
已成功创建 HSTRING。 |
|
string 或 hstringHeader 为 NULL,或者 string 不是 null 终止。 |
|
未能分配新的 HSTRING。 |
|
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 |