windowsPromoteStringBuffer 函式 (winstring.h)

發行項
03/04/2024

語法

HRESULT WindowsPromoteStringBuffer(
  HSTRING_BUFFER bufferHandle,
  HSTRING        *string
);

參數

bufferHandle

類型：[in] HSTRING_BUFFER

要用於新 HSTRING 的緩衝區。您必須使用 WindowsPreallocateStringBuffer 函式來建立 HSTRING_BUFFER。

string

類型：[out] HSTRING*

新建立的 HSTRING ，其中包含 bufferHandle 的內容。

傳回值

類型： HRESULT

此函式可以傳回下列其中一個值。

傳回碼	描述
S_OK	已成功建立 HSTRING。
E_POINTER	字串為 NULL。
E_INVALIDARG	bufferHandle 不是藉由呼叫 WindowsPreallocateStringBuffer 函式所建立，或呼叫端已覆寫 bufferHandle 中的終止 NULL 字元。

備註

使用 WindowsPromoteStringBuffer 函式，從HSTRING_BUFFER建立新的 HSTRING。呼叫 WindowsPromoteStringBuffer 函 式會將可變緩衝區轉換為不可變 的 HSTRING。使用 WindowsPreallocateStringBuffer 函式來建立 HSTRING_BUFFER。

如果 WindowsPromoteStringBuffer 呼叫失敗，您可以呼叫 WindowsDeleteStringBuffer 函式來捨棄可變動的緩衝區。

每個 對 WindowsPromoteStringBuffer 函 式的呼叫都必須與對應的 WindowsDeleteString 呼叫相符。

範例

下列程式代碼範例示範如何使用 WindowsPromoteStringBuffer 函 式。

#include <winstring.h>

int main()
{
    HSTRING hString = NULL;
    HSTRING_BUFFER hStringBuffer = NULL;
    PWSTR strBuffer = NULL;

    HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer);

    if (SUCCEEDED(hr))
    {
        // Fill in the buffer

        hr = WindowsPromoteStringBuffer(hStringBuffer, &hString);

        if (SUCCEEDED(hr))
        {
            WindowsDeleteString(hString);
        }
        else
        {
            WindowsDeleteStringBuffer(hStringBuffer);
        }
    }
}

規格需求

需求	值
最低支援的用戶端	Windows 8 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2012 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winstring.h
程式庫	RuntimeObject.lib
Dll	ComBase.dll