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 字元表示。 如果 sourceString 為 Null，則必須為 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
 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