WindowsCreateString 函数 (winstring.h)

基于指定的源字符串创建新的 HSTRING 。

Syntax

HRESULT WindowsCreateString(
  PCNZWCH sourceString,
  UINT32  length,
  HSTRING *string
);

参数

sourceString

类型:[in,可选] LPCWSTR

要用作新 HSTRING 源的 UTF-16LE 编码文本缓冲区。 若要创建新的、空字符串或 NULL 字符串,请传递 sourceString 的 NULL,并传递长度为 0 的 NULL。

此缓冲区不需要以 null 结尾。 WindowsCreateString 将复制其内容,并在支持返回 的 HSTRING 的新缓冲区中添加 null 终止符。

length

类型:[in] UINT32

SourceString 的长度(以 Unicode 字符为单位)。 如果 sourceString 为 NULL,则必须为 0。

string

类型:[out] HSTRING*

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

返回值

类型:HRESULT

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

返回代码 Description
S_OK
HSTRING 已成功创建。
E_INVALIDARG
字符串 为 NULL。
E_OUTOFMEMORY
未能分配新的 HSTRING。
E_POINTER
sourceString 为 NULL , 长度 为非零。

注解

使用 WindowsCreateString 函数分配新的 HSTRING。 Windows 运行时将 字符串 复制到新 HSTRING 的后备缓冲区,并使用引用计数管理缓冲区生存期。 调用 WindowsCreateStringReference 函数以创建 快速传递字符串,该字符串使用现有字符串而不复制它。

调用 WindowsDeleteString 函数以取消分配 HSTRING。 每次对 WindowsCreateString 函数的调用都必须匹配对 WindowsDeleteString 的调用。

若要创建新的、空字符串或 NULL 字符串,请传递 sourceString 的 NULL,并传递长度为 0 的 NULL。

如果 sourceString 嵌入了 null 字符, 则 WindowsCreateString 函数会将所有字符复制到终止 null 字符。

要求

Requirement 价值
最低支持的客户端 Windows 8 [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows操作系统
Header winstring.h
Library RuntimeObject.lib

另请参阅

WindowsCreateStringReference

WindowsDeleteString