Función WindowsPreallocateStringBuffer (winstring.h)

Artículo
03/04/2024

Asigna un búfer de caracteres mutable para su uso en la creación de HSTRING .

Sintaxis

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

Parámetros

length

Tipo: [in] UINT32

Tamaño del búfer que se va a asignar. Un valor de cero corresponde a la cadena vacía.

charBuffer

Tipo: [out] WCHAR**

Búfer mutable que contiene los caracteres. Tenga en cuenta que el búfer ya contiene un carácter NULL de terminación.

bufferHandle

Tipo: [out] HSTRING_BUFFER*

Búfer de cadena asignado previamente o NULL si la longitud es 0.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	HSTRING se creó correctamente.
E_POINTER	mutableBuffer o bufferHandle es NULL.
MEM_E_INVALID_SIZE	El tamaño de asignación de HSTRING solicitado es demasiado grande.
E_OUTOFMEMORY	No se pudo asignar el HSTRING.

Comentarios

Usa la función WindowsPreallocateStringBuffer para crear un búfer de caracteres mutable que puedas manipular antes de confirmarlo en un HSTRING inmutable. Cuando haya terminado de rellenar mutableBuffer con la cadena, llame a la función WindowsPromoteStringBuffer con el parámetro bufferHandle para crear el HSTRING. Debe escribir caracteres de longitud exacta en el búfer. Windows 10 versión 1803, Windows Server versión 1803 y posteriores: se le permite escribir un terminador nulo después de los caracteres de longitud.

Llame a la función WindowsDeleteStringBuffer para descartar el búfer mutable antes de la promoción. Si el búfer ya ha sido promovido por una llamada a WindowsPromoteStringBuffer, llame a la función WindowsDeleteString para descartar la cadena. Si se produce un error en la llamada a WindowsPromoteStringBuffer , puedes llamar a la función WindowsDeleteStringBuffer para descartar el búfer mutable.

Ejemplos

En el ejemplo de código siguiente se muestra cómo usar la función 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);  
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winstring.h
Library	RuntimeObject.lib
Archivo DLL	ComBase.dll