WindowsCreateStringReference-Funktion (winstring.h)

Artikel
10/20/2023

Erstellt einen neuen Zeichenfolgenverweis basierend auf der angegebenen Zeichenfolge.

Syntax

HRESULT WindowsCreateStringReference(
  PCWSTR         sourceString,
  UINT32         length,
  HSTRING_HEADER *hstringHeader,
  HSTRING        *string
);

Parameter

sourceString

Typ: [in] PCWSTR

Eine NULL-endende Zeichenfolge, die als Quelle für den neuen HSTRING verwendet werden soll.

Der Wert NULL stellt die leere Zeichenfolge dar, wenn der Wert der Länge 0 ist. Sollte im Stapelrahmen zugeordnet werden.

length

Typ: [in] UINT32

Die Länge von sourceString in Unicode-Zeichen. Muss 0 sein, wenn sourceStringNULL ist. Wenn größer als 0, muss sourceString über ein abschließendes NULL-Zeichen verfügen.

hstringHeader

Typ: [out] HSTRING_HEADER*

Ein Zeiger auf eine Struktur, die der Windows-Runtime verwendet, um Zeichenfolgen als Zeichenfolgenverweis oder schnell übergebene Zeichenfolge zu identifizieren.

string

Typ: [out] HSTRING*

Ein Zeiger auf die neu erstellte Zeichenfolge oder NULL , wenn ein Fehler auftritt. Alle vorhandenen Inhalte in der Zeichenfolge werden überschrieben. Der HSTRING ist ein Standardhandletyp.

Rückgabewert

Typ: HRESULT

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Der HSTRING wurde erfolgreich erstellt.
E_INVALIDARG	Entweder string oder hstringHeader ist NULL, oder Zeichenfolge ist nicht null-beendet.
E_OUTOFMEMORY	Fehler beim Zuordnen des neuen HSTRING.
E_POINTER	sourceString ist NULL und die Länge ungleich Null.

Hinweise

Verwenden Sie die WindowsCreateStringReference-Funktion , um einen HSTRING aus einer vorhandenen Zeichenfolge zu erstellen. Diese Art von HSTRING wird als Fast-Pass-Zeichenfolge bezeichnet. Im Gegensatz zu einem von der WindowsCreateString-Funktion erstellten HSTRING wird die Lebensdauer des Sicherungspuffers im neuen HSTRING nicht vom Windows-Runtime verwaltet. Der Aufrufer ordnet sourceString zusammen mit einem nicht initialisierten HSTRING_HEADER auf dem Stapelframe zu, um eine Heapzuordnung zu vermeiden und das Risiko eines Speicherverlusts zu vermeiden. Der Aufrufer muss sicherstellen, dass sourceString und der Inhalt von hstringHeader während der Lebensdauer des angefügten HSTRING unverändert bleiben.

Sie müssen die WindowsDeleteString-Funktion nicht aufrufen, um die Zuordnung eines von der WindowsCreateStringReference-Funktion erstellten HSTRING-Schnellpasses auf heben.

Um einen leeren HSTRING zu erstellen, übergeben Sie NULL für sourceString und 0 für die Länge.

Die Windows-Runtime verfolgt eine Schnellpasszeichenfolge mithilfe einer HSTRING_HEADER-Struktur nach, die im hstringHeader out-Parameter zurückgegeben wird. Ändern Sie den Inhalt der HSTRING_HEADER nicht.

Anforderungen


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

Weitere Informationen

WindowsCreateString

WindowsDeleteString