MAPI のイベント通知

適用対象: Outlook 2013 | Outlook 2016

イベント通知は、2 つの MAPI オブジェクト間の情報の通信です。 オブジェクトの 1 つを介して、クライアントまたはサービス プロバイダーは、他のオブジェクトで発生する可能性があるイベントと呼ばれる変更またはエラーの通知を登録します。 イベントが発生すると、最初のオブジェクトに変更またはエラーが通知されます。 通知を受け取るオブジェクトは、アドバイズ シンクと呼ばれます。通知を担当するオブジェクトは、アドバイズ ソースと呼ばれます。

シンク オブジェクトには、次の 3 種類のアドバイスがあります (すべての型は標準の MAPI オブジェクトです)。

• シンク オブジェクトに関するアドバイス。
• Form はシンク オブジェクトをアドバイスします。
• シンク オブジェクトに関するアドバイスを表示します。

シンク オブジェクトが最も一般的な型であることをアドバイスします。 アドバイズ シンクは通常、アドレス帳とメッセージ ストアの通知を受信し、 IMAPIAdviseSink : IUnknown インターフェイスをサポートするためにクライアント アプリケーションによって実装されます。 IMAPIAdviseSink には、 IMAPIAdviseSink::OnNotify という 1 つのメソッドが含まれています。 シンクのフォームとビューのアドバイスはあまり一般的ではありません。これらは、カスタム フォームへの変更に関する通知を受け取るために実装されます。 Form アドバイズ シンクは IMAPIFormAdviseSink をサポートします。IUnknown インターフェイスとビュー アドバイズ シンクは IMAPIViewAdviseSink : IUnknown インターフェイスをサポートしています。 ほとんどのクライアントは標準のアドバイズ シンク オブジェクトを実装しているため、通知の説明は、フォーム通知ではなくアドレス帳とメッセージ ストアの通知に関連していると仮定します。 フォーム通知の詳細については、「 MAPI フォーム 通知」および「 フォーム サーバー コードの記述」を参照してください。

アドバイス ソース オブジェクトは、サービス プロバイダーと MAPI によって実装されます。 すべてのサービス プロバイダーがイベント通知をサポートしているわけではありません。これは省略可能ですが、強くお勧めします。 メッセージ ストアとアドレス帳プロバイダーは、通常、いくつかのオブジェクトに対するオブジェクト通知と、その内容と階層テーブルに対するテーブル通知をサポートします。 トランスポート プロバイダーは、通知を直接サポートしていません。クライアントとの通信の代替方法に依存しています。

アドバイズ シンクとは異なり、アドバイズ ソース オブジェクトは MAPI オブジェクトの一意の種類ではありません。 メッセージ ストアやテーブルなど、多くの MAPI オブジェクトは、アドバイス ソースの役割を担うことができます。 アドバイス ソースは、次の処理を行う MAPI オブジェクトです。

• 通知登録を受け取る Advise メソッドを実装します。

• 通知の取り消しを受け取る Unadvise メソッドを実装します。

• IMAPIAdviseSink::OnNotify メソッドを呼び出して、登録されている適切なアドバイズ シンク オブジェクトに適切な型の通知を生成します。

アドバイズ シンク オブジェクトを実装するクライアントは、通知に登録する場合に アドバイズ を呼び出します。ほとんどの場合、登録が行われるオブジェクトのエントリ識別子を渡し、登録をキャンセルする場合は Unadvise を呼び出します。 クライアントは、監視するイベントの種類を示すパラメーターを アドバイス に渡します。 アドバイズは、アドバイズ シンクとアドバイズ ソース間の正常な接続を表す 0 以外の数値を返します。

アドバイズを呼び出す前に、メッセージ ストア プロバイダーがメッセージ ストアのPR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) プロパティでSTORE_NOTIFY_OK フラグが設定されていることを確認することで、通知をサポートするかどうかをクライアントが判断できます。 アドレス帳プロバイダーが通知をサポートしているかどうかをクライアントが事前に判断する方法はありません。 クライアントは登録を試行する必要があり、試行が失敗した場合、通知がサポートされていないと見なすことができます。

クライアントが登録したイベントが発生すると、アドバイズ ソースは、イベントに関する情報を含む通知データ構造で IMAPIAdviseSink::OnNotify メソッドを呼び出すことによって、アドバイズ シンクに通知します。 OnNotify のアドバイズ シンクの実装では、メモリ内のデータの更新や画面表示の更新など、通知に応答してタスクを実行できます。

サービス プロバイダーは、通知のサポートを手動で実装することも、IMAPISupport::Subscribe、IMAPISupport::Unsubscribe、IMAPISupport::Notify の 3 つの IMAPISupport メソッドで提供されているヘルプを利用することもできます。 Subscribe メソッドと Unsubscribe メソッドは、プロバイダーの通知登録と登録解除を処理します。Notify メソッドは、必要に応じて通知の送信を処理します。

通知登録にサポート オブジェクト メソッドを使用するために、サービス プロバイダーは、そのアドバイズ メソッドで IMAPISupport::Subscribe を呼び出し、クライアントがアドバイズに渡すアドバイズ シンク ポインターをサブスクライブに渡します。 入力パラメーターとしてエントリ識別子を渡してアドバイス ソースを指定する場合、サービス プロバイダーはそれをバイナリ キーに変換します。 Subscribe は、一意の接続番号を作成し、サービス プロバイダーがクライアントに返すこの番号です。 サービス プロバイダーは、アドバイズ呼び出しが完了した後、いつでもクライアントの アドバイズ シンク オブジェクト ポインターを解放できます。

クライアントが Unadvise を呼び出して登録を取り消すと、サービス プロバイダーは、クライアントのアドバイズ シンク ポインターの参照カウントをデクリメントするか 、Unsubscribe を呼び出して同じ操作を行います。

通知を生成するとき、サービス プロバイダーは通知に関連する内部処理を実行し、未使用のメンバーをすべて 0 に設定して NOTIFICATION 構造体を初期化します。 NOTIFICATION 構造体を初期化するためのこの手法は、クライアントが、より小さく、高速で、エラーが発生しやすい OnNotify 実装を作成するのに役立ちます。

次の図は、シンク オブジェクト、アドバイズ ソース オブジェクト、MAPI の間の通信を示しています。 MAPI は、アドバイス ソースが通知サポートのために IMAPISupport メソッドを呼び出す場合にのみ関係します。

イベント通知呼び出し

MFCMAPI CAdviseSink クラス (AdviseSink.h ファイルとAdviseSink.cpp ファイルを使用) は、 アドバイズへのすべての呼び出しに対してアドバイズ シンク オブジェクトを実装します。 MFCMAPI の詳細については、「 MFCMAPI as a Code Sample and MFCMAPI」を参照してください。