Fonction WindowsCreateStringReference (winstring.h)

  • Article

Crée une référence de chaîne basée sur la chaîne spécifiée.

Syntaxe

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

Paramètres

sourceString

Type : [in] PCWSTR

Chaîne terminée par null à utiliser comme source pour le nouveau HSTRING.

La valeur NULL représente la chaîne vide, si la valeur de longueur est 0. Doit être alloué sur le cadre de pile.

length

Type : [in] UINT32

Longueur de sourceString, en caractères Unicode. Doit être 0 si sourceString a la valeur NULL. Si elle est supérieure à 0, sourceString doit avoir un caractère null de fin.

hstringHeader

Type : [out] HSTRING_HEADER*

Pointeur vers une structure que le Windows Runtime utilise pour identifier la chaîne en tant que référence de chaîne ou chaîne de passage rapide.

string

Type : [out] HSTRING*

Pointeur vers la chaîne nouvellement créée ou NULL si une erreur se produit. Tout contenu existant dans la chaîne est remplacé. Le HSTRING est un type de handle standard.

Valeur retournée

Type : HRESULT

Cette fonction peut retourner l’une de ces valeurs.

Code de retour Description
S_OK
 Le HSTRING a été créé avec succès.
E_INVALIDARG
 Chaîne ou hstringHeader a la valeur NULL, ou la chaîne n’est pas terminée par null.
E_OUTOFMEMORY
 Échec de l’allocation du nouveau HSTRING.
E_POINTER
 sourceString a la valeur NULL et la longueur est différente de zéro.

Remarques

Utilisez la fonction WindowsCreateStringReference pour créer un HSTRING à partir d’une chaîne existante. Ce type de HSTRING est nommé chaîne de passe rapide. Contrairement à un HSTRING créé par la fonction WindowsCreateString, la durée de vie de la mémoire tampon de stockage dans le nouveau HSTRING n’est pas gérée par le Windows Runtime. L’appelant alloue sourceString sur le cadre de pile, ainsi qu’un HSTRING_HEADER non initialisé, pour éviter une allocation de tas et éliminer le risque de fuite de mémoire. L’appelant doit s’assurer que sourceString et le contenu de hstringHeader restent inchangés pendant la durée de vie du HSTRING attaché.

Vous n’avez pas besoin d’appeler la fonction WindowsDeleteString pour annuler l’allocation d’un HSTRING à passage rapide créé par la fonction WindowsCreateStringReference .

Pour créer un HSTRING vide, passez NULL pour sourceString et 0 pour la longueur.

Le Windows Runtime effectue le suivi d’une chaîne de passage rapide à l’aide d’une structure HSTRING_HEADER, qui est retournée dans le paramètre de sortie hstringHeader. Ne modifiez pas le contenu du HSTRING_HEADER.

Configuration requise

   
Client minimal pris en charge Windows 8 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête winstring.h

Voir aussi

WindowsCreateString

WindowsDeleteString