WindowsPreallocateStringBuffer function (winstring.h)

Article
10/19/2023

Allocates a mutable character buffer for use in HSTRING creation.

Syntax

HRESULT WindowsPreallocateStringBuffer(
  UINT32         length,
  WCHAR          **charBuffer,
  HSTRING_BUFFER *bufferHandle
);

Parameters

length

Type: [in] UINT32

The size of the buffer to allocate. A value of zero corresponds to the empty string.

charBuffer

Type: [out] WCHAR**

The mutable buffer that holds the characters. Note that the buffer already contains a terminating NULL character.

bufferHandle

Type: [out] 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
S_OK	The HSTRING was created successfully.
E_POINTER	mutableBuffer or bufferHandle is NULL.
MEM_E_INVALID_SIZE	The requested HSTRING allocation size is too large.
E_OUTOFMEMORY	Failed to allocate the HSTRING.

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. Windows 10 Version 1803, Windows Server Version 1803, and later: You are permitted to write a null terminator after length characters.

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 <winstring.h>

int main()
{
    HSTRING hString = NULL;
    HSTRING_BUFFER hStringBuffer = NULL;
    PWSTR strBuffer = NULL;

    HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer);

    if (SUCCEEDED(hr))
    {
        CopyMemory(strBuffer, L"1234567890", 10 * sizeof(wchar_t));
        hr = WindowsPromoteStringBuffer(hStringBuffer, &hString);
    }

    WindowsDeleteString(hString);  
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	winstring.h
Library	RuntimeObject.lib
DLL	ComBase.dll

Share via