Funzione WindowsCreateStringReference (winstring.h)

Articolo
10/20/2023

Crea un nuovo riferimento stringa basato sulla stringa specificata.

Sintassi

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

Parametri

sourceString

Tipo: [in] PCWSTR

Stringa con terminazione Null da usare come origine per il nuovo HSTRING.

Il valore NULL rappresenta la stringa vuota, se il valore di length è 0. Deve essere allocata nello stack frame.

length

Tipo: [in] UINT32

Lunghezza di sourceString, in caratteri Unicode. Deve essere 0 se sourceString è NULL. Se maggiore di 0, sourceString deve avere un carattere Null di terminazione.

hstringHeader

Tipo: [out] HSTRING_HEADER*

Puntatore a una struttura utilizzata dall'Windows Runtime per identificare la stringa come riferimento stringa o come stringa pass veloce.

string

Tipo: [out] HSTRING*

Puntatore alla stringa appena creata o NULL se si verifica un errore. Qualsiasi contenuto esistente nella stringa viene sovrascritto. HSTRING è un tipo di handle standard.

Valore restituito

Tipo: HRESULT

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	HSTRING è stato creato correttamente.
E_INVALIDARG	String o hstringHeader è NULL oppure la stringa non è con terminazione Null.
E_OUTOFMEMORY	Impossibile allocare il nuovo HSTRING.
E_POINTER	sourceString è NULL e la lunghezza è diversa da zero.

Commenti

Usare la funzione WindowsCreateStringReference per creare un HSTRING da una stringa esistente. Questo tipo di HSTRING è denominato stringa pass veloce. A differenza di un HSTRING creato dalla funzione WindowsCreateString, la durata del buffer di backup nel nuovo HSTRING non viene gestita dalla Windows Runtime. Il chiamante alloca sourceString nello stack frame, insieme a un HSTRING_HEADER non inizializzato, per evitare un'allocazione dell'heap ed eliminare il rischio di perdita di memoria. Il chiamante deve garantire che sourceString e il contenuto di hstringHeader rimangano invariati durante la durata del HSTRING collegato.

Non è necessario chiamare la funzione WindowsDeleteString per annullare l'allocazione di un HSTRING rapido creato dalla funzione WindowsCreateStringReference .

Per creare un HSTRING vuoto, passare NULL per sourceString e 0 per la lunghezza.

Il Windows Runtime tiene traccia di una stringa pass veloce usando una struttura HSTRING_HEADER, che viene restituita nel parametro out hstringHeader. Non modificare il contenuto del HSTRING_HEADER.

Requisiti


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

Vedi anche

WindowsCreateString

WindowsDeleteString

Share via