nf-winstring-windowspromotestringbuffer.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:winstring.WindowsPromoteStringBuffer	WindowsPromoteStringBuffer function (winstring.h)	Creates an HSTRING from the specified HSTRING_BUFFER.	WindowsPromoteStringBuffer WindowsPromoteStringBuffer function [Windows Runtime] winrt.windowspromotestringbuffer winstring/WindowsPromoteStringBuffer	winrt\windowspromotestringbuffer.htm	WinRT	ac5261fd-2d31-4c65-84f2-4c6b4c3566bb	12/05/2018	WindowsPromoteStringBuffer, WindowsPromoteStringBuffer function [Windows Runtime], winrt.windowspromotestringbuffer, winstring/WindowsPromoteStringBuffer	winstring.h		Windows	Windows 8 [desktop apps \| UWP apps]	Windows Server 2012 [desktop apps \| UWP apps]										RuntimeObject.lib	ComBase.dll		Windows			19H1	WindowsPromoteStringBuffer winstring/WindowsPromoteStringBuffer	c++	APIRef kbSyntax	DllExport	ComBase.dll API-MS-Win-Core-WinRT-String-l1-1-0.dll API-MS-Win-Core-WinRT-String-L1-1-1.dll	WindowsPromoteStringBuffer

-description

Creates an HSTRING from the specified HSTRING_BUFFER.

-parameters

-param bufferHandle

Type: [in] HSTRING_BUFFER

The buffer to use for the new HSTRING. You must use the WindowsPreallocateStringBuffer function to create the HSTRING_BUFFER.

-param string

Type: [out] HSTRING*

The newly created HSTRING that contains the contents of bufferHandle.

-returns

Type: HRESULT

This function can return one of these values.

Return code	Description
S_OK	The HSTRING was created successfully.
E_POINTER	string is NULL.
E_INVALIDARG	bufferHandle was not created by calling the WindowsPreallocateStringBuffer function, or the caller has overwritten the terminating NULL character in bufferHandle.

-remarks

Use the WindowsPromoteStringBuffer function to create a new HSTRING from an HSTRING_BUFFER. Calling the WindowsPromoteStringBuffer function converts the mutable buffer to an immutable HSTRING. Use the WindowsPreallocateStringBuffer function to create the HSTRING_BUFFER.

If the WindowsPromoteStringBuffer call fails, you can call the WindowsDeleteStringBuffer function to discard the mutable buffer.

Each call to the WindowsPromoteStringBuffer function must be matched with a corresponding call to WindowsDeleteString.

Examples

The following code example demonstrates how to use the WindowsPromoteStringBuffer function.

#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);
        }
    }
}

-see-also

HSTRING

HSTRING_BUFFER

WindowsDeleteString

WindowsDeleteStringBuffer

WindowsPreallocateStringBuffer