Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WindowsPromoteStringBuffer function

Creates an HSTRING from the specified HSTRING_BUFFER.

Syntax


HRESULT WindowsPromoteStringBuffer(
  _In_   HSTRING_BUFFER bufferHandle,
  _Out_  HSTRING *string
);

Parameters

bufferHandle [in]

Type: HSTRING_BUFFER

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

string [out]

Type: HSTRING*

The newly created HSTRING that contains the contents of bufferHandle.

Return value

Type: HRESULT

This function can return one of these values.

Return codeDescription
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 NUL 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.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

Examples

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


#include <WinrtString.h>

int main()
{
    HSTRING hString = NULL;
    LPVOID* 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);
	       }
    }
}


Requirements

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Header

Winstring.h

See also

WindowsPreallocateStringBuffer
WindowsDeleteStringBuffer
HSTRING
HSTRING_BUFFER

 

 

Community Additions

Show:
© 2014 Microsoft