Méthode IMoniker::GetDisplayName (objidl.h)

Récupère le nom complet du moniker.

Syntaxe

HRESULT GetDisplayName(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [out] LPOLESTR *ppszDisplayName
);

Paramètres

[in] pbc

Pointeur vers l’interface IBindCtx sur le contexte de liaison à utiliser dans cette opération. Le contexte de liaison met en cache les objets liés pendant le processus de liaison, contient des paramètres qui s’appliquent à toutes les opérations utilisant le contexte de liaison et fournit les moyens par lesquels l’implémentation du moniker doit récupérer des informations sur son environnement.

[in] pmkToLeft

Si le moniker fait partie d’un moniker composite, pointez vers le moniker à gauche de ce moniker. Ce paramètre est principalement utilisé par les implémenteurs moniker pour permettre la coopération entre les différents composants d’un moniker composite. Les clients Moniker doivent passer null.

[out] ppszDisplayName

Adresse d’une variable pointeur qui reçoit un pointeur vers la chaîne de nom d’affichage du moniker. L’implémentation doit utiliser IMalloc::Alloc pour allouer la chaîne retournée dans ppszDisplayName, et l’appelant est chargé d’appeler IMalloc::Free pour la libérer. L’appelant et l’implémentation de cette méthode utilisent l’allocateur de tâches COM retourné par CoGetMalloc. Si une erreur se produit, l’implémentation doit définir *ppszDisplayName doit avoir la valeur NULL.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_OUTOFMEMORY, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	La commande s'est correctement terminée.
MK_E_EXCEEDEDDEADLINE	L’opération de liaison n’a pas pu être effectuée dans le délai spécifié par la structure BIND_OPTS du contexte de liaison.
E_NOTIMPL	Il n’existe aucun nom d’affichage.

Notes

GetDisplayName fournit une chaîne qui est une représentation affichable du moniker. Un nom d’affichage n’est pas une représentation complète de l’état interne d’un moniker ; il s’agit simplement d’un formulaire qui peut être lu par les utilisateurs. Par conséquent, il est possible (bien que rare) que deux monikers différents aient le même nom d’affichage. Bien qu’il n’y ait aucune garantie que le nom d’affichage d’un moniker puisse être réanalysé dans ce moniker lors de l’appel de la fonction MkParseDisplayName avec celui-ci, l’échec est rare.

Remarques aux appelants

Il est possible que la récupération du nom d’affichage d’un moniker soit une opération coûteuse. Pour plus d’efficacité, vous pouvez mettre en cache les résultats du premier appel réussi à GetDisplayName, plutôt que d’effectuer des appels répétés.

Remarques aux implémenteurs

Si vous écrivez une classe moniker dans laquelle le nom d’affichage ne change pas, il vous suffit de mettre en cache le nom complet et de fournir le nom mis en cache lorsque vous le souhaitez. Si le nom d’affichage peut changer au fil du temps, l’obtention du nom d’affichage actuel peut signifier que le moniker doit accéder au stockage de l’objet ou le lier à l’objet, ce qui peut représenter des opérations coûteuses. Si tel est le cas, votre implémentation de GetDisplayName doit retourner MK_E_EXCEEDEDDEADLINE si le nom ne peut pas être récupéré à l’heure spécifiée dans la structure BIND_OPTS du contexte de liaison.

Un moniker destiné à faire partie d’un moniker composite générique doit inclure tout délimiteur précédent (tel que « ») dans son nom d’affichage. Par exemple, le nom d’affichage retourné par un moniker d’élément inclut le délimiteur spécifié lors de sa création avec la fonction CreateItemMoniker . Le nom d’affichage d’un moniker de fichier n’inclut pas de délimiteur, car les monikers de fichier sont toujours censés être le composant le plus à gauche d’un composite.

Notes spécifiques à l’implémentation

Implémentation	Notes
Anti-moniker	Pour chaque anti-moniker contenu dans ce moniker, cette méthode retourne un instance de « \.. ».
Moniker de classe	Le nom complet des monikers de classe est de la forme suivante : clsid:string-clsid-no-curly-braces *[ »; » clsid-param=value]:. Par exemple, clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:.
Moniker de fichier	Cette méthode retourne le chemin que le moniker représente.
Moniker composite générique	Cette méthode retourne la concaténation des noms d’affichage retournés par chaque moniker de composant du composite.
Moniker d’élément	Cette méthode retourne la concaténation du délimiteur et le nom d’élément spécifiés lors de la création du moniker d’élément.
MONIKER OBJREF	Cette méthode obtient le nom d’affichage du moniker OBJREF. Le nom d’affichage est un encodage 64 bits qui encapsule l’emplacement de l’ordinateur, le point de terminaison de processus et l’ID de pointeur d’interface (IPID) de l’objet en cours d’exécution. Pour une compatibilité ultérieure, le nom d’affichage est limité aux caractères qui peuvent être spécifiés dans le cadre d’une URL.
Moniker de pointeur	Cette méthode retourne E_NOTIMPL.
Moniker d’URL	Le moniker d’URL tente de retourner sa chaîne d’URL complète. Si le moniker a été créé avec une chaîne d’URL partielle (voir CreateURLMonikerEx), il tente d’abord de trouver un moniker d’URL dans le contexte de liaison sous SZ_URLCONTEXT et recherche ensuite le moniker à gauche pour obtenir des informations contextuelles. S’il ne peut pas retourner sa chaîne d’URL complète, il retourne sa chaîne d’URL partielle.

Spécifications

Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	objidl.h

Voir aussi

IMoniker

MkParseDisplayName