IDataAdviseHolder::Advise メソッド (objidl.h)

  • [アーティクル]

通知を受信するためのアドバイズ シンクとデータ オブジェクトの間の接続を作成します。

構文

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

パラメーター

[in] pDataObject

通知が要求されるデータ オブジェクトの IDataObject インターフェイスへのポインター。 このオブジェクトのデータが変更されると、通知を要求したアドバイズ シンクに通知が送信されます。

[in] pFetc

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

[in] advf

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

値 意味
ADVF_NODATA
 通知と共にデータを送信しないよう求めます。
ADVF_ONLYONCE
 最初の通知が送信された後、アドバイザリ接続が破棄されます。 IDataAdviseHolder::Unadvise への暗黙的な呼び出しは、呼び出し元に代わって行われ、接続が削除されます。
ADVF_PRIMEFIRST
 データが現在の状態から変更されたかどうかに関係なく、初期通知を送信します。
ADVF_DATAONSTOP
 ADVF_NODATAで指定すると、このフラグにより、データ オブジェクトが破棄される前に、含まれるデータを含む最後の通知が送信されます。 ADVF_NODATAが指定されていない場合、このフラグは無効です。

[in] pAdvise

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

[out] pdwConnection

この接続を識別するトークンを受け取る変数へのポインター。 呼び出し元のオブジェクトは、後でこのトークンを IDataAdviseHolder::Unadvise に渡すことで、アドバイザリ接続を削除できます。 この値が 0 の場合、接続は確立されていません。

戻り値

このメソッドは、成功したS_OKを返します。

注釈

このメソッドを介して確立された接続を通じて、アドバイザリ シンクは IAdviseSink::OnDataChange の呼び出しで今後の通知を受け取ることができます。

オブジェクトは IDataObject::D Advise の呼び出しを発行して、目的の形式、中、またはターゲット デバイスの変更に関する通知を要求します。 このデータは pFormatetc パラメーターで指定されます。 DAdvise メソッドは、通常、IDataAdviseHolder::Advise を呼び出して、アドバイス 所有者への接続を設定および追跡するタスクを委任するために実装されます。 対象のデバイスの形式、中、またはターゲットが変更されると、データ オブジェクトは IDataAdviseHolder::SendOnDataChange を呼び出して必要な通知を送信します。

確立された接続を削除するには、IDataAdviseHolder::Unadvise の呼び出しで pdwConnection に値を渡します。

要件

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

こちらもご覧ください

CreateDataAdviseHolder

IDataAdviseHolder

IDataObject::D Advise