Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
WindowsPromoteStringBuffer
Collapse the table of content
Expand the table of content

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

Library

RuntimeObject.lib

DLL

ComBase.dll

See also

WindowsPreallocateStringBuffer
WindowsDeleteStringBuffer
HSTRING
HSTRING_BUFFER

 

 

Community Additions

ADD
Show:
© 2015 Microsoft