イベント通知をサポートしています。Supporting Event Notification

適用されます: OutlookApplies to: Outlook

イベント通知をサポートできますが、複雑なために、MAPI には、プロセスの最も困難な部分を実装する 3 つのサポート オブジェクトのメソッドが用意されています。Because supporting event notification can be complicated, MAPI supplies three support object methods that implement the most difficult parts of the process. これらのメソッドは、ユニットとして動作し、3 つのすべてまたはどれも、プロバイダーを使用する必要があります。These methods work as a unit, and a provider must use all three or none of them.

MAPI サポートされている方法では、通知のキーを使用して、通知を生成するオブジェクトとアドバイズ シンクの接続を管理します。The MAPI support methods use notification keys to manage the connections between the advise sinks and the objects that generate the notifications. 通知キーは、プロセス間でオブジェクトを識別するバイナリ データを格納するNOTIFKEY構造です。A notification key is a NOTIFKEY structure that contains binary data that identifies an object across processes. 通知キーは通常、長期的なエントリのアドバイズ ソース オブジェクトの id からコピーされます。A notification key is typically copied from the long-term entry identifier of the advise source object. クライアントには、アドバイスの呼び出しのエントリ id が指定されている場合は、通知のキーを使用できます。If the client has supplied an entry identifier in the call to Advise, you can use it for the notification key. アドバイズする_lpEntryID_パラメーターが NULL の場合は、メッセージ ・ ストアなど、可能な最も外側のコンテナー オブジェクトのエントリ id を使用します。If the lpEntryID parameter to Advise is NULL, use the entry identifier of the outermost possible container object, such as the message store.

サポート メソッドを使用するには、クライアントが通知を登録するのには、メソッドを呼び出すたびに、 IMAPISupport::Subscribeを呼び出します。To use the support methods, call IMAPISupport::Subscribe whenever a client calls your Advise method to register for a notification. NOTIFKEY構造体を割り当てるし、アドバイスのソース オブジェクトの通知の一意なキーを作成します。Allocate a NOTIFKEY structure and create a unique notification key for your advise source object. などの特定のフォルダーにメッセージを受信したときにクライアントに通知するように要求するメッセージ ストア プロバイダーはそのフォルダーの通知キーを作成します。For example, a message store provider that is prompted to notify a client when a message is received into a particular folder creates a notification key for that folder. クライアントへのポインターとは、購読への呼び出しにNOTIFKEY構造体へのポインターを渡すには、シンクが案内します。Pass a pointer to the NOTIFKEY structure in the call to Subscribe along with a pointer to the client's advise sink. Subscribeメソッドを呼び出してアドバイズ シンクのIUnknown::AddRefその参照カウントをインクリメントし、MAPI では、登録をキャンセルするまで、ポインターが保持されます。Subscribe calls the advise sink's IUnknown::AddRef method to increment its reference count and MAPI retains the pointer until the registration is canceled.

渡すことができます NOTIFY_SYNC フラグ購読通知が動作することを要求する同期していない戻り値のIMAPIAdviseSink::OnNotifyメソッドへのすべての呼び出しを行ったことになるまで登録されているアドバイズ シンクします。You can pass the NOTIFY_SYNC flag to Subscribe to request that Notify behave synchronously and not return until it has made all calls to the IMAPIAdviseSink::OnNotify methods of registered advise sinks. 独自の内部の使用のためにのみ、このフラグを設定します。Set this flag only for your own internal use. クライアントのアドバイスの呼び出しに応答する場合は設定しません。Do not set it when you respond to a client Advise call. クライアントとプロバイダー間でのイベント通知は、常に非同期です。Event notification between clients and providers is always asynchronous. MAPI を保証する呼び出しを実行中にイベントが発生したOnNotify呼び出しのいずれかが行われる前にクライアントに戻ります。That is, MAPI guarantees that the call during which an event happens will return to the client before any of the OnNotify calls are made.

NOTIFY_SYNC フラグを設定する場合、アドバイズ シンク オブジェクトのいずれかに、変更しないでくださいし、購読するHrThisThreadAdviseSinkによって作成されたラッパーのアドバイズ シンクを渡さないでください。If you set the NOTIFY_SYNC flag, do not make any changes to any of the advise sink objects, and do not pass a wrapper advise sink created by HrThisThreadAdviseSink to Subscribe. HrThisThreadAdviseSinkは、スレッド セーフでないバージョンの非同期通知のみに使用するアドバイズ シンクを作成します。HrThisThreadAdviseSink creates a thread-safe version of an advise sink to be used with asynchronous notification only.

同期通知用に登録されているアドバイズ シンクは、CALLBACK_DISCONTINUE フラグを設定してOnNotifyから返された場合、 IMAPISupport::Notifyは NOTIFY_CANCELED フラグを設定し、 OnNotifyへの呼び出しを作成せずに返します。If an advise sink registered for synchronous notification returns from OnNotify with the CALLBACK_DISCONTINUE flag set, IMAPISupport::Notify sets the NOTIFY_CANCELED flag and returns without making any calls to OnNotify.

コピーを保持する必要がする必要がない購読が返されると、クライアントのシンクをアドバイスします。Once Subscribe has returned, you will no longer have any need to hold onto your copy of the client's advise sink. リ スを解放するメソッドを呼び出します。Call its IUnknown::Release method to release it. 購読をクライアントに返す必要がありますは 0 以外の接続数を返します。Subscribe returns a nonzero connection number that you should return to the client. 接続数は、ソース アドバイズとアドバイズ シンク間のリンクを表します。The connection number represents the link between the advise source and the advise sink. それまで有効のままクライアント正常な呼び出しを行います。It remains valid until the client makes a successful call to Unadvise.

クライアントの登録をキャンセルする準備ができたら、 Unadviseメソッドを呼び出します。When the client is ready to cancel a registration, it calls your Unadvise method. IMAPISupport::Unsubscribe Unadviseの呼び出しからの接続数を渡します。Pass the connection number from the Unadvise call to IMAPISupport::Unsubscribe. 購読の取り消しでは、アドバイズ シンクのリ スのメソッドを呼び出します。Unsubscribe calls the advise sink's IUnknown::Release method. アドバイズUnadvise購読および購読解除する呼び出しを組み合わせる必要があります。As with Advise and Unadvise, calls to Subscribe and Unsubscribe must be paired. 購読****購読に対して行ったすべての呼び出しに対して 1 回の呼び出しを行う必要があります。You must make one call to Unsubscribe for every call that is made to Subscribe. ただし、 Subscribeを呼び出して 、メソッドが呼び出されるたびにする必要はありません。However, you do not have to call Subscribe every time your Advise method is called. 逆に、内部通知を設定するために呼び出すことができます。Conversely, you can call it for setting up internal notifications.

イベントが発生してイベントの適切な型の 1 つまたは複数の通知構造体を割り当てるIMAPISupport::Notifyを呼び出します。When an event occurs, allocate one or more NOTIFICATION structures of the type appropriate for the event and call IMAPISupport::Notify. 通知は、各登録されているアドバイズ シンクに通知を生成します。Notify generates a notification for each registered advise sink. 未使用のすべてのメンバー、通知の構造体をゼロを設定する必要があります。You should set all the unused members of the NOTIFICATION structure to zero. 通知の構造体を初期化するためには、この手法は、クライアントが高速で、エラーが発生しやすいOnNotify実装のサイズを小さくすると、作成に役立ちます。This technique for initializing the NOTIFICATION structure can help clients create smaller, faster, and less error-prone OnNotify implementations.

個別通知の構造体が同じ型の複数のイベントであっても、イベントごとに必要なことに注意してください。Note that a separate NOTIFICATION structure is necessary for each event, even for multiple events of the same type. たとえば、3 つのクライアントが特定のテーブルにテーブルの通知用に登録されている 5 つの行がテーブルに追加される場合は、作成する必要が 5 つのOBJECT_NOTIFICATION構造体の通知呼び出しの。For example, if three clients are registered for table notification on a particular table and five rows are added to the table, you must create five OBJECT_NOTIFICATION structures for your Notify call. このバッチ通知は、通知5 回の呼び出しよりもパフォーマンスの向上になります。A batch notification such as this results in better performance than calling Notify five times. 通知の呼び出しには、MAPI は、すべての登録されているアドバイズ シンクのIMAPIAdviseSink::OnNotifyメソッドを呼び出します。For each Notify call, MAPI calls the IMAPIAdviseSink::OnNotify method of every registered advise sink. ある場合は no が登録されているアドバイズ シンクでは、MAPI の呼び出しは無視されます。If there are no registered advise sinks, MAPI ignores the call.

バッチ通知を送信するサービス プロバイダーで必要があります順序を最後の最初の通知から解釈できるようにします。Service providers that send batched notifications must order them so that they can be interpreted from the first notification to the last. 通知バッチには、一連の同じバッチ内の別のイベントに追加された前の行を参照する 1 つのイベントと TABLE_ROW_ADDED などのイベントが含まれている場合は、この順序付けすると特に必要があります。This ordering is especially necessary when a notification batch contains a series of events, such as TABLE_ROW_ADDED with one event that refers to a prior row that was added in another event in the same batch.

関連項目See also

MAPI サービス プロバイダーMAPI Service Providers