IAddrBook::Advise
適用対象: Outlook 2013 | Outlook 2016
アドレス帳内の 1 つ以上のエントリに対する変更に関する通知を受け取るために、クライアントまたはサービス プロバイダーを登録します。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
パラメーター
cbEntryID
[in] lpEntryID パラメーターによって指されるエントリ識別子のバイト数。
lpEntryID
[in] ulEventMask パラメーターで説明されている型または型の変更が発生したときに通知を生成するアドレス帳コンテナー、メッセージング ユーザー、または配布リストのエントリ識別子へのポインター。
ulEventMask
[in]呼び出し元が受信に登録している 1 つ以上の通知イベント。 各イベントは、発生した変更に関する情報を含む特定の通知構造に関連付けられます。 次の表に、 ulEventMask とその対応する構造体の有効な値を示します。
| 通知イベント | 対応する構造体 |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in]通知が要求されたイベントが発生したときに呼び出されるシンク オブジェクトへのポインター。
lpulConnection
[out]通知登録を表す 0 以外の接続番号へのポインター。
戻り値
S_OK
通知の登録が成功しました。
MAPI_E_INVALID_ENTRYID
lpEntryID で渡されたエントリ識別子を担当するアドレス帳プロバイダーは、対応するエントリの通知を登録できませんでした。
MAPI_E_NO_SUPPORT
通知は、 lpEntryID パラメーターで渡されたエントリ識別子によって識別されるオブジェクトを担当するアドレス帳プロバイダーではサポートされていません。
MAPI_E_UNKNOWN_ENTRYID
lpEntryID で渡されたエントリ識別子は、プロファイル内のどのアドレス帳プロバイダーでも処理できません。
注釈
クライアントとサービス プロバイダーは 、 Advise メソッドを呼び出して、アドレス帳エントリに特定の種類または種類の通知を登録します。 通知の種類は、 ulEventMask パラメーターで渡されたイベント マスクによって示されます。
MAPI は、lpEntryID パラメーターのエントリ識別子によって示されるように、エントリを担当するアドレス帳プロバイダーにこのアドバイズ呼び出しを転送します。 アドレス帳プロバイダーは、登録自体を処理するか、サポート メソッド IMAPISupport::Subscribe を呼び出して、MAPI に呼び出し元の登録を求めます。 正常な登録を表す 0 以外の接続番号が返されます。
通知登録によって示される型のエントリに変更が発生するたびに、アドレス帳プロバイダーは、lpAdviseSink パラメーターで指定されたアドバイズ シンク オブジェクトに対して IMAPIAdviseSink::OnNotify メソッドを呼び出します。 OnNotify メソッドには、イベントを記述するデータを含む入力パラメーターとして NOTIFICATION 構造体が含まれています。
アドレス帳プロバイダーに応じて、 OnNotify の呼び出しは、登録されたオブジェクトに対する変更の直後または後で行うことができます。 複数の実行スレッドをサポートするシステムでは、 OnNotify の呼び出しはどのスレッドでも実行できます。 クライアントは、 HrThisThreadAdviseSink 関数を呼び出して、 アドバイズに渡されるアドバイズ シンク オブジェクトを作成することで、これらの通知が特定のスレッドで発生することを要求できます。
アドレス帳プロバイダーは、 アドバイズ 呼び出しが正常に完了した後、および IAddrBook::Unadvise 呼び出しの前にクライアントによって渡されたアドバイズ シンク オブジェクトを解放して通知を取り消すことができるため、 クライアントは、アドバイズ が戻ったときにアドバイズ シンク オブジェクトを解放する必要があります。
通知プロセスの詳細については、「 MAPI でのイベント通知」を参照してください。