イベント通知のサポート
適用対象: Outlook 2013 | Outlook 2016
サポート イベント通知は複雑になる可能性があるため、MAPI では、プロセスの最も困難な部分を実装する 3 つのサポート オブジェクト メソッドが提供されます。 これらのメソッドはユニットとして機能し、プロバイダーは 3 つすべてを使用するか、いずれも使用しない必要があります。
MAPI サポート メソッドは、通知キーを使用して、通知シンクと通知を生成するオブジェクトとの間の接続を管理します。 通知キーは、プロセス間でオブジェクトを識別するバイナリ データを含む NOTIFKEY 構造体です。 通知キーは、通常、アドバイズ ソース オブジェクトの長期的なエントリ識別子からコピーされます。 クライアントが アドバイズの呼び出しでエントリ識別子を指定した場合は、通知キーに使用できます。 Advise の lpEntryID パラメーターが NULL の場合は、メッセージ ストアなど、最も外側のコンテナー オブジェクトのエントリ識別子を使用します。
サポート メソッドを使用するには、クライアントが Advise メソッドを呼び出して通知を登録するたびに、IMAPISupport::Subscribe を呼び出します。 NOTIFKEY 構造体を割り当て、アドバイズ ソース オブジェクトの一意の通知キーを作成します。 たとえば、メッセージが特定のフォルダーに受信されたときにクライアントに通知するように求めるメッセージ ストア プロバイダーは、そのフォルダーの通知キーを作成します。 Subscribe の呼び出しで NOTIFKEY 構造体へのポインターと、クライアントのアドバイズ シンクへのポインターを渡します。 サブスクライブ では、シンクの IUnknown::AddRef メソッドを呼び出して参照カウントをインクリメントし、MAPI は登録が取り消されるまでポインターを保持します。
登録されたアドバイズ シンクの IMAPIAdviseSink::OnNotify メソッドに対するすべての呼び出しが行われるまで、Notify が同期的に動作し、返されない要求に対して、NOTIFY_SYNC フラグを Subscribe に渡すことができます。 このフラグは、独自の内部使用に対してのみ設定します。 クライアント のアドバイズ 呼び出しに応答するときに設定しないでください。 クライアントとプロバイダー間のイベント通知は常に非同期です。 つまり、MAPI は、イベントが発生した呼び出しが 、OnNotify 呼び出しが行われる前にクライアントに返されることを保証します。
NOTIFY_SYNC フラグを設定した場合は、どのアドバイズ シンク オブジェクトにも変更を加えず、 HrThisThreadAdviseSink によって作成されたラッパー アドバイズ シンクを Subscribe に渡さないでください。 HrThisThreadAdviseSink は、非同期通知でのみ使用するアドバイズ シンクのスレッド セーフ バージョンを作成します。
同期通知用に登録されたアドバイズ シンクが、CALLBACK_DISCONTINUE フラグが設定された OnNotify から返された場合、 IMAPISupport::Notify は NOTIFY_CANCELED フラグを設定し、 OnNotify を呼び出さずにを返します。
Subscribe が返されると、クライアントのアドバイズ シンクのコピーを保持する必要がなくなります。 IUnknown::Release メソッドを呼び出して解放します。 Subscribe は、クライアントに返す必要がある 0 以外の接続番号を返します。 接続番号は、アドバイズ ソースとアドバイズ シンクの間のリンクを表します。 クライアントが Unadvise を正常に呼び出すまで有効なままになります。
クライアントが登録を取り消す準備ができたら、 Unadvise メソッドを呼び出します。 Unadvise 呼び出しの接続番号を IMAPISupport::Unsubscribe に渡します。 Unsubscribe は、アドバイズ シンクの IUnknown::Release メソッドを 呼び出します。 アドバイズと Unadvise と同様に、Subscribe と Unsubscribe の呼び出しをペアにする必要があります。 Subscribe に対して行われるすべての呼び出しに対して、 Unsubscribeに対して 1 回の呼び出しを行う必要があります。 ただし、Advise メソッドが呼び出されるたびに Subscribe を呼び出す必要はありません。 逆に、内部通知を設定するために呼び出すことができます。
イベントが発生したら、イベントに適した型の 1 つ以上の NOTIFICATION 構造体を割り当て、 IMAPISupport::Notify を呼び出します。 Notify は、登録されたアドバイズ シンクごとに通知を生成します。 NOTIFICATION 構造体の未使用のメンバーをすべて 0 に設定する必要があります。 NOTIFICATION 構造体を初期化するためのこの手法は、クライアントが、より小さく、高速で、エラーが発生しやすい OnNotify 実装を作成するのに役立ちます。
同じ種類の複数のイベントの場合でも、イベントごとに個別の NOTIFICATION 構造体が必要であることに注意してください。 たとえば、特定のテーブルのテーブル通知に 3 つのクライアントが登録され、5 つの行がテーブルに追加される場合は、Notify 呼び出しに 5 つのOBJECT_NOTIFICATION構造体を作成する必要があります。 このようなバッチ通知は、 Notify を 5 回呼び出すよりもパフォーマンスが向上します。 通知呼び出しごとに、MAPI は、登録されているすべてのアドバイズ シンクの IMAPIAdviseSink::OnNotify メソッドを呼び出します。 登録済みのアドバイズ シンクがない場合、MAPI は呼び出しを無視します。
バッチ通知を送信するサービス プロバイダーは、最初の通知から最後の通知まで解釈できるように、それらを注文する必要があります。 この順序付けは、通知バッチに一連のイベント (同じバッチ内の別のイベントで追加された前の行を参照する 1 つのイベントを含むTABLE_ROW_ADDEDなど) が含まれている場合に特に必要です。