Partager via

Méthode IPropertyDescription ::CoerceToCanonicalValue (propsys.h)

  • Article

Force la valeur à la valeur canonique, en fonction de la description de la propriété.

Syntaxe

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Paramètres

[in, out] ppropvar

Type : PROPVARIANT*

Lors de l’entrée, contient un pointeur vers une structure PROPVARIANT qui contient la valeur d’origine. Lorsque cette méthode retourne, contient la valeur canonique.

Valeur retournée

Type : HRESULT

Si le code d’échec n’est pas INPLACE_S_TRUNCATED ou E_INVALIDARG, la contrainte du type de la valeur vers le type de la description de la propriété n’a pas été possible et la structure PROPVARIANT a été effacée.

Les résultats possibles sont les suivants :

Code de retour Description
S_OK
 La fonction a réussi. La valeur de propriété spécifiée par ppropvar est désormais sous forme canonique.
INPLACE_S_TRUNCATED
 La valeur de propriété spécifiée par ppropvar est désormais sous une forme canonique tronquée.
E_INVALIDARG
 Le paramètre ppropvar n’est pas valide. La structure PROPVARIANT a été effacée.

Remarques

Pour plus d’informations, consultez l’attribut de type de l’élément typeInfo dans le fichier .propdesc de la propriété.

La plupart des descriptions de propriétés spécifient le type que leurs valeurs sont censées utiliser. Par exemple, la description de la propriété pour System.Title spécifie que les valeurs System.Title doivent utiliser VT_LPWSTR. Cette méthode force les valeurs à ce type et force le résultat dans une forme canonique.

Il est important de noter que si cette méthode échoue, elle aura déjà appelé propVariantClear sur la structure PROPVARIANT d’entrée . Ce n’est que si cette méthode réussit que l’application appelante est responsable de l’appel du PropVariantClear sur ppropvar lorsque la structure n’est plus nécessaire.

La contrainte effectuée par cette méthode est également effectuée par le système de propriétés lors des appels IPropertyStore ::GetValue et IPropertyStore ::SetValue . Les applications peuvent dépendre du système de propriété pour effectuer les contraintes, ou utiliser cette méthode pour effectuer la contrainte au moment de leur choix.

La contrainte est effectuée en quatre étapes, comme suit :

  1. Les valeurs suivantes sont converties VT_EMPTYen .
    • Valeurs de type VT_NULL.
    • Valeurs de type VT_LPWSTR, VT_BSTR, ou VT_LPSTR dont le pointeur est NULL.
    • Valeurs de type VT_LPWSTR, VT_BSTR, ou VT_LPSTR qui sont vides ou se composent entièrement d’espaces.
    • Valeurs de type VT_FILETIME antérieures à minuit 1601/01/02.
  2. Si la valeur n’est pas de type VT_EMPTY après l’étape 1, elle est convertie en type spécifié par la description de la propriété. Le type d’une description de propriété peut être obtenu à l’aide de IPropertyDescription ::GetPropertyType. Pour plus d’informations sur la façon dont le schéma de propriété influence le type d’une description de propriété, consultez typeInfo . Les conversions sont effectuées comme suit :
  3. Après les étapes 2 et 3, la valeur est convertie sous forme canonique en fonction de son type. Les formes canoniques sont résumées dans le tableau suivant.
    Type de valeur Forme canonique
    VT_EMPTY Toujours canonique.
    VT_LPWSTR
    • Aucun espace de début ou de fin. La chaîne n’est pas vide. La chaîne n’est pas NULL. Par exemple : L"Alice".
    • S’il s’agit d’une propriété d’arborescence (autrement dit, si l’attribut de isTreeProperty l’élément typeInfo est TRUE), il ne doit pas avoir de barres obliques de début ou de fin (/), ne doit pas avoir d’espaces entre le texte et les barres obliques, et ne doit pas avoir deux barres obliques(/) consécutives. Par exemple : L"Friend/Bob"
    • La contrainte supprime les caractères inutiles et entraîne l’absence de VT_EMPTY contenu.
    VT_VECTOR | VT_LPWSTR
    • Chaque chaîne du vecteur doit respecter les règles pour VT_LPWSTR listées ci-dessus. En outre, le vecteur ne doit avoir aucun doublon et aucun pointeur null.
    • S’il s’agit d’une propriété d’arborescence, aucune valeur ne peut être l’ancêtre d’une autre valeur. Par exemple, L"Friend" est un ancêtre de L"Friend/Bob ».
    • S’il n’y a pas de contenu, la contrainte supprime les caractères dupliqués et ancêtres et entraîne la création de VT_EMPTY.
     
  4. Le cas échéant, la valeur est vérifiée par rapport à l’énumération du type de description de propriété. Les vérifications suivantes s’appliquent.
    Type d’énumération Type de valeur Forme canonique
    Discret ou range VT_EMPTY Toujours canonique
    Discret VT_LPWSTR La chaîne correspond à l’une des chaînes énumérées autorisées pour la propriété . Les comparaisons ne respectent pas la casse. Si ce n’est pas le cas, convertissez la valeur en VT_EMPTY.
    Discret Numérique Le nombre correspond à l’une des valeurs énumérées autorisées pour la propriété. Si ce n’est pas le cas, convertissez la valeur en VT_EMPTY.
    Discret VT_VECTOR | VT_LPWSTR Chaque chaîne du vecteur correspond à l’une des chaînes énumérées autorisées pour la propriété . Les comparaisons ne respectent pas la casse. Si ce n’est pas le cas, supprimez cette chaîne du vecteur. Si le vecteur résultant est vide, convertissez la valeur en VT_EMPTY.
    Discret VT_VECTOR | Numérique Chaque nombre dans le vecteur correspond à l’une des valeurs énumérées autorisées pour la propriété . Si ce n’est pas le cas, supprimez ce nombre du vecteur. Si le vecteur résultant est vide, convertissez la valeur en VT_EMPTY.
    Variait VT_LPWSTR La chaîne existe dans la plage autorisée pour la propriété . Les comparaisons respectent la casse. Si ce n’est pas le cas, convertissez la valeur en VT_EMPTY.
    Variait Numérique Le nombre existe dans la plage autorisée pour la propriété . Si ce n’est pas le cas, convertissez la valeur en VT_EMPTY.
    Variait VT_VECTOR | VT_LPWSTR Chaque chaîne du vecteur existe dans la plage autorisée pour la propriété . Les comparaisons respectent la casse. Si ce n’est pas le cas, supprimez cette chaîne du vecteur. Si le vecteur résultant est vide, convertissez la valeur en VT_EMPTY.
    Variait VT_VECTOR | Numérique Chaque nombre dans le vecteur existe dans la plage autorisée pour la propriété . Si ce n’est pas le cas, supprimez ce nombre du vecteur. Si le vecteur résultant est vide, convertissez la valeur en VT_EMPTY.
     

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête propsys.h

Voir aussi

IPropertyDescription

Schéma de description de la propriété