Expand Minimize

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

ADD
Show:
© 2014 Microsoft