IDataObject::D Advise メソッド (objidl.h)

  • [アーティクル]

アドバイズ シンクをサポートするオブジェクトによって呼び出され、データ オブジェクトとアドバイズ シンクの間に接続が作成されます。 これにより、アドバイズ シンクにオブジェクトのデータの変更が通知されます。

構文

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

パラメーター

[in] pformatetc

将来の通知に使用される形式、ターゲット デバイス、アスペクト、およびメディアを定義する FORMATETC 構造体へのポインター。 たとえば、1 つのシンクは、データ オブジェクト内のデータのビットマップ表現が変更された場合にのみ知りたい場合があります。 別のシンクは、同じオブジェクトのメタファイル形式のみに関心がある場合があります。 関心のあるデータが変更されると、各アドバイス シンクに通知されます。 通知が発生すると、このデータはアドバイズ シンクに返されます。

[in] advf

アドバイザリ接続を制御するためのフラグのグループ。 指定できる値は、 ADVF 列挙からの値です。 ただし、この方法に関連するのは、考えられる ADVF 値の一部のみです。 次の表では、関連する値について簡単に説明します。

ADVF 値 説明
ADVF_NODATA 通知でデータを送信しないようにデータ オブジェクトに要求します。 通常、データは送信されます。 このフラグは、既定の動作をオーバーライドする方法です。 ADVF_NODATAを使用する場合、OnDataChange に渡される STGMEDIUM 構造体の tymed メンバーには通常、TYMED_NULLが含まれます。 呼び出し元は、後続の IDataObject::GetData 呼び出しでデータを取得できます。
ADVF_ONLYONCE 最初の変更通知が送信された後、アドバイザリ接続が破棄されます。 IDataObject::D Unadvise への暗黙的な呼び出しは、呼び出し元に代わって行われ、接続を削除します。
ADVF_PRIMEFIRST 追加の初期通知を要求します。 ADVF_ONLYONCEとADVF_PRIMEFIRSTの組み合わせにより、実質的には非同期 IDataObject::GetData 呼び出しが提供されます。
ADVF_DATAONSTOP ADVF_NODATAで指定すると、このフラグにより、データ オブジェクトが破棄される前に、含まれるデータを含む最後の通知が送信されます。

ADVF_NODATAせずに使用する場合、 DAdvise は次のいずれかの方法で実装できます。

  • ADVF_DATAONSTOPは無視できます。
  • オブジェクトは、ADVF_NODATAが指定されたかのように動作できます。
変更通知は、シャットダウンの場合にのみ送信されます。 シャットダウン前にデータを変更しても、通知は送信されません。

[in] pAdvSink

変更通知を受け取るアドバイザリ シンクの IAdviseSink インターフェイスへのポインター。

[out] pdwConnection

この接続を識別するトークン。 このトークンは、後で使用してアドバイザリ接続を削除できます ( IDataObject::D Unadvise に渡します)。 この値が 0 の場合、接続は確立されませんでした。

戻り値

このメソッドは、成功したS_OKを返します。 その他の使用可能な値は次のとおりです。

リターン コード 説明
E_NOTIMPL
 このメソッドは、データ オブジェクトには実装されていません。
DV_E_LINDEX
 lindex の値が無効です。現在、-1 のみがサポートされています。
DV_E_FORMATETC
 pformatetc の値が無効です。
OLE_E_ADVISENOTSUPPORTED
 データ オブジェクトは、変更通知をサポートしていません。

注釈

DAdvise は 、データ オブジェクトと呼び出し元の間に変更通知接続を作成します。 呼び出し元は、オブジェクトのデータが変更されたときに通知を送信できるアドバイザリ シンクを提供します。

データ転送に単純に使用されるオブジェクトは、通常、アドバイザリ通知をサポートせず、 DAdvise からOLE_E_ADVISENOTSUPPORTEDを返します。

呼び出し元へのメモ

アドバイズ シンクをサポートするオブジェクトは 、DAdvise を呼び出して接続を設定し、渡される FORMATETC 構造体の対象となる形式、アスペクト、メディア、ターゲット デバイスを指定します。 データ オブジェクトが要求された属性の 1 つ以上または通知の送信をまったくサポートしていない場合は、OLE_E_ADVISENOTSUPPORTEDを返すことによって接続を拒否できます。

リンク オブジェクトのコンテナーは、バインドされたリンク ソースと直接、または接続を管理する標準 OLE リンク オブジェクトを介して間接的にアドバイザリ接続を設定できます。 バインドされたリンク ソースで設定Connectionsは自動的には削除されません。 アドバイザリ接続を削除するには、バインドされたリンク ソースで IDataObject::D Unadvise を明示的に呼び出す必要があります。 IOleLink インターフェイスを介して操作される OLE リンク オブジェクトは、既定のハンドラーに実装されます。 OLE リンク オブジェクトを使用して設定Connectionsは、リンク オブジェクトが削除されると破棄されます。

OLE の既定のリンク オブジェクトは、リンク ソースで "ワイルドカード アドバイス" を作成し、OLE が最後の変更時刻を維持できるようにします。 このアドバイスは、特に何か変更された時間をメモするために使用されます。 OLE では、変更された可能性のあるすべてのデータ形式が無視され、最後の変更時刻のみが表示されます。 ワイルドカード アドバイスを許可するには、DAdvise を呼び出す前に FORMATETC メンバーを次のように設定します。

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

アドバイス フラグには、ADVF_NODATAも含める必要があります。 OLE からのワイルドカード のアドバイスは、常にアプリケーションで受け入れる必要があります。

実装者へのメモ

通知をサポートする IDataObject (DUnadvise および EnumDAdvise) での DAdvise およびその他の通知メソッドの実装を簡略化するために、OLE は通知の登録と送信を管理するアドバイス ホルダー オブジェクトを提供します。 このオブジェクトへのポインターを取得するには、 DAdvise の最初の呼び出しでヘルパー関数 CreateDataAdviseHolder を呼び出します。 これにより、オブジェクトの IDataAdviseHolder インターフェイスへのポインターが提供されます。 次に、要求された接続を作成し、その後管理するデータ アドバイズ ホルダーの IDataAdviseHolder::Advise メソッドに呼び出しを委任します。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー objidl.h

こちらもご覧ください

CreateDataAdviseHolder

IAdviseSink::OnDataChange

Idataobject