Função WindowsPreallocateStringBuffer (winstring.h)

Artigo
03/04/2024

Aloca um buffer de caractere mutável para uso na criação de HSTRING .

Sintaxe

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

Parâmetros

length

Tipo: [in] UINT32

O tamanho do buffer a ser alocado. Um valor zero corresponde à cadeia de caracteres vazia.

charBuffer

Tipo: [out] WCHAR**

O buffer mutável que contém os caracteres. Observe que o buffer já contém um caractere NULL de terminação.

bufferHandle

Tipo: [out] HSTRING_BUFFER*

O buffer de cadeia de caracteres pré-alocado ou NULL se length for 0.

Retornar valor

Tipo: HRESULT

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O HSTRING foi criado com êxito.
E_POINTER	mutableBuffer ou bufferHandle é NULL.
MEM_E_INVALID_SIZE	O tamanho de alocação HSTRING solicitado é muito grande.
E_OUTOFMEMORY	Falha ao alocar o HSTRING.

Comentários

Use a função WindowsPreallocateStringBuffer para criar um buffer de caractere mutável que você pode manipular antes de confirmá-lo em um HSTRING imutável. Quando terminar de preencher o mutableBuffer com sua cadeia de caracteres, chame a função WindowsPromoteStringBuffer com o parâmetro bufferHandle para criar o HSTRING. Você deve gravar exatamente caracteres de comprimento no buffer. Windows 10 versão 1803, Windows Server versão 1803 e posteriores: você tem permissão para gravar um terminador nulo após caracteres de comprimento.

Chame a função WindowsDeleteStringBuffer para descartar o buffer mutável antes da promoção. Se o buffer já tiver sido promovido por uma chamada para WindowsPromoteStringBuffer, chame a função WindowsDeleteString para descartar a cadeia de caracteres. Se a chamada windowsPromoteStringBuffer falhar, você poderá chamar a função WindowsDeleteStringBuffer para descartar o buffer mutável.

Exemplos

O exemplo de código a seguir demonstra como usar a função 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	Valor
Cliente mínimo com suporte	Windows 8 [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2012 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winstring.h
Biblioteca	RuntimeObject.lib
DLL	ComBase.dll