IMAPITable::Advise

適用対象: Outlook 2013 | Outlook 2016

テーブルに影響を与える指定されたイベントの通知を受信するようにシンク オブジェクトにアドバイスを登録します。

HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

パラメーター

ulEventMask

[in]通知を生成するイベントの種類を示す値。 有効な値は次のとおりです。

fnevTableModified

lpAdviseSink

[in]後続の通知を受け取るシンク オブジェクトへのポインター。 このアドバイスシンク オブジェクトは既に割り当てられている必要があります。

lpulConnection

[out]正常な通知登録を表す 0 以外の値へのポインター。

戻り値

S_OK

通知の登録が正常に完了しました。

MAPI_E_NO_SUPPORT

テーブルの実装では、行と列の変更がサポートされていないか、通知がサポートされていません。

注釈

IMAPITable::Advise メソッドを使用して、通知コールバック用にプロバイダーに実装されたテーブル オブジェクトを登録します。 テーブル オブジェクトに変更が発生するたびに、プロバイダーは 、ulEventMask パラメーターに設定されたイベント マスク ビットと、発生した変更の種類を確認します。 ビットが設定されている場合、プロバイダーは IMAPIAdviseSink::OnNotify メソッドを呼び出して、 lpAdviseSink パラメーターによって示されるアドバイズ シンク オブジェクトに対してイベントを報告します。 通知構造体で OnNotify ルーチンに渡されるデータは、イベントを記述します。

OnNotify の呼び出しは、オブジェクトを変更する呼び出し中、または次の時点で行うことができます。 複数の実行スレッドをサポートするシステムでは、 OnNotify の呼び出しはどのスレッドでも実行できます。 不都合なタイミングで発生する可能性がある OnNotify の呼び出しを、処理する方が安全な呼び出しに変換するには、プロバイダーは HrThisThreadAdviseSink 関数を使用する必要があります。

通知を提供するには、 アドバイス を実装するプロバイダーは、 lpAdviseSink アドバイズ シンク オブジェクトへのポインターのコピーを保持する必要があります。これを行うには、 IUnknown::AddRef メソッドを呼び出して、通知登録が IMAPITable::Unadvise メソッドの呼び出しで取り消されるまでオブジェクト ポインターを維持するように、アドバイズ シンクを呼び出します。 Advise 実装では、通知登録に接続番号を割り当て、この接続番号に対して AddRef を呼び出してから lpulConnection パラメーターに返す必要があります。 サービス プロバイダーは、登録が取り消される前にアドバイズ シンク オブジェクトを解放できますが、 Unadvise が呼び出されるまで接続番号を解放しないでください。

Advise の呼び出しが成功した後、Unadvise が呼び出される前に、アドバイズ シンク オブジェクトが解放されるようにクライアントを準備する必要があります。 したがって、クライアントは、特定の長期的な使用がない限り 、アドバイズ が戻った後にアドバイズ シンク オブジェクトを解放する必要があります。

通知の非同期動作により、テーブル列の設定を変更する実装では、前の列の順序で整理された情報を含む通知を受け取ることができます。 たとえば、コンテナーから削除したばかりのメッセージのテーブル行が返される場合があります。 このような通知は、列設定の変更が行われ、それに関する情報が送信されたが、通知テーブル ビューがまだその情報で更新されていない場合に送信されます。

通知プロセスの詳細については、「 MAPI でのイベント通知」を参照してください。 テーブル通知の詳細については、「テーブル通知 について」を参照してください。 IMAPISupport メソッドを使用して通知をサポートする方法については、「イベント通知のサポート」を参照してください。

MFCMAPI リファレンス

MFCMAPI のサンプル コードについては、次の表を参照してください。

関連項目

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable : コードサンプルとしての IUnknown MFCMAPI