HSTRING

Handle a una stringa di Windows Runtime.

typedef HSTRING__* HSTRING;

Commenti

Usare HSTRING per rappresentare stringhe non modificabili nella Windows Runtime.

JavaScript e altri linguaggi, ad esempio C#e Microsoft Visual Basic, possono usare stringhe rappresentate tramite HSTRING. Nella tabella seguente viene illustrato come viene rappresentato un HSTRING in altri linguaggi.

Linguaggio di programmazione	Rappresentazione stringa
C++/WinRT	classe winrt::hstring
Estensioni del componente Visual C++ (C++/CX)	Classe Platform::String
JavaScript	String (oggetto)
.NET Framework	Classe System.String

 

L'handle HSTRING è un tipo di handle standard. Semanticamente, un HSTRING contenente il valore NULL rappresenta la stringa vuota, costituita da zero caratteri di contenuto e un carattere NULL terminante. La creazione di una stringa tramite WindowsCreateString con zero caratteri produrrà il valore di handle NULL. Quando si chiama WindowsGetStringRawBuffer con il valore NULL, verrà restituito un puntatore a una stringa vuota seguita solo dal carattere di terminazione NUL . Nessun valore distinto esiste per rappresentare un HSTRING non inizializzato.

Chiamare la funzione WindowsCreateString per creare un nuovo HSTRING e chiamare la funzione WindowsDeleteString per rilasciare il riferimento alla memoria stringa di backup. Chiamare la funzione WindowsCreateStringReference per creare un riferimento stringa, denominato anche stringa di passaggio rapido.

Copiare un HSTRING chiamando la funzione WindowsDuplicateString .

Concatenare due stringhe chiamando la funzione WindowsConcatString .

Accedere alla memoria stringa di backup chiamando la funzione WindowsGetStringRawBuffer .

HSTRING può archiviare e usare caratteri NUL incorporati. Usare la funzione WindowsStringHasEmbedDedNull per verificare la presenza di caratteri NUL incorporati prima di usare tutte le funzioni che potrebbero produrre risultati imprevisti. Ad esempio, la maggior parte delle funzioni di Windows usa LPCWSTR come parametro di input e calcola la lunghezza della stringa solo finché non viene rilevato il primo NUL .

La stringa di backup deve rimanere non modificabile e terminata con null. Quando si chiama codice crea un riferimento stringa usando la funzione WindowsCreateStringReference , la memoria contenente la rappresentazione stringa di backup è di proprietà del chiamante. La Windows Runtime si basa sul contenuto della stringa originale per rimanere invariata. Quando si passa un riferimento stringa alla Windows Runtime, è responsabilità del chiamante assicurarsi che il contenuto della stringa non sia modificabile e NUL terminato per la durata della chiamata. Il Windows Runtime rilascia tutti i riferimenti al riferimento stringa quando la chiamata restituisce.

Quando si riceve un HSTRING come parametro out, è consigliabile impostare l'handle su NULL al termine dell'operazione.

Chiamare la funzione WindowsPreallocateStringBuffer per allocare un buffer stringa modificabile che è possibile usare per creare un HSTRING non modificabile. Al termine della popolamento del buffer, si chiama la funzione WindowsPromoteStringBuffer per creare HSTRING. Questo modello di costruzione a due fasi consente funzionalità simili a un "generatore di stringhe".

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Server minimo supportato	Windows Server 2012
Intestazione	Hstring.h

Vedi anche

WindowsCreateString

WindowsDeleteString

WindowsDuplicateString

WindowsPreallocateStringBuffer