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