MAPI でのイベントの通知Event notification in MAPI

適用されます: OutlookApplies to: Outlook

イベント通知は、2 つの MAPI オブジェクト間で情報の通信です。Event notification is the communication of information between two MAPI objects. を通じて、オブジェクトのいずれか、クライアントまたはサービス プロバイダーを変更または他のオブジェクトで発生する可能性があります、イベントと呼ばれる、エラーの通知を登録します。Through one of the objects, a client or service provider registers for notification of a change or error, called an event, which may take place in the other object. イベントが発生すると、最初のオブジェクトが変更またはエラーの通知されます。After the event occurs, the first object is notified of the change or error. アドバイズ シンクに通知を受信するオブジェクトと呼びます通知用に使用するオブジェクトは、アドバイズ ソースと呼ばれます。The object receiving the notification is called the advise sink; the object responsible for the notification is called the advise source.

3 種類ありますのアドバイズ シンク オブジェクト (すべての種類の標準的な MAPI オブジェクト)。There are three types of advise sink objects (all types are standard MAPI objects):

  • シンク オブジェクトに通知します。Advise sink objects.
  • フォームでは、シンク オブジェクトを案内します。Form advise sink objects.
  • ビューでは、シンク オブジェクトを案内します。View advise sink objects.

シンク オブジェクトは、最も一般的な種類を案内します。Advise sink objects are the most common type. 通常、シンクは、アドレス帳とメッセージ ストアの通知およびサポートを受信するクライアント アプリケーションで実装をアドバイス、 IMAPIAdviseSink: IUnknownインタ フェースです。Advise sinks are typically implemented by client applications to receive address book and message store notifications and support the IMAPIAdviseSink : IUnknown interface. IMAPIAdviseSinkには、 IMAPIAdviseSink::OnNotify、1 つのメソッドが含まれています。IMAPIAdviseSink contains a single method, IMAPIAdviseSink::OnNotify. フォームとビューの通知シンクは、あまり一般的です。ユーザー設定フォームへの変更に関する通知を受信することが実装されています。Form and view advise sinks are less common; they are implemented to receive notifications about changes to custom forms. フォームのアドバイズ シンクのサポート、 IMAPIFormAdviseSink: IUnknownインタ フェースとビューの通知シンク サポート、 IMAPIViewAdviseSink: IUnknownインタ フェースです。Form advise sinks support the IMAPIFormAdviseSink : IUnknown interface and view advise sinks support the IMAPIViewAdviseSink : IUnknown interface. クライアント実装のほとんどの標準では、シンク オブジェクトをアドバイス、ためには、通知のディスカッションがフォームの通知ではなく、アドレス帳とメッセージ ストアの通知に関連するいると仮定します。Because most clients implement standard advise sink objects, assume that discussions of notifications relate to address book and message store notifications rather than forms notifications. フォームの通知の詳細については、 MAPI フォームの通知およびフォームのサーバー コードの記述を参照してください。For more information about forms notifications, see MAPI Forms Notifications and Writing Form Server Code.

ソースのサービス ・ プロバイダー、および MAPI オブジェクトの実装を推奨します。Advise source objects are implemented by service providers and by MAPI. イベントの通知をサポートしていないすべてのサービス プロバイダーオプションですが、強くお勧めします。Not all service providers support event notification; it is optional, but strongly recommended. メッセージ ストアとアドレス帳プロバイダー通常サポート オブジェクトの通知のそれぞれのオブジェクトとテーブルの通知の内容および階層テーブルにいくつかの。Message store and address book providers usually support object notifications on several of their objects and table notifications on their contents and hierarchy tables. トランスポート プロバイダーは通知をサポートします。他の方法でクライアントとの通信に依存しています。Transport providers do not support notifications directly; they rely on alternative methods of communication with clients.

アドバイズ シンクとは異なり、ソース オブジェクトは、MAPI オブジェクトの一意の型ではありませんを案内します。Unlike advise sinks, advise source objects are not a unique type of MAPI object. メッセージ ストアやテーブルなど、多くの MAPI オブジェクトは、ソースのアドバイズの役割に対して実行できます。Many MAPI objects, such as message stores and tables, can take on the role of advise source. アドバイズ ソースの MAPI する任意のオブジェクトは、次のとおりです。An advise source is any MAPI object that does the following:

  • 登録の通知を受信するアドバイズメソッドを実装します。Implements an Advise method to receive notification registrations.

  • キャンセルの通知を受信するのにはUnadviseメソッドを実装します。Implements an Unadvise method to receive notification cancellations.

  • IMAPIAdviseSink::OnNotifyメソッドを呼び出すことによって登録されている適切なアドバイズ シンク オブジェクトに適切な種類の通知を生成します。Generates notifications of the appropriate type to the appropriate advise sink objects that have registered by calling their IMAPIAdviseSink::OnNotify methods.

実装するクライアントの通知をキャンセルするときに登録する必要がありますが実行される、オブジェクトとUnadviseのエントリの識別子を渡すことのほとんどの場合、通知を登録するときに、シンク オブジェクトがアドバイズを呼び出す、登録します。Clients that implement advise sink objects call Advise when they want to register for a notification, in most cases passing in the entry identifier of the object with which registration should occur, and Unadvise when they want to cancel the registration. クライアントでは、アドバイズを監視するイベントのいくつかの種類を示すにパラメーターを渡します。Clients pass a parameter to Advise that indicates which of the several types of events they want to monitor. アドバイズは、ソースのアドバイズとアドバイズ シンク間の接続が成功を表す数値を 0 以外の値を返します。Advise returns a nonzero number that represents a successful connection between the advise sink and advise source.

メッセージ ストア プロバイダーがメッセージ ストアのPR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) で、STORE_NOTIFY_OK フラグが設定されている確認することによって通知をサポートしているかどうか、アドバイズを呼び出す前にクライアントを決定できます。プロパティです。Before calling Advise, clients can determine whether a message store provider supports notification by checking that the STORE_NOTIFY_OK flag is set in the message store's PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property. アドレス帳プロバイダーが通知をサポートしているかどうかというクライアントが事前に決定することがあります。There is no way for clients to determine ahead of time whether or not an address book provider supports notifications. クライアントを登録しようとする必要があり、試行が失敗した場合、それらと見なすことが通知はサポートされていません。Clients must attempt to register and if the attempt fails, they can assume notifications are unsupported.

クライアントが登録されているイベントが発生するとアドバイスのソース イベントに関する情報を含む通知データ構造を持つ場合は、そのIMAPIAdviseSink::OnNotifyメソッドを呼び出して、アドバイズ シンクに通知します。When an event for which a client has registered occurs, the advise source notifies the advise sink by calling its IMAPIAdviseSink::OnNotify method with a notification data structure that contains information about the event. OnNotifyのアドバイズ シンクの実装では、メモリ内のデータを更新し、画面表示を更新するなど、通知への応答としてタスクを実行できます。An advise sink's implementation of OnNotify can perform tasks in response to the notification, such as updating data in memory or refreshing a screen display.

サービス ・ プロバイダーは通知のサポートを手動で実装したり、 IMAPISupportの 3 つの方法で提供されているヘルプの利用: IMAPISupport::SubscribeIMAPISupport::Unsubscribe、およびIMAPISupport::Notify.Service providers can implement support for notifications manually or take advantage of the help provided in three IMAPISupport methods: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. 購読および購読解除の方法は、通知の登録を処理し、プロバイダーの登録解除通知メソッドは、該当する場合の通知の送信を処理します。The Subscribe and Unsubscribe methods handle notification registration and deregistration for providers; the Notify method handles sending notifications when appropriate.

通知の登録のサポート オブジェクトのメソッドを使用するには、サービス プロバイダーは、アドバイズメソッドでIMAPISupport::Subscribeを呼び出すし、購読するクライアントがアドバイズを通過するアドバイズ シンク ポインターを渡します。To use the support object methods for notification registration, service providers call IMAPISupport::Subscribe in their Advise methods and pass to Subscribe the advise sink pointer that clients pass to Advise. エントリ識別子が渡された場合、アドバイスのソースを指定する入力パラメーターとして、サービス ・ プロバイダーに変換するバイナリのキー。If an entry identifier is passed as an input parameter to specify an advise source, service providers convert it to a binary key. 購読は、一意の接続数を作成しはこのサービス プロバイダーをクライアントに返す値です。Subscribe creates a unique connection number and it is this number that service providers return to clients. サービス プロバイダーは、クライアントのリリースできますアドバイスの呼び出しが完了した後は、いつでもシンク オブジェクトのポインターを案内します。Service providers can release the client's advise sink object pointer at any time after the Advise call has completed.

クライアントは、サービス プロバイダーの登録をキャンセルするのにはUnadviseのクライアントの参照カウント、デクリメントを呼び出すときに、シンク ポインターを勧めるか、同じように購読中止を呼び出します。When clients call Unadvise to cancel a registration, service providers either decrement the reference count on the client's advise sink pointer or call Unsubscribe to do the same.

通知を生成する時間は、サービス プロバイダーは、通知に関連し、すべての使用されていないメンバーを 0 に設定して、通知の構造体を初期化する内部処理を実行します。When it is time to generate a notification, service providers perform any internal processing that relates to the notification and initializes a NOTIFICATION structure by setting all of its unused members to zero. 通知の構造体を初期化するためには、この手法は、クライアントが高速で、エラーが発生しやすいOnNotify実装のサイズを小さくすると、作成に役立ちます。This technique for initializing the NOTIFICATION structure can help clients create smaller, faster, and less error-prone OnNotify implementations.

通知シンク オブジェクトを次の図がの間の通信には、ソース オブジェクト、および MAPI に案内します。The following illustration shows the communication between advise sink objects, advise source objects, and MAPI. MAPI が関係しているは、アドバイスのソースでは、 IMAPISupportメソッドを呼び出して通知をサポートするためにのみです。MAPI is involved only when the advise source calls the IMAPISupport methods for notification support.

イベント通知の呼び出しEvent notification calls

イベント通知の呼び出しEvent notification calls

(AdviseSink.h および AdviseSink.cpp ファイルを使用して) MFCMAPI CAdviseSinkクラスでは、アドバイズするすべての呼び出しに対してアドバイズ シンク オブジェクトを実装します。The MFCMAPI CAdviseSink class (using the AdviseSink.h and AdviseSink.cpp files) implements the advise sink object for all calls to Advise. MFCMAPI の詳細については、コード サンプルとして MFCMAPIMFCMAPIを参照してください。For more information about MFCMAPI, see MFCMAPI as a Code Sample and MFCMAPI.