Funzione WindowsPreallocateStringBuffer (winstring.h)

Articolo
03/04/2024

Alloca un buffer di caratteri modificabile da usare nella creazione HSTRING .

Sintassi

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

Parametri

length

Tipo: [in] UINT32

Dimensione del buffer da allocare. Un valore pari a zero corrisponde alla stringa vuota.

charBuffer

Tipo: [out] WCHAR**

Buffer modificabile che contiene i caratteri. Si noti che il buffer contiene già un carattere NULL terminante.

bufferHandle

Tipo: [out] HSTRING_BUFFER*

Buffer stringa preallocato o NULL se la lunghezza è 0.

Valore restituito

Tipo: HRESULT

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	L'HSTRING è stato creato correttamente.
E_POINTER	mutableBuffer o bufferHandle è NULL.
MEM_E_INVALID_SIZE	Le dimensioni di allocazione HSTRING richieste sono troppo grandi.
E_OUTOFMEMORY	Impossibile allocare HSTRING.

Commenti

Usare la funzione WindowsPreallocateStringBuffer per creare un buffer di caratteri modificabile che è possibile modificare prima di eseguirne il commit in un HSTRING non modificabile. Al termine della compilazione della funzione mutableBuffer con la stringa, chiamare la funzione WindowsPromoteStringBuffer con il parametro bufferHandle per creare HSTRING. È necessario scrivere esattamente caratteri di lunghezza nel buffer. Windows 10 versione 1803, Windows Server Versione 1803 e versioni successive: è possibile scrivere un terminatore Null dopo i caratteri di lunghezza.

Chiamare la funzione WindowsDeleteStringBuffer per eliminare il buffer modificabile prima della promozione. Se il buffer è già stato promosso da una chiamata a WindowsPromoteStringBuffer, chiamare la funzione WindowsDeleteString per eliminare la stringa. Se la chiamata WindowsPromoteStringBuffer ha esito negativo, è possibile chiamare la funzione WindowsDeleteStringBuffer per eliminare il buffer modificabile.

Esempio

Nell'esempio di codice seguente viene illustrato come usare la funzione 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);  
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winstring.h
Libreria	RuntimeObject.lib
DLL	ComBase.dll