IABLogon::Advise

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

コンテナー、メッセージング ユーザー、または配布リストに影響を与える指定されたイベントの通知を受信するように呼び出し元を登録します。

HRESULT Advise(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulEventMask,
  LPMAPIADVISESINK lpAdviseSink,
  ULONG FAR * lpulConnection
);

パラメーター

cbEntryID

[in] lpEntryID パラメーターによって指されるエントリ識別子のバイト数。

lpEntryID

[in]通知を生成するオブジェクトのエントリ識別子へのポインター。

ulEventMask

[in]呼び出し元が関心を持ち、登録に含める必要がある通知イベントの種類を示す値のビットマスク。 イベントに関する情報を保持するイベントの種類ごとに、対応する NOTIFICATION 構造体が関連付けられています。 次の表に、 ulEventMask パラメーターの有効な値と、各値に関連付けられている構造体を示します。

通知イベントの種類 対応する NOTIFICATION 構造体
fnevCriticalError
ERROR_NOTIFICATION
fnevObjectCreated
OBJECT_NOTIFICATION
fnevObjectDeleted
OBJECT_NOTIFICATION
fnevObjectModified
OBJECT_NOTIFICATION
fnevObjectCopied
OBJECT_NOTIFICATION
fnevObjectMoved
OBJECT_NOTIFICATION

lpAdviseSink

[in]後続の通知を受け取るシンク オブジェクトへのポインター。

lpulConnection

[out]通知登録を表す 0 以外の値へのポインター。

戻り値

S_OK

通知の登録が成功しました。

MAPI_E_INVALID_ENTRYID

lpEntryID パラメーターで渡されるエントリ識別子が適切な形式ではありません。

MAPI_E_NO_SUPPORT

アドレス帳プロバイダーは通知をサポートしていません。おそらく、そのオブジェクトに対する変更が許可されていないためです。

MAPI_E_UNKNOWN_ENTRYID

アドレス帳プロバイダーは、 lpEntryID で渡されたエントリ識別子を処理できません。

注釈

アドレス帳プロバイダーは 、IABLogon::Advise メソッドを実装して、コンテナー内のオブジェクトに変更が発生したときに通知されるように呼び出し元を登録します。 呼び出し元は、メッセージング ユーザー、配布リスト、またはコンテナー全体に関する通知を登録できます。

クライアントは通常 、IAddrBook::Advise メソッドを呼び出してアドレス帳の通知を登録します。 MAPI は、lpEntryID のエントリ識別子によって表されるオブジェクトを担当するアドレス帳プロバイダーの Advise メソッドを呼び出します。

ulEventMask で表される型の指定されたオブジェクトに変更が発生すると、lpAdviseSink が指すアドバイズ シンクの OnNotify メソッドへの呼び出しが行われます。 NOTIFICATION 構造体で OnNotify ルーチンに渡されるデータは、イベントを記述します。

実装に関するメモ

MAPI のヘルプの有無にかかわらず、通知をサポートできます。 MAPI には、サービス プロバイダーが通知を実装するのに役立つ 3 つのサポート オブジェクト メソッドがあります。

MAPI サポート メソッドを使用する場合は、Advise メソッドが呼び出されたときに Subscribe を呼び出し、lpAdviseSink ポインターを解放します。

通知を自分でサポートする場合は、lpAdviseSink パラメーターで表されるアドバイズ シンクの AddRef メソッドを呼び出して、このポインターのコピーを保持します。 登録を取り消すために IABLogon::Unadvise メソッドが呼び出されるまで、このコピーを維持します。

通知をサポートする方法に関係なく、0 以外の接続番号を通知登録に割り当て、 lpulConnection パラメーターで返します。 Unadvise メソッドが呼び出されるまで、この接続番号を解放しないでください。

呼び出し側への注意

アドバイズ シンク ポインターは、 lpAdviseSink パラメーターを アドバイズ に渡すと、作成したオブジェクト、または MAPI が HrThisThreadAdviseSink 関数を使用して作成したオブジェクトを指すことができます。 複数の実行スレッドをサポートし、後続の OnNotify メソッドの呼び出しが適切なスレッドで適切なタイミングで実行されるようにする場合は、HrThisThreadAdviseSink を使用することをお勧めします。

アドバイズへの呼び出しの後、Unadvise への呼び出しの前に、いつでもアドバイズ シンク オブジェクトが解放されるように準備してください。 そのため、特定の長期的な使用がない限り、 アドバイズ シンク オブジェクトは、アドバイズ が返された後に解放する必要があります。

通知プロセスの詳細については、「 MAPI でのイベント通知」を参照してください。 IMAPISupport メソッドを使用して通知をサポートする方法については、「イベント通知のサポート」を参照してください。 マルチスレッドと MAPI の詳細については、「MAPI でのスレッド処理」を参照してください。

関連項目

HrThisThreadAdviseSink

IABLogon::Unadvise

IMAPIAdviseSink::OnNotify

�ʒm

IABLogon : IUnknown