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
);
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 |
|---|---|
|
Der HSTRING wurde erfolgreich erstellt. |
|
Entweder string oder hstringHeader ist NULL, oder Zeichenfolge ist nicht null-beendet. |
|
Fehler beim Zuordnen des neuen HSTRING. |
|
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 |