Partager via

Fonction PSCoerceToCanonicalValue (propsys.h)

  • Article

Convertit la valeur d’une propriété en valeur canonique, en fonction de la description de la propriété.

Syntaxe

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Paramètres

[in] key

Type : REFPROPERTYKEY

Référence à une structure PROPERTYKEY qui identifie la propriété dont la valeur doit être renforcée.

[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 fonction retourne correctement, contient la valeur canonique.

Valeur retournée

Type : HRESULT

Les valeurs de retour possibles sont les suivantes :

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 se présente 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.
TYPE_E_TYPEMISMATCH
 La contrainte entre le type de la valeur et le type de description de la propriété n’était pas possible. La structure PROPVARIANT a été effacée.
Tout autre code d’échec
 La contrainte entre le type de la valeur et le type de description de la propriété n’était pas possible. La structure PROPVARIANT a été effacée.

Remarques

Cette fonction est un wrapper autour de l’implémentation par le système de IPropertyDescription ::CoerceToCanonicalValue.

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

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

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

Le forçage est effectué en quatre étapes, comme suit :

  1. Les valeurs suivantes sont converties en VT_EMPTY.
    • 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 vides ou composées entièrement d’espaces.
    • Les valeurs de type VT_FILETIME avant 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 en appelant IPropertyDescription ::GetPropertyType. Pour plus d’informations sur l’influence du schéma de propriété sur 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 en une 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 est non vide et non NULL. Par exemple, L"Alice ».
    • S’il s’agit d’une propriété d’arborescence (autrement dit, si l’attribut isTreeProperty de l’élément typeInfo a la valeur 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 ».
    • Le forçage supprime les caractères inutiles et entraîne des VT_EMPTY s’il n’y avait pas de contenu.
    VT_VECTOR | VT_LPWSTR
    • Chaque chaîne dans le vecteur doit respecter les règles pour VT_LPWSTR répertorié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 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 du tableau suivant 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 du 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.
     

Exemples

L’exemple suivant, à inclure dans le cadre d’un programme plus grand, montre comment utiliser PSCoerceToCanonicalValue pour forcer une valeur au type requis pour PKEY_Keywords.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP avec SP2, Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 avec SP1 [applications de bureau uniquement]
Plateforme cible Windows
En-tête propsys.h
Bibliothèque Propsys.lib
DLL Propsys.dll (version 6.0 ou ultérieure)
Composant redistribuable Windows Desktop Search (WDS) 3.0

Voir aussi

IPropertyDescription

IShellItem2 ::GetPropertyStore

PropVariantChangeType

Schéma de description de propriété

typeInfo