MkParseDisplayName, fonction (objbase.h)

Convertit une chaîne en moniker qui identifie l’objet nommé par la chaîne.

Cette fonction est l’inverse de l’opération IMoniker ::GetDisplayName , qui récupère le nom d’affichage associé à un moniker.

Syntaxe

HRESULT MkParseDisplayName(
  [in]  LPBC      pbc,
  [in]  LPCOLESTR szUserName,
  [out] ULONG     *pchEaten,
  [out] LPMONIKER *ppmk
);

Paramètres

[in] pbc

Pointeur vers l’interface IBindCtx sur l’objet de contexte de liaison à utiliser dans cette opération de liaison.

[in] szUserName

Pointeur vers le nom complet à analyser.

[out] pchEaten

Pointeur vers le nombre de caractères de szUserName qui ont été consommés. Si la fonction réussit, *pchEaten est la longueur de szUserName ; sinon, il s’agit du nombre de caractères correctement analysés.

[out] ppmk

Adresse de la variable pointeur IMoniker* qui reçoit le pointeur d’interface vers le moniker créé à partir de szUserName. En cas de réussite, la fonction a appelé AddRef sur le moniker et l’appelant est responsable de l’appel de Release. Si une erreur se produit, le pointeur d’interface spécifié contient autant de moniker que la méthode a pu créer avant que l’erreur ne se produise.

Valeur retournée

Cette fonction peut retourner la valeur de retour standard E_OUTOFMEMORY, ainsi que les valeurs suivantes.

Cette fonction peut également retourner l’une des valeurs d’erreur retournées par IMoniker ::BindToObject, IOleItemContainer ::GetObject ou IParseDisplayName ::P arseDisplayName.

Remarques

La fonction MkParseDisplayName analyse un nom lisible par l’homme dans un moniker qui peut être utilisé pour identifier une source de lien. Le moniker résultant peut être un moniker simple (tel qu’un moniker de fichier), ou il peut s’agir d’un composite générique composé des pièces de moniker de composant. Par exemple, le nom complet « c :\mydir\somefile !item 1 »

peut être analysé dans le moniker composite générique suivant : FileMoniker basé sur « c :\mydir\somefile ») + (ItemMoniker basé sur « item 1 »).

L’utilisation la plus courante de MkParseDisplayName est dans l’implémentation de la boîte de dialogue Liens standard, qui permet à un utilisateur final de spécifier la source d’un objet lié en tapant une chaîne. Vous devrez peut-être également appeler MkParseDisplayName si votre application prend en charge un langage de macro qui autorise les références distantes (référence à des éléments en dehors du document).

L’analyse d’un nom d’affichage nécessite souvent d’activer les mêmes objets que ceux qui seraient activés pendant une opération de liaison, ce qui peut être aussi coûteux (en termes de performances) que la liaison. Les objets liés pendant l’opération d’analyse sont mis en cache dans le contexte de liaison passé à la fonction. Si vous envisagez de lier le moniker retourné par MkParseDisplayName, il est préférable de le faire immédiatement après le retour de la fonction, en utilisant le même contexte de liaison, ce qui supprime la nécessité d’activer des objets une deuxième fois.

MkParseDisplayName analyse autant le nom d’affichage qu’il comprend dans un moniker. La fonction appelle ensuite IMoniker ::P arseDisplayName sur le moniker nouvellement créé, en passant le reste du nom d’affichage. Le moniker retourné par ParseDisplayName est composé à la fin du moniker existant et, si l’un des noms d’affichage reste non analysé, ParseDisplayName est appelé sur le résultat de la composition. Ce processus est répété jusqu’à ce que le nom complet ait été analysé.

MkParseDisplayName tente les stratégies suivantes pour analyser le début du nom d’affichage, en utilisant le premier qui réussit :

1. La fonction recherche dans la table d’objets en cours d’exécution les monikers de fichier correspondant à tous les préfixes du nom d’affichage qui se composent uniquement de caractères de nom de fichier valides. Cette stratégie peut identifier les documents qui ne sont pas encore enregistrés.
2. La fonction vérifie le préfixe maximal du nom d’affichage, qui se compose uniquement de caractères de nom de fichier valides, pour voir si un document OLE 1 est inscrit sous ce nom. Dans ce cas, le moniker retourné est un moniker interne fourni par la couche de compatibilité OLE 1 d’OLE 2.
3. La fonction consulte le système de fichiers pour case activée si un préfixe du nom d’affichage correspond à un fichier existant. Le nom de fichier peut être absolu du lecteur, relatif au lecteur, relatif au répertoire de travail, ou commencer par un nom de partage réseau explicite. C’est le cas habituel.
4. Si le caractère initial du nom d’affichage est « @ », la fonction recherche la chaîne la plus longue immédiatement après qui est conforme à la syntaxe progID légale. La fonction convertit cette chaîne en CLSID à l’aide de la fonction CLSIDFromProgID . Si le CLSID représente une classe OLE 2, la fonction charge l’objet de classe correspondant et demande un pointeur d’interface IParseDisplayName . L’interface IParseDisplayName obtenue reçoit ensuite la chaîne entière à analyser, en commençant par « @ ». Si le CLSID représente une classe OLE 1, la fonction traite la chaîne qui suit le ProgID comme un indicateur de liaison OLE1/DDE ayant la syntaxed’élémentde nom de fichier|.

Configuration requise

Voir aussi

IMoniker ::GetDisplayName

IMoniker ::P arseDisplayName

IParseDisplayName