IMoniker ::BindToObject, méthode (objidl.h)

Article
02/29/2024

Lie à l’objet spécifié. Le processus de liaison implique de rechercher l’objet, de le mettre à l’état d’exécution si nécessaire et de fournir à l’appelant un pointeur vers une interface spécifiée sur l’objet identifié.

Syntaxe

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

Paramètres

[in] pbc

Pointeur vers l’interface IBindCtx sur l’objet de contexte de liaison, qui est utilisé dans cette opération de liaison. 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 utiliser la valeur NULL.

[in] riidResult

IID de l’interface que le client souhaite utiliser pour communiquer avec l’objet identifié par le moniker.

[out] ppvResult

Adresse de la variable pointeur qui reçoit le pointeur d’interface demandé dans riid. En cas de retour réussi, *ppvResult contient le pointeur d’interface demandé vers l’objet identifié par le moniker. En cas de réussite, l’implémentation doit appeler AddRef sur le moniker. Il incombe à l’appelant d’appeler Release. Si une erreur se produit, *ppvResult doit avoir la valeur NULL.

Valeur retournée

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

Code de retour	Description
S_OK	L’opération de liaison a réussi.
MK_E_NOOBJECT	L’objet identifié par ce moniker, ou un objet identifié par le moniker composite dont ce moniker fait partie, est introuvable.
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.
MK_E_CONNECTMANUALLY	L’opération de liaison nécessite l’aide de l’utilisateur final. La raison la plus courante pour retourner cette valeur est qu’un mot de passe est nécessaire ou qu’une disquette doit être montée. Lorsque cette valeur est retournée, récupérez le moniker qui a provoqué l’erreur avec un appel à IBindCtx ::GetObjectParam avec la clé « ConnectManually ». Vous pouvez ensuite appeler IMoniker ::GetDisplayName pour obtenir le nom complet, afficher une boîte de dialogue qui communique les informations souhaitées, telles que des instructions pour monter une disquette ou une demande de mot de passe, puis réessayer l’opération de liaison.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Un objet intermédiaire a été trouvé, mais il ne prend pas en charge une interface requise pour terminer l’opération de liaison. Par exemple, un moniker d’élément retourne cette valeur si son conteneur ne prend pas en charge l’interface IOleItemContainer .
STG_E_ACCESSDENIED	Impossible d’accéder à l’objet de stockage.

Cette méthode peut également retourner les erreurs associées à la méthode IOleItemContainer ::GetObject .

Remarques

BindToObject implémente la fonction principale d’un moniker, qui consiste à localiser l’objet identifié par le moniker et à retourner un pointeur vers l’une de ses interfaces.

Remarques aux appelants

Si vous utilisez un moniker comme connexion persistante entre deux objets, vous activez la connexion en appelant BindToObject.

Vous appelez généralement BindToObject au cours du processus suivant :

Créez un objet de contexte de liaison avec un appel à la fonction CreateBindCtx .
Appelez BindToObject à l’aide du moniker, en récupérant un pointeur vers une interface souhaitée sur l’objet identifié.
Libérez le contexte de liaison.
Via le pointeur d’interface acquis, effectuez les opérations souhaitées sur l’objet .
Une fois l’objet terminé, relâchez le pointeur d’interface de l’objet.

Le fragment de code suivant illustre ces étapes.

HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &amp;pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk-&gt;BindToObject(pbc, NULL, IID_ICellRange, &amp;pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc-&gt;Release(); 
pCellRange-&gt;Release();

Vous pouvez également utiliser la fonction BindMoniker lorsque vous envisagez une seule opération de liaison et que vous n’avez pas besoin de conserver l’objet de contexte de liaison. Cette fonction d’assistance encapsule la création du contexte de liaison, en appelant BindToObject et en libérant le contexte de liaison.

Les conteneurs COM qui prennent en charge les liens vers des objets utilisent des monikers pour localiser et obtenir l’accès à l’objet lié, mais n’appellent généralement pas BindToObject directement. Au lieu de cela, lorsqu’un utilisateur active un lien dans un conteneur, le conteneur de liens appelle généralement IOleObject ::D oVerb, à l’aide de l’implémentation du gestionnaire de liens, qui appelle BindToObject sur le moniker stocké dans l’objet lié (s’il ne peut pas gérer le verbe).

Remarques aux implémenteurs

Le fonctionnement de votre implémentation varie selon que votre moniker doit avoir un préfixe ; autrement dit, si vous vous attendez à ce que le paramètre pmkToLeft soit NULL ou non. Par exemple, un moniker d’élément, qui identifie un objet dans un conteneur, s’attend à ce que pmkToLeft identifie le conteneur. Un moniker d’élément utilise donc pmkToLeft pour demander des services à partir de ce conteneur. Si vous vous attendez à ce que votre moniker ait un préfixe, vous devez utiliser le paramètre pmkToLeft (par exemple, en appelant BindToObject sur celui-ci) pour demander des services à partir de l’objet qu’il identifie.

Si vous vous attendez à ce que votre moniker n’ait pas de préfixe, votre implémentation BindToObject doit d’abord case activée la table d’objets en cours d’exécution (ROT) pour voir si l’objet est déjà en cours d’exécution. Pour acquérir un pointeur vers le ROT, votre implémentation doit appeler IBindCtx ::GetRunningObjectTable sur le paramètre pbc . Vous pouvez ensuite appeler la méthode IRunningObjectTable ::GetObject pour voir si le moniker actuel a été inscrit dans le ROT. Dans ce cas, vous pouvez appeler immédiatement QueryInterface pour obtenir un pointeur vers l’interface demandée par l’appelant.

Lorsque votre implémentation BindToObject se lie à un objet, elle doit utiliser le paramètre pbc pour appeler IBindCtx ::RegisterObjectBound afin de stocker une référence à l’objet lié dans le contexte de liaison. Cela garantit que l’objet lié reste en cours d’exécution jusqu’à ce que le contexte de liaison soit libéré, ce qui peut éviter les frais de chargement ultérieur d’une opération de liaison ultérieure.

Si la structure BIND_OPTS du contexte de liaison spécifie l’indicateur BINDFLAGS_JUSTTESTEXISTENCE, votre implémentation a la possibilité de retourner NULL dans ppvResult (bien que vous puissiez également ignorer l’indicateur et effectuer l’opération de liaison complète).

Notes spécifiques à l’implémentation

Implémentation	Notes
Anti-moniker	Cette méthode n’est pas implémentée. Elle retourne E_NOTIMPL.
Moniker de classe	Si pmkLeft a la valeur NULL, appelle CoGetClassObject, en utilisant le CLSID avec lequel le moniker de classe a été initialisé (dans CreateClassMoniker ou via MkParseDisplayName) et le CLSCTX du pbc actuel (IBindCtx). Si pmkLeft n’a pas la valeur NULL, appelle pmkLeft-BindToObject> pour IClassActivator et appelle IClassActivator ::GetClassObject avec le CLSID avec lequel il a été initialisé et les paramètres CLSCTX et régionaux du pbc actuel (IBindCtx).
Moniker de fichier	Lorsque pmkToLeft a la valeur NULL, la méthode recherche le moniker dans le ROT et, s’il est trouvé, interroge l’objet récupéré pour le pointeur d’interface demandé. Si le moniker est introuvable dans le ROT, la méthode charge l’objet à partir du système de fichiers et récupère le pointeur d’interface demandé. Si pmkLeft n’a pas la valeur NULL, au lieu de déterminer la classe à instancier et à initialiser avec le contenu du fichier auquel le moniker de fichier fait référence à l’aide de GetClassFile (ou d’autres moyens), appelez pmkLeft-BindToObject> pour IClassFactory et IClassActivator, récupérez ce pointeur dans pcf. Si cela échoue avec E_NOINTERFACE, retournez MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Si le pointeur IClassFactory est correctement récupéré, appelez pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) pour obtenir une nouvelle instance de la classe à initialiser et l’initialiser à l’aide de IPersistFile ou d’autres moyens appropriés selon les chemins d’initialisation existants du moniker de fichier.
Moniker composite générique	Si pmkToLeft a la valeur NULL, cette méthode recherche le moniker dans le ROT et, s’il est trouvé, interroge l’objet récupéré pour le pointeur d’interface demandé. Si pmkToLeft n’est pas NULL, la méthode appelle de manière récursive BindToObject sur le composant le plus à droite du composite, en passant le reste du composite en tant que paramètre pmkToLeft pour cet appel.
Moniker d’élément	Si pmkToLeft a la valeur NULL, cette méthode retourne E_INVALIDARG. Sinon, la méthode appelle BindToObject sur le paramètre pmkToLeft , en demandant un pointeur d’interface IOleItemContainer . La méthode appelle ensuite IOleItemContainer ::GetObject, en passant la chaîne contenue dans le moniker, puis retourne le pointeur d’interface demandé.
MONIKER OBJREF	Le paramètre pmkToLeft doit être NULL. Étant donné que le moniker OBJREF représente un objet en cours d’exécution, aucune activation n’a lieu. Si l’objet représenté n’est plus en cours d’exécution, BindToObject échoue avec E_UNEXPECTED.
Moniker de pointeur	Cette méthode interroge le pointeur encapsulé pour l’interface demandée.
Moniker d’URL	Étant donné que l’URL Moniker prend en charge la liaison asynchrone, la valeur de retour réelle de son Objet BindToObject peut varier en fonction des paramètres d’objet établis dans le contexte de liaison. Pour plus d’informations, voir plus bas.

La sémantique de l’opération de liaison pour un moniker d’URL est identique quelle que soit l’utilisation synchrone ou asynchrone, et se présente comme suit :

Le moniker d’URL extrait des informations supplémentaires pour l’opération de liaison à partir du contexte de liaison. Par exemple, le moniker peut obtenir des pointeurs vers les interfaces IBindStatusCallback et IEnumFORMATETC inscrites dans le contexte de liaison. D’autres informations peuvent inclure des options de liaison supplémentaires spécifiées dans le contexte de liaison via IBindCtx ::SetBindOptions, telles que le paramètre dwTickCountDeadline ou la valeur grfFlags de BIND_MAYBOTHERUSER.
Ensuite, le moniker vérifie le ROT du contexte de liaison pour déterminer si l’objet référencé est déjà en cours d’exécution. Le moniker peut obtenir ces informations avec les appels suivants :
```
IBindCtx::GetRunningObjectTable(&amp;prot)
prot-&gt;IsRunning(this)
```
Si l’objet est déjà en cours d’exécution, le moniker récupère l’objet en cours d’exécution avec l’appel suivant :
```
prot-&gt;GetObject(this, &amp;punk)
```
Ensuite, le moniker appelle QueryInterface pour l’interface demandée.
Sinon, le moniker interroge le client en appelant IBindStatusCallback ::GetBindInfo pour obtenir des informations de liaison supplémentaires. Le moniker lance ensuite l’opération de liaison et transmet l’interface IBinding résultante au client en appelant IBindStatusCallback ::OnStartBinding.
Si à l’étape 1, il a été déterminé qu’il s’agissait d’une liaison asynchrone, BindToObject retourne MK_S_ASYNCHRONOUS à ce stade avec NULL dans ppv. L’appelant recevra le pointeur d’objet réel pendant la méthode IBindStatusCallback ::OnObjectAvailable ultérieurement. Les étapes suivantes se produisent ensuite de manière asynchrone pour l’appelant, généralement sur un autre thread d’exécution.
La classe de la ressource désignée par l’URL Moniker est déterminée de l’une des manières suivantes :
- Le moniker d’URL examine le type de média des données. Si le type de média est application/x-oleobject, les 16 premiers octets des données réelles (Content-Body) contiennent le CLSID de la ressource et les données suivantes doivent être interprétées par la classe elle-même. Pour tous les autres types de médias, URL Moniker recherche dans le Registre système la clé HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID. Notez que application/x-oleobject sera utilisé jusqu’à ce que l’application/oleobject soit approuvée.
- Le moniker d’URL met en correspondance des parties des données arrivantes aux modèles enregistrés dans le registre système sous HKEY_CLASSES_ROOT\FileTypes.
- Enfin, si tout le reste échoue, l’URL Moniker met en corrélation l’extension de fin de la ressource, le cas échéant, avec un CLSID à l’aide du HKEY_CLASSES_ROOT\. ??? clés dans le registre système, comme le fait GetClassFile et l’interpréteur de commandes.
Après avoir déterminé la classe, le moniker d’URL crée un instance à l’aide de CoCreateInstance de CLSCTX_SERVER demandant l’interface IUnknown.
Le moniker d’URL appelle ensuite la méthode QueryInterface de l’objet nouvellement créé pour l’interface IPersistMoniker . Si QueryInterface réussit, le moniker d’URL appelle IPersistMoniker ::Load en se transmettant (this) comme paramètre moniker. L’objet appelle généralement BindToStorage en demandant l’interface de stockage qui l’intéresse.
Sinon, le moniker d’URL appelle QueryInterface pour IPersistStream et, en cas de réussite, appelle IPersistStream ::Load, en passant à l’objet un pointeur IStream pour un objet de flux qui est rempli de manière asynchrone par le transport.
Si la classe appelée n’est pas marquée avec la catégorie CATID_AsyncAware, les appels à ISequentialStream ::Read ou ISequentialStream ::Write font référence à un bloc de données qui ne sont pas encore disponibles jusqu’à ce que les données soient disponibles. Ces appels sont bloqués au sens com traditionnel. Une boucle de message est entrée, ce qui permet à certains messages d’être traités, et le IMessageFilter du thread est appelé de manière appropriée.

Si la classe est marquée avec la catégorie CATID_AsyncAware, les appels à ISequentialStream ::Read ou ISequentialStream ::Write qui référencent des données qui ne sont pas encore disponibles retournent E_PENDING.
Sinon, le moniker d’URL appelle QueryInterface pour IPersistFile et, s’il réussit, termine le téléchargement dans un fichier temporaire. Une fois l’opération terminée, le moniker d’URL appelle IPersistFile ::Load. Le fichier créé est mis en cache avec d’autres données téléchargées sur Internet. Le client doit être sûr de ne pas supprimer ce fichier.
Lorsque l’objet retourne un des différents appels Load décrits dans les étapes précédentes, le moniker d’URL appelle la méthode IBindStatusCallback ::OnObjectAvailable pour retourner le pointeur d’interface que le client a demandé à l’origine lorsque le client a appelé BindToObject.

Configuration requise

Condition requise	Valeur
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

BindMoniker

IMoniker