Функция WindowsPreallocateStringBuffer (winstring.h)

Статья
10/20/2023

Выделяет изменяемый буфер символов для использования при создании HSTRING .

Синтаксис

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

Параметры

length

Тип: [in] UINT32

Размер выделяемого буфера. Значение, равное нулю, соответствует пустой строке.

charBuffer

Тип: [out] WCHAR**

Изменяемый буфер, содержащий символы. Обратите внимание, что буфер уже содержит завершающий символ NULL .

bufferHandle

Тип: [out] HSTRING_BUFFER*

Предварительно выделянный строковый буфер или значение NULL , если длина равна 0.

Возвращаемое значение

Тип: HRESULT

Эта функция может возвращать одно из этих значений.

Код возврата	Описание
S_OK	HSTRING успешно создан.
E_POINTER	значение mutableBuffer или bufferHandle равно NULL.
MEM_E_INVALID_SIZE	Запрошенный размер выделения HSTRING слишком велик.
E_OUTOFMEMORY	Не удалось выделить HSTRING.

Используйте функцию WindowsPreallocateStringBuffer для создания изменяемого буфера символов, которым можно управлять перед фиксацией в неизменяемом HSTRING. Завершив заполнение mutableBuffer строкой, вызовите функцию WindowsPromoteStringBuffer с параметром bufferHandle , чтобы создать HSTRING. В буфер необходимо записать символы точной длины . Windows 10 версии 1803, Windows Server версии 1803 и более поздних версий: вы можете писать символ конца null после символов длины.

Вызовите функцию WindowsDeleteStringBuffer , чтобы отменить изменяемый буфер перед повышением уровня. Если буфер уже повышен путем вызова WindowsPromoteStringBuffer, вызовите функцию WindowsDeleteString , чтобы отменить строку. Если вызов WindowsPromoteStringBuffer завершается сбоем , можно вызвать функцию WindowsDeleteStringBuffer , чтобы отменить изменяемый буфер.

Примеры

В следующем примере кода показано, как использовать функцию WindowsPreallocateStringBuffer .

#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);  
}

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winstring.h
Библиотека	RuntimeObject.lib
DLL	ComBase.dll