IMSLogon::Advise
適用対象: Outlook 2013 | Outlook 2016
メッセージ ストアの変更に関する通知のために、メッセージ ストア プロバイダーにオブジェクトを登録します。 メッセージ ストアは、登録されたオブジェクトへの変更に関する通知を送信します。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
パラメーター
cbEntryID
[in] lpEntryID パラメーターによって指されるエントリ識別子のサイズ (バイト単位)。
lpEntryID
[in]通知を生成するオブジェクトのエントリ識別子へのポインター。 このオブジェクトには、フォルダー、メッセージ、またはメッセージ ストア内の他のオブジェクトを指定できます。 または、MAPI で cbEntryID パラメーターを 0 に設定し、lpEntryID に null を渡す場合、アドバイズ シンクはメッセージ ストア全体の変更に関する通知を提供します。
ulEventMask
[in]MAPI が通知を生成するオブジェクトに対して発生する通知イベントの種類のイベント マスク。 マスクは特定のケースをフィルター処理します。 各イベントの種類には、イベントに関する追加情報を含む構造体が関連付けられています。 次の表に、使用可能なイベントの種類と、対応する構造体を示します。
| 通知イベントの種類 | 対応する構造体 |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevNewMail |
NEWMAIL_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
| fnevSearchComplete |
OBJECT_NOTIFICATION |
| fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[in]通知が要求されたセッション オブジェクトに対してイベントが発生したときに呼び出されるシンク オブジェクトへのポインター。 これはシンク オブジェクトが既に存在している必要があります。
lpulConnection
[out]正常に戻ると通知登録の接続番号を保持する変数へのポインター。 接続番号は 0 以外である必要があります。
戻り値
S_OK
�ʘb���������A�\�������l�܂��͒l���Ԃ���܂��B
MAPI_E_NO_SUPPORT
この操作は、MAPI または 1 つ以上のサービス プロバイダーによってサポートされていません。
注釈
メッセージ ストア プロバイダーは、 IMSLogon::Advise メソッドを実装して、通知コールバックのオブジェクトを登録します。 指定されたオブジェクトに変更が発生するたびに、プロバイダーは ulEventMask パラメーターで設定されたイベント マスク ビットを確認し、そのため、どのような種類の変更が発生したかを確認します。 ビットが設定されている場合、プロバイダーは IMAPIAdviseSink::OnNotify メソッドを呼び出して、 lpAdviseSink パラメーターによって示されるアドバイズ シンク オブジェクトに対してイベントを報告します。 通知構造体で OnNotify ルーチンに渡されるデータは、イベントを記述します。
OnNotify の呼び出しは、オブジェクトを変更する呼び出し中、または後で発生する可能性があります。 複数の実行スレッドをサポートするシステムでは、 OnNotify の呼び出しはどのスレッドでも実行できます。 不都合なタイミングで発生する可能性がある OnNotify の呼び出しを安全に処理するには、クライアント アプリケーションで HrThisThreadAdviseSink 関数を使用する必要があります。
通知を提供するには、 アドバイス を実装するメッセージ ストア プロバイダーは 、lpAdviseSink アドバイズ シンク オブジェクトへのポインターのコピーを保持する必要があります。これを行うには、プロバイダーは IUnknown::AddRef メソッドを呼び出して、通知登録が IMSLogon::Unadvise メソッドの呼び出しで取り消されるまでオブジェクト ポインターを維持するようにシンクにアドバイスします。 Advise 実装では、通知登録に接続番号を割り当て、この接続番号に対して AddRef を呼び出してから lpulConnection パラメーターに返す必要があります。 サービス プロバイダーは、登録が取り消される前にアドバイズ シンク オブジェクトを解放できますが、 Unadvise が呼び出されるまで接続番号を解放しないでください。
アドバイズへの呼び出しが成功した後、Unadvise が呼び出される前に、プロバイダーはアドバイズ シンク オブジェクトが解放されるように準備する必要があります。 そのため、プロバイダーは、特定の長期的な使用がない限り、アドバイズが返された後に アドバイズ シンク オブジェクトを解放する必要があります。
通知プロセスの詳細については、「 MAPI でのイベント通知」を参照してください。