PSFormatForDisplayAlloc, fonction (propsys.h)

Article
08/25/2023

Obtient une représentation sous forme de chaîne Unicode d’une valeur de propriété stockée dans une structure PROPVARIANT . Cette fonction alloue de la mémoire à la chaîne de sortie.

Syntaxe

PSSTDAPI PSFormatForDisplayAlloc(
  [in]  REFPROPERTYKEY        key,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] PWSTR                 *ppszDisplay
);

Paramètres

[in] key

Type : REFPROPERTYKEY

Référence à une PROPRIÉTÉKEY qui nomme la propriété dont la valeur est récupérée.

[in] propvar

Type : REFPROPVARIANT

Référence à une structure PROPVARIANT qui contient le type et la valeur de la propriété .

[in] pdff

Type : PROPDESC_FORMAT_FLAGS

Un ou plusieurs indicateurs qui spécifient le format à appliquer à la chaîne de propriété. Consultez PROPDESC_FORMAT_FLAGS pour connaître les valeurs possibles.

[out] ppszDisplay

Type : PWSTR*

Lorsque la fonction retourne, contient un pointeur vers une représentation sous forme de chaîne Unicode terminée par null de la valeur de propriété demandée.

Valeur retournée

Type : HRESULT

Retourne l’une des valeurs suivantes.

Code de retour	Description
S_OK	La chaîne mise en forme a été créée avec succès. S_OK avec une chaîne de retour vide indique qu’il y avait une chaîne d’entrée vide ou une valeur non vide qui a été mise en forme en tant que chaîne vide.
S_FALSE	La chaîne mise en forme n’a pas été créée. S_FALSE avec une chaîne de retour vide indique que la chaîne vide a été le résultat d’une VT_EMPTY.
E_OUTOFMEMORY	Indique que l’allocation a échoué.

Remarques

Cette fonction appelle l’implémentation du sous-système de schéma de IPropertySystem ::FormatForDisplayAlloc. Cet appel fournit une représentation sous forme de chaîne Unicode d’une valeur de propriété, avec une mise en forme supplémentaire basée sur un ou plusieurs PROPDESC_FORMAT_FLAGS. Si propertyKEY n’est pas reconnu par le sous-système de schéma, IPropertySystem ::FormatForDisplayAlloc tente de mettre en forme la valeur en fonction du VARTYPE de la valeur.

Vous devez initialiser com (Component Object Model) avec CoInitialize ou OleInitialize avant d’appeler PSFormatForDisplayAlloc.

La fonction alloue de la mémoire via CoTaskMemAlloc et retourne un pointeur vers cette mémoire via le paramètre ppszDisplay . L’application appelante doit utiliser CoTaskMemFree pour libérer cette ressource quand elle n’est plus nécessaire.

L’objectif de cette fonction est de convertir des données en chaîne pouvant être affichées à l’utilisateur. La valeur est mise en forme en fonction des paramètres régionaux actuels, de la langue de l’utilisateur, du PROPDESC_FORMAT_FLAGS et de la description de propriété spécifiée par la clé de propriété. Pour plus d’informations sur la façon dont le schéma de description de propriété influence la mise en forme de la valeur, consultez les rubriques suivantes :

En règle générale, les PROPDESC_FORMAT_FLAGS sont utilisées pour modifier le format prescrit par la description de la propriété.

La chaîne de sortie peut contenir des caractères directionnels Unicode. Ces caractères non espacés influencent l’algorithme bidirectionnel Unicode de sorte que les valeurs s’affichent correctement lorsqu’une langue de gauche à droite (LTR) est dessinée sur une fenêtre RTL (droite à gauche) ou qu’un langage RTL est dessiné sur une fenêtre LTR. Ces caractères sont les suivants : "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Les propriétés suivantes utilisent des formats spéciaux et ne sont pas affectées par les PROPDESC_FORMAT_FLAGS. Notez que les exemples cités concernent les chaînes dont les paramètres régionaux actuels sont définis sur anglais ; en règle générale, la sortie est localisée, sauf indication contraire.

Propriété	Format
System.FileAttributes	Les attributs de fichier suivants sont convertis en lettres et ajoutés pour créer une chaîne (par exemple, une valeur de 0x1801 (FILE_ATTRIBUTE_READONLY \| FILE_ATTRIBUTE_COMPRESSED \| FILE_ATTRIBUTE_OFFLINE) est converti en « RCO ») : FILE_ATTRIBUTE_READONLY (0x00000001) - 'R' FILE_ATTRIBUTE_SYSTEM (0x00000004) - 'S' FILE_ATTRIBUTE_ARCHIVE (0x00000020) -'A' FILE_ATTRIBUTE_COMPRESSED (0x00000800) - 'C' FILE_ATTRIBUTE_ENCRYPTED (0x00004000) - 'E' FILE_ATTRIBUTE_OFFLINE (0x00001000) - 'O' FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (0x00002000) - 'I'
System.Photo.ISOSpeed	Par exemple, « ISO-400 ».
System.Photo.ShutterSpeed	La valeur APEX est convertie en temps d’exposition à l’aide de la formule suivante : `Exposure_time = 2^(-APEX_value)` Par exemple, « 2 secondes ». ou « 1/125 seconde ».
System.Photo.ExposureTime	Par exemple, « 2 secondes ». ou « 1/125 s ».
System.Photo.Aperture	La valeur APEX est convertie en nombre F à l’aide de la formule suivante : `F_Number = 2^(APEX_Value / 2)` Par exemple, « f/5.6 ».
System.Photo.FNumber	Par exemple, « f/5.6 ».
System.Photo.SubjectDistance	Par exemple, « 15 m » ou « 250 mm ».
System.Photo.FocalLength	Par exemple, « 50 mm ».
System.Photo.FlashEnergy	Par exemple, « 500 bpcs ».
System.Photo.ExposureBias	Par exemple, « -2 étape », « 0 étape » ou « +3 étape ».
System.Computer.DecoratedFreeSpace	Par exemple, « 105 Mo sans 13,2 Go ».
System.ItemType	Par exemple, « Application » ou « Image JPEG ».
System.ControlPanel.Category	Par exemple, « Apparence et personnalisation ».
System.ComputerName	Par exemple, « LITWARE05 (cet ordinateur) » ou « testbox07 ».

Si la clé de propriété ne correspond pas à une description de propriété dans l’un des schémas de propriété inscrits, cette fonction choisit un format en fonction du type de la valeur.

Type de la valeur	Format
VT_BOOLEAN	Non pris en charge.
VT_FILETIME	Chaîne de date/heure spécifiée par PROPDESC_FORMAT_FLAGS et les paramètres régionaux actuels. PDFF_SHORTTIME et PDFF_SHORTDATE sont les valeurs par défaut. Par exemple, « 13/11/2006 15 :22 PM ».
VARTYPE numérique	Chaîne décimale dans les paramètres régionaux actuels. Par exemple, « 42 ».
VT_LPWSTR ou autre	Converti en chaîne. Les séquences de « \r », « \t » ou « \n » sont remplacées par un espace unique.
VT_VECTOR \| Rien	Valeurs séparées par des points-virgules. Un point-virgule est utilisé quels que soient les paramètres régionaux.

Exemples

L’exemple suivant, à inclure dans le cadre d’un programme plus large, montre comment utiliser PSFormatForDisplayAlloc pour mettre en forme une valeur d’évaluation.

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatForDisplayAlloc(PKEY_Rating, propvar, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
         CoTaskMemFree(pszValue);
    }
    PropVariantClear(&propvar);
}

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
Bibliothèque	Propsys.lib
DLL	Propsys.dll (version 6.0 ou ultérieure)
Composant redistribuable	Windows Desktop Search (WDS) 3.0

Voir aussi

PSFormatForDisplay

PSFormatPropertyValue

Schéma de description de la propriété

Partager via