Fonction PSCoerceToCanonicalValue (propsys.h)
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 |
|---|---|
|
La fonction a réussi. La valeur de propriété spécifiée par ppropvar est désormais sous forme canonique. |
|
La valeur de propriété spécifiée par ppropvar se présente désormais sous une forme canonique tronquée. |
|
Le paramètre ppropvar n’est pas valide. La structure PROPVARIANT a été effacée. |
|
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. |
|
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 :
- 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.
- 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 :
- Les valeurs de type VT_LPWSTR, VT_BSTR ou VT_LPSTR sont converties en VT_VECTOR | VT_LPWSTR à l’aide d’InitPropVariantFromStringAsVector.
- Toutes les autres conversions sont effectuées à l’aide de PropVariantChangeType
- 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.
- 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
IShellItem2 ::GetPropertyStore
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour