IMAPISession::Advise
適用対象: Outlook 2013 | Outlook 2016
セッションに影響を与える指定したイベントの通知を受信するように登録します。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
パラメーター
cbEntryID
[in] lpEntryID パラメーターによって指されるエントリ識別子のバイト数。
lpEntryID
[in]通知を生成する必要があるアドレス帳またはメッセージ ストア オブジェクトのエントリ識別子へのポインター、またはクライアントがセッションのみに影響を与えるイベントに関する通知を受信するために登録していることを示す NULL。
ulEventMask
[in]クライアントが関心を持ち、登録に含める必要がある通知イベントの種類を示す値のマスク。 lpEntryID が NULL の場合、MAPI は、セッションのみに影響する重大なエラー イベントに対してクライアントを自動的に登録します。 lpEntryID がエントリ識別子を指している場合、ulEventMask パラメーターに対して次の値が有効です。
fnevCriticalError
メモリ不足などの重大なエラーに関する通知を登録します。
fnevExtended
特定のアドレス帳またはメッセージ ストア プロバイダーに固有のイベントに関する通知とセッションのシャットダウンに関する通知を登録します。
fnevNewMail
新しいメッセージの到着に関する通知を登録します。
fnevObjectCreated
新しいオブジェクトの作成に関する通知を登録します。
fnevObjectCopied
コピーされるオブジェクトに関する通知を登録します。
fnevObjectDeleted
削除されるオブジェクトに関する通知を登録します。
fnevObjectModified
変更中のオブジェクトに関する通知を登録します。
fnevObjectMoved
移動中のオブジェクトに関する通知を登録します。
fnevSearchComplete
検索操作の完了に関する通知を登録します。
lpAdviseSink
[in]後続の通知を受け取るシンク オブジェクトへのポインター。 このアドバイスシンク オブジェクトは既に割り当てられている必要があります。
lpulConnection
[out]呼び出し元のアドバイズ シンク オブジェクトとセッションの間の接続を表す 0 以外の数値へのポインター。
戻り値
S_OK
登録が成功しました。
MAPI_E_INVALID_ENTRYID
lpEntryID が指すエントリ識別子は、有効なエントリ識別子を表しません。
MAPI_E_NO_SUPPORT
lpEntryID が指すエントリ識別子を担当するサービス プロバイダーは、ulEventMask パラメーターで指定されたイベントの種類をサポートしていないか、通知をサポートしていません。
MAPI_E_UNKNOWN_ENTRYID
lpEntryID によって指されるエントリ識別子は、プロファイル内のどのサービス プロバイダーでも処理できません。
注釈
IMAPISession::Advise メソッドは、呼び出し元のアドバイズ シンク オブジェクト、セッション、および必要に応じてサービス プロバイダー間の接続を確立します。 この接続は、 ulEventMask パラメーターで指定された 1 つ以上のイベントが lpEntryID が指すオブジェクトに対して発生した場合に、アドバイズ シンクに通知を送信するために使用されます。 lpEntryID が NULL の場合、ターゲット オブジェクトはセッションであり、重要なエラーと拡張イベントに対してのみ通知が送信されます。
lpEntryID が有効なエントリ識別子を指している場合、MAPI は責任あるサービス プロバイダーに属するログオン オブジェクトの Advise メソッドを呼び出します。 たとえば、 lpEntryID が配布リストのエントリ識別子を指している場合、MAPI は適切なアドレス帳プロバイダーの IABLogon::Advise メソッドを呼び出します。
通知を送信するには、サービス プロバイダーまたは MAPI が、登録済みのアドバイズ シンクの IMAPIAdviseSink::OnNotify メソッドを呼び出します。 通知構造である OnNotify のパラメーターの 1 つに、特定のイベントを記述する情報が含まれています。
呼び出し側への注意
複数の実行スレッドをサポートするシステムでは、 OnNotify の呼び出しはいつでも任意のスレッドで実行できます。 通知が特定のスレッドの特定の時刻にのみ発生することを保証する必要がある場合は、 HrThisThreadAdviseSink 関数を呼び出して 、Advise メソッドに渡すアドバイズ シンク オブジェクトを生成します。
クライアントがログオフしたタイミングを判断するには、lpEntryID を NULL に設定し、cbEntryID を 0 に設定して Advise を呼び出して、サービス プロバイダーに通知を登録します。 ログオフが発生すると、fnevExtended 通知が表示されます。
アドバイスの呼び出しが成功した後、IMAPISession::Unadvise が呼び出されて登録を取り消す前に、特定の長期的な使用がない限り、アドバイズ シンク オブジェクトを解放します。
通知プロセスの概要については、「 MAPI でのイベント通知」を参照してください。
通知の処理の詳細については、「通知の 処理」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI では、 IMAPISession::Advise メソッドを使用して、セッションに対する通知を登録します。 |