WindowsCreateStringReference-Funktion (winstring.h)

Erstellt einen neuen Zeichenfolgenverweis basierend auf der angegebenen Zeichenfolge.

Syntax

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

Die Parameter

sourceString

Typ: [in] PCWSTR

Eine mit Null beendete Zeichenfolge, die als Quelle für den neuen HSTRING verwendet werden soll.

Ein Wert von NULL stellt die leere Zeichenfolge dar, wenn der Wert der Länge 0 ist. Sollte auf dem Stapelrahmen zugewiesen werden.

length

Typ: [in] UINT32

Die Länge von sourceString in Unicode-Zeichen. Muss 0 sein, wenn sourceStringNULL ist. Wenn größer als 0 ist, muss sourceString ein endendes NULL-Zeichen aufweisen.

hstringHeader

Typ: [out] HSTRING_HEADER*

Ein Zeiger auf eine Struktur, die von der Windows-Runtime zum Identifizieren von Zeichenfolgen als Zeichenfolgenverweis oder fast-pass-Zeichenfolge verwendet wird.

string

Typ: [out] HSTRING*

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

Rückgabewert

Typ: HRESULT-

Diese Funktion kann einen dieser Werte zurückgeben.

Bemerkungen

Verwenden Sie die WindowsCreateStringReference-Funktion , um einen HSTRING aus einer vorhandenen Zeichenfolge zu erstellen. Diese Art von HSTRING heißt eine Schnelldurchlaufzeichenfolge. Im Gegensatz zu einer von der WindowsCreateString-Funktion erstellten HSTRING-Funktion wird die Lebensdauer des Sicherungspuffers im neuen HSTRING nicht von der Windows-Runtime verwaltet. Der Aufrufer weist sourceString im Stapelframe zusammen mit einer nicht initialisierten HSTRING_HEADER zu, um eine Heap-Zuordnung 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 eine von der WindowsCreateString-Funktion erstellte HSTRING schnell zuzuweisen.

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

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

Anforderungen

Siehe auch

WindowsCreateString

WindowsDeleteString