WindowsPreallocateStringBuffer-Funktion (winstring.h)

Artikel
10/20/2023

Weist einen veränderlichen Zeichenpuffer für die Verwendung bei der HSTRING-Erstellung zu.

Syntax

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

Parameter

length

Typ: [in] UINT32

Die Größe des zuzuordnenden Puffers. Ein Wert von null entspricht der leeren Zeichenfolge.

charBuffer

Typ: [out] WCHAR**

Der veränderbare Puffer, der die Zeichen enthält. Beachten Sie, dass der Puffer bereits ein beendendes NULL-Zeichen enthält.

bufferHandle

Typ: [out] HSTRING_BUFFER*

Der vorab zugewiesene Zeichenfolgenpuffer oder NULL , wenn die Länge 0 ist.

Rückgabewert

Typ: HRESULT

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Der HSTRING wurde erfolgreich erstellt.
E_POINTER	mutableBuffer oder bufferHandle ist NULL.
MEM_E_INVALID_SIZE	Die angeforderte HSTRING-Zuordnungsgröße ist zu groß.
E_OUTOFMEMORY	Fehler beim Zuweisen des HSTRING.

Hinweise

Verwenden Sie die WindowsPreallocateStringBuffer-Funktion , um einen veränderlichen Zeichenpuffer zu erstellen, den Sie bearbeiten können, bevor Sie ihn zu einem unveränderlichen HSTRING verpflichten. Wenn Sie das Auffüllen des mutableBuffer mit Ihrer Zeichenfolge abgeschlossen haben, rufen Sie die WindowsPromoteStringBuffer-Funktion mit dem parameter bufferHandle auf, um den HSTRING zu erstellen. Sie müssen genau Längenzeichen in den Puffer schreiben. Windows 10 Version 1803, Windows Server Version 1803 und höher: Sie dürfen einen Null-Abschlussator nach Längenzeichen schreiben.

Rufen Sie die WindowsDeleteStringBuffer-Funktion auf, um den veränderlichen Puffer vor der Heraufstufung zu verwerfen. Wenn der Puffer bereits durch einen Aufruf von WindowsPromoteStringBuffer heraufgestuft wurde, rufen Sie die WindowsDeleteString-Funktion auf, um die Zeichenfolge zu verwerfen. Wenn der WindowsPromoteStringBuffer-Aufruf fehlschlägt, können Sie die WindowsDeleteStringBuffer-Funktion aufrufen, um den veränderlichen Puffer zu verwerfen.

Beispiele

Im folgenden Codebeispiel wird die Verwendung der WindowsPreallocateStringBuffer-Funktion veranschaulicht.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winstring.h
Bibliothek	RuntimeObject.lib
DLL	ComBase.dll

Weitere Informationen

HSTRING

HSTRING_BUFFER

WindowsDeleteStringBuffer

WindowsPromoteStringBuffer