IDataAdviseHolder::Advise-Methode (objidl.h)

  • Artikel

Erstellt eine Verbindung zwischen einer Empfehlungssenke und einem Datenobjekt zum Empfangen von Benachrichtigungen.

Syntax

HRESULT Advise(
  [in]  IDataObject *pDataObject,
  [in]  FORMATETC   *pFetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvise,
  [out] DWORD       *pdwConnection
);

Parameter

[in] pDataObject

Ein Zeiger auf die IDataObject-Schnittstelle für das Datenobjekt, für das Benachrichtigungen angefordert werden. Wenn sich die Daten in diesem Objekt ändern, wird eine Benachrichtigung an die Beratungssenken gesendet, die eine Benachrichtigung angefordert haben.

[in] pFetc

Ein Zeiger auf eine FORMATETC-Struktur , die das angegebene Format, das angegebene Medium und das angegebene Zielgerät enthält, das für die Benachrichtigungssenke von Interesse ist. 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, die die Empfehlungsverbindung steuern. 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; eine ausführlichere Beschreibung finden Sie in der Beschreibung der ADVF-Enumeration .

Wert Bedeutung
ADVF_NODATA
 Fordert auf, dass keine Daten zusammen mit der Benachrichtigung gesendet werden.
ADVF_ONLYONCE
 Bewirkt, dass die Empfehlungsverbindung nach dem Senden der ersten Benachrichtigung zerstört wird. Ein impliziter Aufruf von IDataAdviseHolder::Unadvise erfolgt im Namen des Aufrufers, um die Verbindung zu entfernen.
ADVF_PRIMEFIRST
 Bewirkt, dass eine anfängliche Benachrichtigung gesendet wird, unabhängig davon, ob sich daten vom aktuellen Zustand geändert haben.
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. Wenn ADVF_NODATA nicht angegeben ist, hat dieses Flag keine Auswirkung.

[in] pAdvise

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

[out] pdwConnection

Ein Zeiger auf eine Variable, die ein Token empfängt, das diese Verbindung identifiziert. Das aufrufende Objekt kann die Empfehlungsverbindung später löschen, indem dieses Token an IDataAdviseHolder::Unadvise übergeben wird. Wenn dieser Wert 0 (null) ist, wurde die Verbindung nicht hergestellt.

Rückgabewert

Diese Methode gibt S_OK bei Erfolg zurück.

Hinweise

Durch die über diese Methode hergestellte Verbindung kann die Beratungssenke zukünftige Benachrichtigungen in einem Aufruf von IAdviseSink::OnDataChange empfangen.

Ein Objekt ruft IDataObject::D Advise auf, um Benachrichtigungen über Änderungen am Format, medium oder Zielgerät von Interesse anzufordern. Diese Daten werden im pFormatetc-Parameter angegeben. Die DAdvise-Methode wird in der Regel implementiert, um IDataAdviseHolder::Advise aufzurufen, um die Aufgabe des Einrichtens und Nachverfolgens einer Verbindung an den Empfehlungsinhaber zu delegieren. Wenn sich das Format, das Medium oder das Zielgerät ändert, ruft das Datenobjekt IDataAdviseHolder::SendOnDataChange auf, um die erforderlichen Benachrichtigungen zu senden.

Die hergestellte Verbindung kann gelöscht werden, indem der Wert in pdwConnection in einem Aufruf von IDataAdviseHolder::Unadvise übergeben wird.

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

IDataAdviseHolder

IDataObject::D Advise