WindowsPreallocateStringBuffer function (winstring.h)

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.

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

See also

HSTRING

HSTRING_BUFFER

WindowsDeleteStringBuffer

WindowsPromoteStringBuffer