IDataObject::D Advise-Methode (objidl.h)

  • Artikel

Wird von einem Objekt aufgerufen, das eine Empfehlungssenke unterstützt, um eine Verbindung zwischen einem Datenobjekt und der Empfehlungssenke herzustellen. Dadurch kann die Empfehlungssenke über Änderungen an den Daten des Objekts benachrichtigt werden.

Syntax

HRESULT DAdvise(
  [in]  FORMATETC   *pformatetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvSink,
  [out] DWORD       *pdwConnection
);

Parameter

[in] pformatetc

Ein Zeiger auf eine FORMATTC-Struktur , die das Format, das Zielgerät, den Aspekt und das Medium definiert, das für zukünftige Benachrichtigungen verwendet wird. Beispielsweise möchte eine Senke möglicherweise nur wissen, wann sich die Bitmap-Darstellung der Daten im Datenobjekt ändert. Eine andere Senke ist möglicherweise nur am Metadateiformat des gleichen Objekts interessiert. Jede Advise-Senke wird benachrichtigt, wenn sich die relevanten Daten ändern. Diese Daten werden an die Advise-Senke übergeben, wenn eine Benachrichtigung auftritt.

[in] advf

Eine Gruppe von Flags zum Steuern der Beratungsverbindung. Mögliche Werte stammen aus der ADVF-Enumeration . Für diese Methode sind jedoch nur einige der möglichen ADVF-Werte relevant. In der folgenden Tabelle werden die relevanten Werte kurz beschrieben.

ADVF-Wert BESCHREIBUNG
ADVF_NODATA Fordert das Datenobjekt auf, das Senden von Daten mit den Benachrichtigungen zu vermeiden. In der Regel werden Daten gesendet. Dieses Flag ist eine Möglichkeit, das Standardverhalten zu überschreiben. Wenn ADVF_NODATA verwendet wird, enthält das tymed-Element der STGMEDIUM-Struktur , das an OnDataChange übergeben wird, in der Regel TYMED_NULL. Der Aufrufer kann die Daten dann mit einem nachfolgenden IDataObject::GetData-Aufruf abrufen.
ADVF_ONLYONCE Bewirkt, dass die Empfehlungsverbindung nach dem Senden der ersten Änderungsbenachrichtigung zerstört wird. Ein impliziter Aufruf von IDataObject::D Unadvise erfolgt im Namen des Aufrufers, um die Verbindung zu entfernen.
ADVF_PRIMEFIRST Fordert eine zusätzliche anfängliche Benachrichtigung an. Die Kombination aus ADVF_ONLYONCE und ADVF_PRIMEFIRST stellt tatsächlich einen asynchronen IDataObject::GetData-Aufruf bereit.
ADVF_DATAONSTOP Bei Angabe mit ADVF_NODATA bewirkt dieses Flag, dass eine letzte Benachrichtigung mit den enthaltenen Daten gesendet wird, bevor das Datenobjekt zerstört wird.

Bei Verwendung ohne ADVF_NODATA kann DAdvise auf eine der folgenden Arten implementiert werden:

  • Die ADVF_DATAONSTOP kann ignoriert werden.
  • Das Objekt kann sich so verhalten, als ob ADVF_NODATA angegeben wurde.
Eine Änderungsbenachrichtigung wird nur im Fall des Herunterfahrens gesendet. Datenänderungen vor dem Herunterfahren führen nicht dazu, dass eine Benachrichtigung gesendet wird.

[in] pAdvSink

Ein Zeiger auf die IAdviseSink-Schnittstelle in der Empfehlungssenke, die die Änderungsbenachrichtigung empfängt.

[out] pdwConnection

Ein Token, das diese Verbindung identifiziert. Sie können dieses Token später verwenden, um die Empfehlungsverbindung zu löschen (indem Sie sie an IDataObject::D Unadvise übergeben). Wenn dieser Wert 0 ist, wurde die Verbindung nicht hergestellt.

Rückgabewert

Diese Methode gibt S_OK bei Erfolg zurück. Weitere mögliche Werte sind:

Rückgabecode Beschreibung
E_NOTIMPL
 Diese Methode ist bei einem Datenobjekt nicht implementiert.
DV_E_LINDEX
 Der Wert für lindex ist ungültig; derzeit wird nur -1 unterstützt.
DV_E_FORMATETC
 Der Wert für pformatetc ist ungültig.
OLE_E_ADVISENOTSUPPORTED
 Das Datenobjekt unterstützt keine Änderungsbenachrichtigung.

Hinweise

DAdvise erstellt eine Änderungsbenachrichtigungsverbindung zwischen einem Datenobjekt und dem Aufrufer. Der Aufrufer stellt eine Empfehlungssenke bereit, an die die Benachrichtigungen gesendet werden können, wenn sich die Daten des Objekts ändern.

Objekte, die einfach für die Datenübertragung verwendet werden, unterstützen in der Regel keine Empfehlungsbenachrichtigungen und geben OLE_E_ADVISENOTSUPPORTED von DAdvise zurück.

Hinweise für Anrufer

Das Objekt, das die Empfehlungssenke unterstützt, ruft DAdvise auf, um die Verbindung einzurichten und dabei das gewünschte Format, den Aspekt, das Medium und/oder das Zielgerät anzugeben, das in der übergebenen FORMATTC-Struktur von Interesse ist. Wenn das Datenobjekt eines oder mehrere der angeforderten Attribute oder das Senden von Benachrichtigungen überhaupt nicht unterstützt, kann es die Verbindung ablehnen, indem es OLE_E_ADVISENOTSUPPORTED zurückgibt.

Container von verknüpften Objekten können Beratungsverbindungen direkt mit der quelle der gebundenen Verknüpfung oder indirekt über das STANDARDMÄßIGE OLE-Linkobjekt einrichten, das die Verbindung verwaltet. Connections, die mit der Quelle des gebundenen Links eingerichtet wurden, werden nicht automatisch gelöscht. Der Container muss IDataObject::D Unadvise explizit für die gebundene Linkquelle aufrufen, um eine Empfehlungsverbindung zu löschen. Das OLE-Linkobjekt, das über die IOleLink-Schnittstelle bearbeitet wird, wird im Standardhandler implementiert. Connections, die über das OLE-Linkobjekt eingerichtet werden, werden zerstört, wenn das Linkobjekt gelöscht wird.

Das OLE-Standardlinkobjekt erstellt eine "Wildcard-Empfehlung" mit der Linkquelle, damit OLE den Zeitpunkt der letzten Änderung beibehalten kann. Dieser Rat wird speziell verwendet, um die Zeit zu notieren, zu der sich etwas geändert hat. OLE ignoriert alle Datenformate, die sich möglicherweise geändert haben, wobei nur der Zeitpunkt der letzten Änderung berücksichtigt wird. Um Wildcard-Ratschläge zuzulassen, legen Sie die FORMATETC-Member wie folgt fest, bevor Sie DAdvise aufrufen:

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

Die Empfehlungsflags sollten auch ADVF_NODATA enthalten. Wildcard-Ratschläge von OLE sollten von Anwendungen immer akzeptiert werden.

Hinweise für Implementierer

Um die Implementierung von DAdvise und den anderen Benachrichtigungsmethoden in IDataObject (DUnadvise und EnumDAdvise) zu vereinfachen, die Benachrichtigungen unterstützen, stellt OLE ein Empfehlungsinhaberobjekt bereit, das die Registrierung und das Senden von Benachrichtigungen verwaltet. Um einen Zeiger auf dieses Objekt abzurufen, rufen Sie die Hilfsfunktion CreateDataAdviseHolder beim ersten Aufruf von DAdvise auf. Dadurch wird ein Zeiger auf die IDataAdviseHolder-Schnittstelle des Objekts bereitgestellt. Delegieren Sie dann den Aufruf der IDataAdviseHolder::Advise-Methode im Datenberater, der die angeforderte Verbindung erstellt und anschließend verwaltet.

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

CreateDataAdviseHolder

IAdviseSink::OnDataChange

Idataobject