HSTRING

Handle d’une chaîne Windows Runtime.

typedef HSTRING__* HSTRING;

Notes

Utilisez HSTRING pour représenter des chaînes immuables dans le Windows Runtime.

JavaScript et d’autres langages, tels que C#, et Microsoft Visual Basic, peuvent utiliser des chaînes représentées à l’aide de HSTRING. Le tableau suivant montre comment un HSTRING est représenté dans d’autres langues.

Langage de programmation	Représentation de chaîne
C++/WinRT	classe winrt::hstring
Extensions de composant Visual C++ (C++/CX)	Platform::String, classe
JavaScript	String (objet)
.NET Framework	Classe System.String

 

Le handle HSTRING est un type de handle standard. Sémantiquement, un HSTRING contenant la valeur NULL représente la chaîne vide, qui se compose de zéro caractère de contenu et d’un caractère NULL de fin. La création d’une chaîne via WindowsCreateString avec zéro caractères produit la valeur null du handle. Lors de l’appel de WindowsGetStringRawBuffer avec la valeur NULL, un pointeur vers une chaîne vide suivie uniquement du caractère de fin NUL est retourné. Il n’existe aucune valeur distincte pour représenter un HSTRING qui n’est pas initialisé.

Appelez la fonction WindowsCreateString pour créer un HSTRING, puis appelez la fonction WindowsDeleteString pour libérer la référence à la mémoire de la chaîne de stockage. Appelez la fonction WindowsCreateStringReference pour créer une référence de chaîne, également appelée chaîne de passe rapide.

Copiez un HSTRING en appelant la fonction WindowsDuplicateString .

Concaténétez deux chaînes en appelant la fonction WindowsConcatString .

Accédez à la mémoire de chaîne de stockage en appelant la fonction WindowsGetStringRawBuffer .

HSTRING peut stocker et utiliser des caractères NUL incorporés . Utilisez la fonction WindowsStringHasEmbeddedNull pour case activée pour les caractères NUL incorporés avant d’utiliser les fonctions susceptibles de produire des résultats inattendus. Par exemple, la plupart des fonctions Windows utilisent LPCWSTR comme paramètre d’entrée et calculent la longueur de la chaîne uniquement jusqu’à ce que le premier NUL soit rencontré.

La chaîne de stockage doit rester immuable et terminée par null. Lorsque l’appel de code crée une référence de chaîne à l’aide de la fonction WindowsCreateStringReference , la mémoire contenant la représentation de chaîne de stockage appartient à l’appelant. Le Windows Runtime s’appuie sur le contenu de la chaîne d’origine pour rester inchangé. Lors de la transmission d’une référence de chaîne dans le Windows Runtime, il incombe à l’appelant de s’assurer que le contenu de la chaîne est inchangé et que nul est arrêté pendant la durée de l’appel. Le Windows Runtime libère toutes les références à la référence de chaîne lorsque l’appel est retourné.

Lorsque vous recevez un HSTRING en tant que paramètre out, il est recommandé de définir le handle sur NULL lorsque vous en avez terminé.

Appelez la fonction WindowsPreallocateStringBuffer pour allouer une mémoire tampon de chaîne mutable que vous pouvez utiliser pour créer un HSTRING immuable. Une fois que vous avez terminé de remplir la mémoire tampon, vous appelez la fonction WindowsPromoteStringBuffer pour créer le HSTRING. Ce modèle de construction en deux phases active des fonctionnalités similaires à un « générateur de chaînes ».

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Serveur minimal pris en charge	Windows Server 2012
En-tête	Hstring.h

Voir aussi

WindowsCreateString

WindowsDeleteString

WindowsDuplicateString

WindowsPreallocateStringBuffer