Méthode IShellFolder ::GetDisplayNameOf (shobjidl_core.h)

Article
03/02/2024

Récupère le nom d’affichage de l’objet de fichier ou du sous-dossier spécifié.

Syntaxe

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Paramètres

[in] pidl

Type : PCUITEMID_CHILD

PIDL qui identifie de manière unique l’objet de fichier ou le sous-dossier relatif au dossier parent.

[in] uFlags

Type : SHGDNF

Indicateurs utilisés pour demander le type de nom d’affichage à retourner. Pour obtenir la liste des valeurs possibles, consultez le type énuméré SHGDNF .

[out] pName

Type : STRRET*

Lorsque cette méthode est retournée, contient un pointeur vers une structure STRRET dans laquelle retourner le nom d’affichage. Le type de nom retourné dans cette structure peut être le type demandé, mais le dossier Shell peut retourner un type différent.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Il incombe à l’appelant de libérer les ressources allouées par cette fonction.

Normalement, pidl peut faire référence uniquement aux éléments contenus dans le dossier parent. Le PIDL doit être de niveau unique et contenir exactement une structure SHITEMID suivie d’un zéro de fin. Si vous souhaitez récupérer le nom d’affichage d’un élément situé plus loin d’un niveau du dossier parent, utilisez SHBindToParent pour établir une liaison avec le dossier parent immédiat de l’élément, puis transmettez le PIDL de niveau unique de l’élément à IShellFolder ::GetDisplayNameOf.

En outre, si l’indicateur de SHGDN_FORPARSING est défini dans uFlags et que l’indicateur SHGDN_INFOLDER n’est pas défini, pidl peut faire référence à un objet à n’importe quel niveau sous le dossier parent dans la hiérarchie de l’espace de noms. À un moment donné, pidl peut être un PIDL à plusieurs niveaux, relatif au dossier parent, et peut contenir plusieurs structures SHITEMID . Toutefois, cela n’est plus pris en charge et pidl ne doit désormais faire référence qu’à un seul élément enfant.

Le moyen le plus simple de récupérer le nom complet à partir de la structure pointée par pName consiste à le transmettre à StrRetToBuf ou StrRetToStr. Ces fonctions prennent une structure STRRET et retournent le nom. Vous pouvez également examiner le membre uType de la structure et récupérer le nom du membre approprié.

Les indicateurs spécifiés dans uFlags sont des indicateurs sur l’utilisation prévue du nom. Ils ne garantissent pas que IShellFolder retournera la forme demandée du nom. Si ce formulaire n’est pas disponible, un autre formulaire peut être retourné. En particulier, il n’existe aucune garantie que le nom retourné par l’indicateur SHGDN_FORPARSING sera correctement analysé par IShellFolder ::P arseDisplayName. Il existe également des combinaisons d’indicateurs qui peuvent entraîner l’aller-retour GetDisplayNameOf/ParseDisplayName pour ne pas renvoyer la liste d’identificateurs d’origine. Cet événement est exceptionnel, mais vous devez case activée être sûr.

Note Le nom d’analyse retourné lorsque uFlags a l’indicateur SHGDN_FORPARSING défini n’est pas nécessairement une chaîne de texte normale. Les dossiers virtuels tels que Poste de travail peuvent renvoyer une chaîne contenant le GUID de l’objet de dossier sous la forme « ::{GUID} ». Les développeurs qui implémentent IShellFolder ::GetDisplayNameOf sont encouragés à retourner des noms d’analyse aussi proches que possible des noms complets, car l’utilisateur final doit souvent taper ou modifier ces noms.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (incluez Shobjidl.h)
DLL	Shell32.dll (version 4.0 ou ultérieure)

Voir aussi

IShellFolder

IShellFolder2

Partager via