IMAPIAdviseSink::OnNotify
適用対象: Outlook 2013 | Outlook 2016
1 つ以上のタスクを実行して通知に応答します。 実行されるタスクは、イベントの種類と通知を生成するオブジェクトによって異なります。
ULONG OnNotify(
ULONG cNotif,
LPNOTIFICATION lpNotifications
);
パラメーター
cNotif
[in]lpNotifications パラメーターによって指される NOTIFICATION 構造体の数。
lpNotifications
[in]発生したイベントに関する情報を提供する 1 つ以上の NOTIFICATION 構造体へのポインター。
戻り値
S_OK
通知が正常に処理されました。
注釈
通知プロセスは、クライアントまたは MAPI がサービス プロバイダーの Advise メソッドを呼び出して登録し、特定のオブジェクトの特定の種類の通知を受信すると開始されます。 Advise メソッドのパラメーターの 1 つは、IMAPIAdviseSink インターフェイスを実装するアドバイズ シンク オブジェクトへのポインターです。 登録された通知に対応するターゲット オブジェクトにイベントが発生すると、サービス プロバイダーは MAPI を介して直接または間接的に、アドバイズ シンクの OnNotify メソッドを呼び出します。
OnNotify への呼び出しは、イベントの原因となっている MAPI 呼び出し中または後で発生する可能性があります。 複数の実行スレッドをサポートするシステムでは、登録に使用されたのと同じスレッドで、または別のスレッドで OnNotify を呼び出すことができます。 クライアントは、OnNotify 呼び出しが、HrThisThreadAdviseSink 関数を使用してアドバイズに渡すアドバイズ シンクを作成することによって、アドバイズの呼び出しに使用されるのと同じスレッドで行われるようにすることができます。
lpNotifications パラメーターは、イベント中に何が変更されたかを記述する 1 つ以上の NOTIFICATION 構造体を指します。 イベントの種類ごとに異なる種類の NOTIFICATION 構造体があります。
次の表は、可能なイベントの種類と、各値に関連付けられている構造体を表すために使用される値の一覧です。
| 通知イベントの種類 | 対応する構造体 |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevNewMail |
NEWMAIL_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevSearchComplete |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
|
fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
|
fnevExtended |
EXTENDED_NOTIFICATION |
通知を設定および停止する方法の詳細については、IABLogon、IAddrBook、IMAPIForm、IMAPIForm、IMAPISession、IMAPITable、IMsgStore、IMSLogon のいずれかのインターフェイスのアドバイズ メソッドと Unadvise メソッドのリファレンス エントリを参照してください。
通知プロセスに関する一般的な情報については、「 MAPI でのイベント通知」を参照してください。
実装に関するメモ
OnNotify 実装は、通常、受信する通知の種類ごとに 1 つ以上のコード ブロックで構成されます。 これらのコード ブロック内で、通知への応答として必要と考えるタスクを実行します。 たとえば、ダイアログ ボックスの表示に含まれるフォルダーで fnevObjectModified 通知を受信するように登録するとします。 fnevObjectModified 通知を処理するために OnNotify メソッドに含めるコード ブロックで、更新された表示を要求する Windows メッセージをダイアログ ボックスに送信する場合があります。
OnNotify に渡される NOTIFICATION 構造体を変更したり解放したりしないでください。 構造体内のデータは、 OnNotify が返されるまで有効です。
呼び出し側への注意
複数のオブジェクトに変更が発生した場合は、 OnNotify の 1 回の呼び出しで、またはメモリ制約に応じて複数の呼び出しで、登録済みのアドバイズ シンクに通知できます。 これは、変更が 1 つのメソッド呼び出しの結果であるか、複数のメソッド呼び出しの結果であるかに関係なく当てはまります。 たとえば、 IMAPIFolder::CopyMessages の呼び出しは、複数のメッセージとフォルダーに影響を与える可能性があります。 メッセージ ストア プロバイダーとして、ターゲット フォルダーまたは多数の呼び出しに対して fnevObjectModified イベントの種類を指定して OnNotify を 1 回呼び出すことができます。各呼び出しに対して 1 つはメッセージに影響します。 同様に、クライアントが IMAPIFolder::CreateMessage を繰り返し呼び出す場合、これらの呼び出しをフォルダーの 1 つの fnevObjectModified イベントに結合するか、新しいメッセージごとに個々の fnevObjectCreated イベントに分けることができます。
通知を生成する方法とタイミングの詳細については、「 MAPI でのイベント通知 」および「 イベント通知のサポート」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| AdviseSink.h と AdviseSink.cpp |
CAdviseSink::OnNotifyDesc |
CAdviseSink クラスは、MFCMAPI 内のすべての通知を処理するために実装されます。 |