WindowsPreallocateStringBuffer function
Allocates a mutable character buffer for use in HSTRING creation.
Syntax
HRESULT WindowsPreallocateStringBuffer( _In_ UINT32 length, _Out_ WCHAR **mutableBuffer, _Out_ HSTRING_BUFFER *bufferHandle );
Parameters
- length [in]
-
Type: UINT32
The size of the buffer to allocate. A value of zero corresponds to the empty string.
- mutableBuffer [out]
-
Type: WCHAR**
The mutable buffer that holds the characters. Note that the buffer already contains a terminating NULL character.
- bufferHandle [out]
-
Type: HSTRING_BUFFER*
The preallocated string buffer, or NULL if length is 0.
Return value
Type: HRESULT
This function can return one of these values.
| Return code | Description |
|---|---|
|
The HSTRING was created successfully. |
|
mutableBuffer or bufferHandle is NULL. |
|
The requested HSTRING allocation size is too large. |
|
Failed to allocate the HSTRING buffer. |
Remarks
Use the WindowsPreallocateStringBuffer function to create a mutable character buffer that you can manipulate prior to committing it to an immutable HSTRING. When you have finished populating the mutableBuffer with your string, call the WindowsPromoteStringBuffer function with the bufferHandle parameter to create the HSTRING. You must write exactly length characters into the buffer.
Call the WindowsDeleteStringBuffer function to discard the mutable buffer prior to promotion. If the buffer has already been promoted by a call to WindowsPromoteStringBuffer, call the WindowsDeleteString function to discard the string. If the WindowsPromoteStringBuffer call fails, you can call the WindowsDeleteStringBuffer function to discard the mutable buffer.
Examples
The following code example demonstrates how to use the WindowsPreallocateStringBuffer function.
#include <WinrtString.h> int main() { HSTRING hString = NULL; HSTRING_BUFFER hStringBuffer = NULL; PWSTR strBuffer = NULL; HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer); if (SUCCEEDED(hr)) { hr = WindowsPromoteStringBuffer(hStringBuffer, &hString); } WindowsDeleteString(hString); }
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