HSTRING

handle d’une chaîne de Windows Runtime.

typedef HSTRING__* HSTRING;

Remarques

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 qui sont 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 sous forme de chaîne
C++/WinRT WinRT :: hstring , classe
Extensions de composant Visual C++ (C++/CX) Platform :: String , classe
JavaScript String (objet)
.NET Framework System. String (classe)

Le descripteur 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 caractères de contenu nuls et d’un caractère null de fin. La création d’une chaîne via WindowsCreateString avec zéro caractère génère la valeur de handle null. Lors de l’appel de WindowsGetStringRawBuffer avec la valeur null, un pointeur vers une chaîne vide, suivi uniquement par le 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 des chaînes de sauvegarde. Appelez la fonction WindowsCreateStringReference pour créer une référence de chaîne, qui est également appelée une chaîne de passe rapide.

Copiez un HSTRING en appelant la fonction WindowsDuplicateString .

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

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

HSTRING peut stocker et utiliser des caractères null incorporés. Utilisez la fonction WindowsStringHasEmbeddedNull pour rechercher les caractères null incorporés avant d’utiliser des fonctions qui peuvent produire des résultats inattendus. par exemple, la plupart des fonctions Windows utilisent LPCWSTR comme paramètre d’entrée, et elles calculent la longueur de la chaîne uniquement jusqu’à ce que la première valeur null soit rencontrée.

La chaîne de sauvegarde doit rester immuable et se terminer par null. Lorsque le code appelant crée une référence de chaîne à l’aide de la fonction WindowsCreateStringReference , la mémoire qui contient la représentation sous forme 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 du passage 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 invariable et que NUL se termine 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é.

Quand vous recevez un HSTRING en tant que paramètre de sortie, il est recommandé de définir le handle sur la valeur null lorsque vous n’en avez plus besoin.

Appelez la fonction WindowsPreallocateStringBuffer pour allouer une mémoire tampon de chaîne mutable que vous pouvez utiliser pour créer un HSTRING immuable. Lorsque 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 une fonctionnalité similaire à un « générateur de chaîne ».

Configuration requise

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