IMoniker::BindToObject-Methode (objidl.h)

Artikel
08/25/2023

Bindet an das angegebene Objekt. Der Bindungsprozess umfasst das Suchen des Objekts, das Versetzen es bei Bedarf in den Ausführungszustand und das Bereitstellen eines Zeigers auf eine angegebene Schnittstelle für das identifizierte Objekt.

Syntax

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

Parameter

[in] pbc

Ein Zeiger auf die IBindCtx-Schnittstelle für das Bindungskontextobjekt, das in diesem Bindungsvorgang verwendet wird. Der Bindungskontext speichert Objekte, die während des Bindungsprozesses gebunden sind, enthält Parameter, die für alle Vorgänge mit dem Bindungskontext gelten, und stellt die Mittel bereit, mit denen die Monikerimplementierung Informationen zu ihrer Umgebung abrufen soll.

[in] pmkToLeft

Wenn der Moniker Teil eines zusammengesetzten Monikers ist, zeiger auf den Moniker links neben diesem Moniker. Dieser Parameter wird hauptsächlich von Monikerimplementierern verwendet, um die Zusammenarbeit zwischen den verschiedenen Komponenten eines zusammengesetzten Monikers zu ermöglichen. Moniker-Clients sollten NULL verwenden.

[in] riidResult

Die IID der Schnittstelle, die der Client verwenden möchte, um mit dem Objekt zu kommunizieren, das der Moniker identifiziert.

[out] ppvResult

Die Adresse der Zeigervariable, die den in riid angeforderten Schnittstellenzeiger empfängt. Nach erfolgreicher Rückgabe enthält *ppvResult den angeforderten Schnittstellenzeiger auf das Objekt, das der Moniker identifiziert. Wenn die Implementierung erfolgreich ist, muss AddRef für den Moniker aufgerufen werden. Es liegt in der Verantwortung des Aufrufers , Release aufzurufen. Wenn ein Fehler auftritt, sollte *ppvResultNULL sein.

Rückgabewert

Diese Methode kann die standardmäßigen Rückgabewerte E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Der Bindungsvorgang war erfolgreich.
MK_E_NOOBJECT	Das durch diesen Moniker identifizierte Objekt oder ein Objekt, das durch den zusammengesetzten Moniker identifiziert wurde, zu dem dieser Moniker gehört, konnte nicht gefunden werden.
MK_E_EXCEEDEDDEADLINE	Der Bindungsvorgang konnte nicht innerhalb des durch die BIND_OPTS-Struktur des Bindungskontexts angegebenen Frist abgeschlossen werden.
MK_E_CONNECTMANUALLY	Für den Bindungsvorgang ist die Unterstützung des Endbenutzers erforderlich. Der häufigste Grund für die Rückgabe dieses Werts ist, dass ein Kennwort erforderlich ist oder dass eine Diskette bereitgestellt werden muss. Wenn dieser Wert zurückgegeben wird, rufen Sie den Moniker ab, der den Fehler verursacht hat, mit einem Aufruf von IBindCtx::GetObjectParam mit dem Schlüssel "ConnectManually". Sie können dann IMoniker::GetDisplayName aufrufen, um den Anzeigenamen abzurufen, ein Dialogfeld anzeigen, das die gewünschten Informationen kommuniziert, z. B. Anweisungen zum Einbinden einer Diskette oder einer Anforderung für ein Kennwort, und dann den Bindungsvorgang wiederholen.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Es wurde ein Zwischenobjekt gefunden, aber es hat keine Schnittstelle unterstützt, die zum Abschließen des Bindungsvorgangs erforderlich ist. Beispielsweise gibt ein Elementmoniker diesen Wert zurück, wenn sein Container die IOleItemContainer-Schnittstelle nicht unterstützt.
STG_E_ACCESSDENIED	Auf das Speicherobjekt kann nicht zugegriffen werden.

Diese Methode kann auch die Fehler zurückgeben, die der IOleItemContainer::GetObject-Methode zugeordnet sind.

Hinweise

BindToObject implementiert die primäre Funktion eines Monikers, die darin besteht, das durch den Moniker identifizierte Objekt zu suchen und einen Zeiger auf eine seiner Schnittstellen zurückzugeben.

Hinweise für Anrufer

Wenn Sie einen Moniker als dauerhafte Verbindung zwischen zwei Objekten verwenden, aktivieren Sie die Verbindung, indem Sie BindToObject aufrufen.

In der Regel rufen Sie BindToObject während des folgenden Prozesses auf:

Erstellen Sie ein Bindkontextobjekt mit einem Aufruf der CreateBindCtx-Funktion .
Rufen Sie BindToObject mithilfe des Monikers auf, und rufen Sie einen Zeiger auf eine gewünschte Schnittstelle für das identifizierte Objekt ab.
Geben Sie den Bindungskontext frei.
Führen Sie über den abgerufenen Schnittstellenzeiger die gewünschten Vorgänge für das Objekt aus.
Wenn Sie mit dem -Objekt fertig sind, lassen Sie den Schnittstellenzeiger des Objekts los.

Das folgende Codefragment veranschaulicht diese Schritte.

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();

Sie können die BindMoniker-Funktion auch verwenden, wenn Sie nur einen Bindungsvorgang beabsichtigen und das Bindkontextobjekt nicht beibehalten müssen. Diese Hilfsfunktion kapselt die Erstellung des Bindungskontexts, ruft BindToObject auf und gibt den Bindungskontext frei.

COM-Container, die Verknüpfungen zu Objekten unterstützen, verwenden Moniker, um das verknüpfte Objekt zu suchen und Zugriff darauf zu erhalten, rufen jedoch BindToObject in der Regel nicht direkt auf. Wenn ein Benutzer stattdessen einen Link in einem Container aktiviert, ruft der Linkcontainer in der Regel IOleObject::D oVerb auf, wobei die Implementierung des Linkhandlers verwendet wird, die BindToObject für den im verknüpften Objekt gespeicherten Moniker aufruft (wenn er das Verb nicht verarbeiten kann).

Hinweise für Implementierer

Was Ihre Implementierung tut, hängt davon ab, ob Sie erwarten, dass Ihr Moniker ein Präfix hat. d. h. unabhängig davon, ob Sie den Parameter pmkToLeft als NULL erwarten oder nicht. Beispielsweise erwartet ein Elementmoniker, der ein Objekt in einem Container identifiziert, dass pmkToLeft den Container identifiziert. Ein Elementmoniker verwendet daher pmkToLeft , um Dienste von diesem Container anzufordern. Wenn Sie erwarten, dass Ihr Moniker ein Präfix hat, sollten Sie den parameter pmkToLeft (z. B. den Aufruf von BindToObject ) verwenden, um Dienste von dem identifizierten Objekt anzufordern.

Wenn Sie erwarten, dass Ihr Moniker kein Präfix hat, sollte Ihre BindToObject-Implementierung zuerst die laufende Objekttabelle (ROT) überprüfen, um festzustellen, ob das Objekt bereits ausgeführt wird. Um einen Zeiger auf die ROT abzurufen, sollte Ihre Implementierung IBindCtx::GetRunningObjectTable für den pbc-Parameter aufrufen. Anschließend können Sie die IRunningObjectTable::GetObject-Methode aufrufen, um festzustellen, ob der aktuelle Moniker in rot registriert wurde. Wenn ja, können Sie sofort QueryInterface aufrufen, um einen Zeiger auf die vom Aufrufer angeforderte Schnittstelle zu erhalten.

Wenn Ihre BindToObject-Implementierung an ein Objekt gebunden wird, sollte sie den pbc-Parameter verwenden, um IBindCtx::RegisterObjectBound aufzurufen, um einen Verweis auf das gebundene Objekt im Bindungskontext zu speichern. Dadurch wird sichergestellt, dass das gebundene Objekt ausgeführt wird, bis der Bindungskontext freigegeben wird, wodurch der Aufwand vermieden werden kann, dass es später von einem nachfolgenden Bindungsvorgang erneut geladen wird.

Wenn die BIND_OPTS-Struktur des Bindungskontexts das BINDFLAGS_JUSTTESTEXISTENCE-Flag angibt, hat Ihre Implementierung die Möglichkeit , NULL in ppvResult zurückzugeben (obwohl Sie das Flag auch ignorieren und den vollständigen Bindungsvorgang ausführen können).

Implementierungsspezifische Hinweise

Implementierung	Hinweise
Anti-Moniker	Diese Methode ist nicht implementiert. Es wird E_NOTIMPL zurückgegeben.
Moniker der Klasse	Wenn pmkLeftNULL ist, ruft CoGetClassObject auf, und verwendet dabei die CLSID, mit der der Klassenmoniker initialisiert wurde (in CreateClassMoniker oder über MkParseDisplayName) und die CLSCTX des aktuellen pbc (IBindCtx). Wenn pmkLeft nicht NULL ist, ruft pmkLeft-BindToObject> für IClassActivator auf und ruft IClassActivator::GetClassObject mit der CLSID auf, mit der es initialisiert wurde, und den CLSCTX - und Gebietsschemaparametern des aktuellen pbc (IBindCtx).
Dateimoniker	Wenn pmkToLeftNULL ist, sucht die Methode nach dem Moniker in rot und fragt das abgerufene Objekt nach dem angeforderten Schnittstellenzeiger ab, falls gefunden. Wenn der Moniker nicht in rot gefunden wird, lädt die Methode das Objekt aus dem Dateisystem und ruft den angeforderten Schnittstellenzeiger ab. Wenn pmkLeft nicht NULL ist, rufen Sie pmkLeft-BindToObject> für IClassFactory und IClassActivator auf, anstatt die Klasse zu bestimmen, die mit dem Dateimoniker mit GetClassFile (oder anderen Mitteln) instanziiert und initialisiert werden soll. Rufen Sie diesen Zeiger in pcf ab. Wenn dies mit E_NOINTERFACE fehlschlägt, geben Sie MK_E_INTERMEDIATEINTERFACENOTSUPPORTED zurück. Wenn der IClassFactory-Zeiger erfolgreich abgerufen wurde, rufen Sie pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) auf, um eine neue instance der zu initialisierenden Klasse zu erhalten, und initialisieren Sie sie mithilfe von IPersistFile oder einer anderen geeigneten Methode gemäß den vorhandenen Initialisierungspfaden des Dateimonikers.
Generischer zusammengesetzter Moniker	Wenn pmkToLeftNULL ist, sucht diese Methode nach dem Moniker im ROT und fragt, falls gefunden, das abgerufene Objekt nach dem angeforderten Schnittstellenzeiger ab. Wenn pmkToLeft nicht NULL ist, ruft die Methode Rekursiv BindToObject auf der äußersten rechten Komponente des zusammengesetzten Elements auf und übergibt den Rest der zusammengesetzten Komponente als pmkToLeft-Parameter für diesen Aufruf.
Elementmoniker	Wenn pmkToLeftNULL ist, gibt diese Methode E_INVALIDARG zurück. Andernfalls ruft die Methode BindToObject für den parameter pmkToLeft auf und fordert einen IOleItemContainer-Schnittstellenzeiger an. Die -Methode ruft dann IOleItemContainer::GetObject auf, übergibt die im Moniker enthaltene Zeichenfolge und gibt den angeforderten Schnittstellenzeiger zurück.
OBJREF-Moniker	Der parameter pmkToLeft muss NULL sein. Da der OBJREF-Moniker ein ausgeführtes Objekt darstellt, erfolgt keine Aktivierung. Wenn das dargestellte Objekt nicht mehr ausgeführt wird, schlägt BindToObject mit E_UNEXPECTED fehl.
Zeigermoniker	Diese Methode fragt den umschlossenen Zeiger für die angeforderte Schnittstelle ab.
URL-Moniker	Da der URL-Moniker die asynchrone Bindung unterstützt, kann der tatsächliche Rückgabewert seines BindToObject-Objekts je nach den im Bindungskontext eingerichteten Objektparametern variieren. Weitere Informationen finden Sie unten.

Die Semantik des Bindungsvorgangs für einen URL-Moniker ist unabhängig von der synchronen oder asynchronen Verwendung identisch und lautet wie folgt:

Der URL-Moniker ruft weitere Informationen für den Bindungsvorgang aus dem Bindungskontext ab. Der Moniker kann beispielsweise Zeiger auf die Schnittstellen IBindStatusCallback und IEnumFORMATETC abrufen, die im Bindungskontext registriert sind. Weitere Informationen können zusätzliche Bindungsoptionen umfassen, die im Bindungskontext über IBindCtx::SetBindOptions angegeben sind, z. B. der dwTickCountDeadline-Parameter oder der grfFlags-Wert von BIND_MAYBOTHERUSER.
Als Nächstes überprüft der Moniker den ROT-Wert des Bindungskontexts, um zu ermitteln, ob das Objekt, auf das verwiesen wird, bereits ausgeführt wird. Der Moniker kann diese Informationen mit den folgenden Aufrufen abrufen:
```
IBindCtx::GetRunningObjectTable(&amp;prot)
prot-&gt;IsRunning(this)
```
Wenn das Objekt bereits ausgeführt wird, ruft der Moniker das ausgeführte Objekt mit dem folgenden Aufruf ab:
```
prot-&gt;GetObject(this, &amp;punk)
```
Anschließend ruft der Moniker QueryInterface für die angeforderte Schnittstelle auf.
Andernfalls fragt der Moniker den Client ab, indem er IBindStatusCallback::GetBindInfo aufruft , um zusätzliche Bindungsinformationen abzurufen. Der Moniker initiiert dann den Bindungsvorgang und übergibt die resultierende IBinding-Schnittstelle zurück an den Client, indem er IBindStatusCallback::OnStartBinding aufruft.
Wenn in Schritt 1 festgestellt wurde, dass es sich um eine asynchrone Bindung handelt, gibt BindToObject MK_S_ASYNCHRONOUS an diesem Punkt mit NULL in ppv zurück. Der Aufrufer empfängt den tatsächlichen Objektzeiger während der IBindStatusCallback::OnObjectAvailable-Methode zu einem späteren Zeitpunkt. Die folgenden Schritte erfolgen dann asynchron für den Aufrufer, in der Regel in einem anderen Ausführungsthread.
Die Klasse der Ressource, die von der Moniker-URL festgelegt wird, wird auf eine der folgenden Arten bestimmt:
- Der URL-Moniker untersucht den Medientyp der Daten. Wenn der Medientyp application/x-oleobject ist, enthalten die ersten 16 Bytes der tatsächlichen Daten (Content-Body) die CLSID der Ressource, und nachfolgende Daten sind von der Klasse selbst zu interpretieren. Für alle anderen Medientypen sucht URL Moniker in der Systemregistrierung nach dem HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<medientyp>\CLSID-Schlüssel. Beachten Sie, dass application/x-oleobject verwendet wird, bis application/oleobject genehmigt wurde.
- Der URL-Moniker gleicht Teile der eingehenden Daten mit Mustern ab, die in der Systemregistrierung unter HKEY_CLASSES_ROOT\FileTypes registriert sind.
- Wenn alles andere fehlschlägt, korreliert die URL Moniker die nachfolgende Erweiterung der Ressource(sofern vorhanden) mit einer CLSID unter Verwendung des HKEY_CLASSES_ROOT\.??? Schlüssel in der Systemregistrierung, wie dies von GetClassFile und der Shell geschieht.
Nachdem die Klasse ermittelt wurde, erstellt der URL-Moniker eine instance mithilfe von CoCreateInstance von CLSCTX_SERVER, die nach der IUnknown-Schnittstelle fragt.
Der URL-Moniker ruft als Nächstes die QueryInterface-Methode des neu erstellten Objekts für die IPersistMoniker-Schnittstelle auf. Wenn QueryInterface erfolgreich ist, ruft der URL-Moniker IPersistMoniker::Load auf, der sich selbst (this) als moniker-Parameter übergibt. Das -Objekt ruft in der Regel BindToStorage auf und fragt nach der Speicherschnittstelle, an der es interessiert ist.
Andernfalls ruft der URL-Moniker QueryInterface für IPersistStream auf und ruft bei erfolgreicher Ausführung IPersistStream::Load auf, wobei dem Objekt ein IStream-Zeiger für ein Streamobjekt übergeben wird, das asynchron vom Transport ausgefüllt wird.
Wenn die aufgerufene Klasse nicht mit der Kategorie CATID_AsyncAware gekennzeichnet ist, rufen Sie ISequentialStream::Read oder ISequentialStream::Schreiben auf, dass die Referenzdaten noch nicht verfügbar sind, bis die Daten verfügbar sind. Diese Aufrufe blockieren im herkömmlichen COM-Sinne. Es wird eine Nachrichtenschleife eingegeben, mit der bestimmte Nachrichten verarbeitet werden können, und der IMessageFilter des Threads wird entsprechend aufgerufen.

Wenn die Klasse mit der Kategorie CATID_AsyncAware gekennzeichnet ist, geben Aufrufe von ISequentialStream::Read oder ISequentialStream::Write die noch nicht verfügbaren Referenzdaten E_PENDING zurück.
Andernfalls ruft der URL-Moniker QueryInterface für IPersistFile auf und schließt bei erfolgreicher Ausführung den Download in eine temporäre Datei ab. Nach Abschluss ruft der URL-Moniker IPersistFile::Load auf. Die erstellte Datei wird zusammen mit anderen heruntergeladenen Internetdaten zwischengespeichert. Der Client muss sicherstellen, dass diese Datei nicht gelöscht wird.
Wenn das Objekt von einem der verschiedenen Load-Aufrufe zurückgibt, die in den vorherigen Schritten beschrieben wurden, ruft der URL-Moniker die IBindStatusCallback::OnObjectAvailable-Methode auf, um den Schnittstellenzeiger zurückzugeben, den der Client ursprünglich angefordert hat, als der Client BindToObject aufgerufen hat.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	objidl.h

Weitere Informationen

BindMoniker

Imoniker