アドバイズ シンク オブジェクトの実装

適用対象: Outlook 2013 | Outlook 2016

クライアントは、独自のアドバイズ シンク オブジェクトを実装するか、ユーティリティ関数 HrAllocAdviseSink を使用できます。 HrAllocAdviseSink は、コールバック関数を呼び出す OnNotify の実装を持つアドバイズ シンク オブジェクトを作成します。

HrAllocAdviseSink を使用することには、長所と短所があります。 作業を保存できますが、作成するアドバイズ シンク オブジェクトをカウントする参照を制御することはできません。 そのため、アドバイズ シンクのリリースを慎重に制御する必要があるクライアント、またはアドバイズ シンクと別のクライアント オブジェクトの間に相互依存関係があるクライアントは、独自の IMAPIAdviseSink 実装を構築し、 HrAllocAdviseSink を完全に使用しないようにする必要があります。

独自のアドバイズ シンクを実装するクライアントは、参照カウントとオブジェクトの解放における潜在的な複雑さを排除するために、他のオブジェクトに関連しない、または他のオブジェクトに依存しない独立したオブジェクトにする必要があります。 ただし、アドバイズ シンクを別のオブジェクトの一部として実装する必要がある場合、または別のオブジェクトへのバック ポインターをデータ メンバーとして含める必要がある場合は、2 つの個別の参照カウントを維持することをお勧めします。1 つは、アドバイズ シンクによって参照されるオブジェクト用とアドバイズ シンク用です。

参照オブジェクトの参照カウントが 0 に低下すると、すべてのメソッドが失敗し、その vtable を破棄できますが、アドバイズ シンクのメモリは、参照カウントも 0 になるまでそのまま維持する必要があります。 つまり、アドバイズ シンクの Release メソッドは、参照カウントをデクリメントし、そのカウントが 0 に達したときにオブジェクトの破棄を完了する必要があります。 2 つの個別の参照カウントが維持されない場合、包含オブジェクトの Release プロセスの一部として、アドバイズ シンクを誤って破棄するのは簡単です。

HrAllocAdviseSink を使用してアドバイズ シンクを実装するクライアントは、コールバック関数を別のアドバイズ シンク オブジェクトのメソッドとして含めないように、同様に注意する必要があります。 C++ クライアントの場合は、これを行い、 この ポインターをパラメーターとして渡す必要があります。 通常、クライアントは参照カウントが 0 に達したときにオブジェクトを解放するため、これは危険な戦略です。 アドバイズ シンク オブジェクトのメモリを解放すると、 この ポインターは無効になります。

イベントの種類とアドバイス ソースに応じて、 OnNotify メソッドはさまざまな方法でイベントを処理できます。 次の表では、一部の標準イベントを処理する方法の提案を示します。

イベントの種類	OnNotify での処理
オブジェクトの移動	移動したオブジェクトの元の親が新しい親に関連している場合は、階層内で最も高いフォルダーまたはアドレス帳コンテナーで始まるビューを更新します。 2 つの親コンテナーが無関係な場合は、両方のビューを更新します。
新しいメッセージ	ユーザー インターフェイスを変更して、1 つ以上の新しいメッセージの到着をユーザーに通知します。 現在のビューに受信フォルダーを配置します。
Error	セッションを除くすべてのオブジェクトについて、必要に応じてエラーをログに記録し、 を返します。 セッション オブジェクトの場合は、可能であればログオフします。
検索の完了	処理は必要ありません。

注:

通知ハンドラーは再入可能である必要があります。