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 code | Description |
|---|---|
|
The HSTRING was created successfully. |
|
string is NULL. |
|
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.
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 <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] |
|
Minimum supported phone |
Windows Phone 8 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also