Export (0) Print
Expand All
Expand Minimize

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. The terminating NUL character is appended.

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 codeDescription
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 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 ensure that mutableBuffer ends in a terminating NUL character.

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.

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 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]

Header

Winstring.h

See also

WindowsPromoteStringBuffer
WindowsDeleteStringBuffer
HSTRING
HSTRING_BUFFER

 

 

Community Additions

ADD
Show:
© 2014 Microsoft