共用方式為


WindowsCreateStringReference 函式 (winstring.h)

根據指定的字串建立新的字串參考。

語法

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

參數

sourceString

類型: [in] PCWSTR

要作為新 HSTRING來源的 Null 終止字串。

如果長度為 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
字串hstringHeader為 Null,或字串不是以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