サポート オブジェクトの概要Support Object Overview

適用されます: OutlookApplies to: Outlook

MAPI をサポート オブジェクトを実装するオブジェクトを提供する、 IMAPISupport: IUnknownインタ フェースは、ログオン時にすべてのサービス プロバイダーとすべてのメッセージ サービスの構成中にします。MAPI furnishes a support object, an object that implements the IMAPISupport : IUnknown interface, for all service providers during logon and for all message services during configuration.

サポート オブジェクトは、クライアントによってアクセスできません。MAPI によって実装されており、サービス ・ プロバイダーによってのみ呼び出されます。Support objects are not accessible by clients; they are implemented by MAPI and called only by service providers. IMAPISupportインターフェイスは、Mapispi.h ヘッダー ファイルで指定します。The IMAPISupport interface is specified in the Mapispi.h header file. その識別子は IID_IMAPISup で、そのポインター型は LPMAPISUP です。Its identifier is IID_IMAPISup and its pointer type is LPMAPISUP. サポート オブジェクトによって MAPI プロパティが公開されることはありません。No MAPI properties are exposed by support objects.

プロバイダーは、プロバイダーのメッセージ サービスのエントリ関数が呼び出される回数または時間の MAPI ログオン プロバイダーの数に応じて、1 つ以上のサポート オブジェクトを得ることができます。A provider can be given one or more support objects, depending on the number of times MAPI logs the provider on or the number of times the provider's message service entry function is called. 通常、プロバイダーは、セッションごとに少なくとも 1 回記録されます。Typically, a provider will be logged on at least once per session. アドレス帳およびトランスポート プロバイダーは、クライアントがそれらを要求するプロファイル エントリを持つセッションを起動するたびにログオンします。Address book and transport providers are logged on every time a client starts a session with a profile entry that requests them. メッセージ ストア プロバイダーは、クライアントが、 IMAPISession::OpenMsgStoreメソッドを呼び出すたびにログオンします。Message store providers are logged on every time a client calls the IMAPISession::OpenMsgStore method.

場合は複数のログオン セッションでは、ことができますいずれかを保持し、サポートの各オブジェクトを個別に使用するを保持し、最初のものだけを使用して、各後続のサポート オブジェクトを破棄すること。In the case of multiple logons in a session, you can choose either to retain and use each support object separately or to retain and use only the first, discarding each subsequent support object. サポート オブジェクトを保持するには、 IUnknown::AddRefメソッドを呼び出します。To retain a support object, call its IUnknown::AddRef method. セッション全体で保持する必要があるサポート オブジェクトでAddRefを呼び出すことは、非常に重要です。呼び出しが行われない限り、MAPI はサポート オブジェクトを解放し、そのメモリを解放します。Calling AddRef on a support object that you want to retain throughout a session is extremely important; if the call is not made, MAPI releases the support object and frees its memory.

サポート オブジェクトの目的は、かなり多数のプロバイダーで一般的に使用するメソッドの実装を提供すること。The purpose of the support object is to provide implementations for a fairly large number of methods commonly used by the providers. サポートの各オブジェクトには、プロバイダーは、プロバイダーを使用しているプロファイル] セクションで実行中のセッションなどの独自のインスタンスとセッションのエラー情報を特定のコンテキストのデータも含まれています。Each support object also contains contextual data specific to its own instance, such as the session the provider is running in, the profile section the provider is using, and error information for the session.

サポート オブジェクトの 4 つの種類があります: 各 (アドレス帳、メッセージ ・ ストア、およびトランスポート) は、主なプロバイダーの種類と構成のサポートのいずれかのいずれかです。There are four different types of support objects: one for each major provider type (address book, message store, and transport) and one for configuration support.

MAPI は、その使用法に関連付けられているメソッドの実装を含めることによって、サポートの各オブジェクトをカスタマイズします。MAPI customizes each support object by including implementations of methods that are relevant for its usage. サポートのすべてのオブジェクトには、 IMAPISupport::OpenProfileSectionなどのいくつかのメソッドの実装が含まれます。Implementations of some methods, such as IMAPISupport::OpenProfileSection, are included in all support objects. IMAPISupport::SpoolerNotifyなどの他のメソッドの実装は、特定のサポートのオブジェクトにのみ適用されます。Implementations of other methods, such as IMAPISupport::SpoolerNotify, apply only to particular support objects. のみメッセージ ストアと、トランスポート プロバイダーは、このメソッドを使用できます。アドレス帳プロバイダーまたはメッセージ サービスを呼び出すことと、MAPI は、MAPI_E_NO_SUPPORT を返します。Only message store and transport providers can use this method; when an address book provider or a message service try to call it, MAPI returns MAPI_E_NO_SUPPORT.

サポート オブジェクトは、次のような多くのタスクを実行する使用できます。Support objects can be used to accomplish many tasks, such as the following:

ログオン時に、MAPI は、各サービス プロバイダーのプロバイダー オブジェクトのログオン メソッドを呼び出します。At logon time, MAPI calls the logon method of each service provider's provider object. アドレス帳プロバイダーでは、MAPI は、 IABProvider::Logonを呼び出します。For address book providers, MAPI calls IABProvider::Logon. メッセージ ストア プロバイダーでは、MAPI は、 IMSProvider::Logonを呼び出します。For message store providers, MAPI calls IMSProvider::Logon. トランスポート プロバイダーでは、MAPI は、 IXPProvider::TransportLogonを呼び出します。For transport providers, MAPI calls IXPProvider::TransportLogon. MAPI は、このメソッドのパラメーターのいずれかで適切なサポート オブジェクトへのポインターを渡します。MAPI passes a pointer to the appropriate support object in one of the parameters to this method. ログオン方法には、サポート オブジェクトへのポインターを渡すこと、ログオン オブジェクトがインスタンス化します。The logon method in turn instantiates a logon object, passing it the support object pointer. ログオン オブジェクトは、必要な場合に、その維持のサポート オブジェクトのIUnknown::AddRefメソッドを呼び出します。The logon object calls the support object's IUnknown::AddRef method to retain it, if necessary. サービス プロバイダーの詳細については、ログオン プロセスは、サービス プロバイダーの起動を参照してください。For more information about the logon process for service providers, see Starting a Service Provider.

クライアントがログオフすると、MAPI は、ログオン オブジェクトのログオフのメソッドを呼び出します。When a client logs off, MAPI calls the logon object's logoff method. ログオフ メソッドでは、プロバイダーがサポートされている方法のいずれかを呼び出すため不要になった意図を示すためにサポート オブジェクトのリ スのメソッドを呼び出します。The logoff method calls the support object's IUnknown::Release method to indicate that the provider no longer intends to call any of the support methods. 同様に、ログオンは、ログオフの方法は、わずかに異なる名前を持ちます。As with logon, the logoff methods have slightly different names. IABLogonおよびIMSLogonインタ フェースがあるログオフの方法です。IXPLogonインターフェイスには、 TransportLogoffメソッドがあります。The IABLogon and IMSLogon interfaces have Logoff methods; the IXPLogon interface has a TransportLogoff method.

メッセージ サービスのエントリ ポイント関数は、MAPI_E_UNCONFIGURED エラーが発生したか、クライアント構成要求を開始すると、ログオンの試行が失敗したときに呼び出されます。Message service entry point functions are called when a logon attempt fails with the error MAPI_E_UNCONFIGURED or when a client initiates a configuration request. MAPI では、構成のサポート オブジェクトをインスタンス化し、未構成のプロバイダーまたはプロバイダーの構成は変更するのいずれかのメッセージ サービスのエントリ ポイント関数を呼び出します。MAPI instantiates a configuration support object and calls the message service entry point function for either the unconfigured provider or the provider whose configuration is about to change. オブジェクトと異なり、その他のサポート、構成のサポート オブジェクトは、有効なエントリ ポイントの関数の戻り値までの間だけメッセージ サービスは、それらを保持するのには、これらのオブジェクトのAddRefメソッドを呼び出さないようにします。Unlike the other support objects, configuration support objects are valid only until the entry point function returns; message services do not call these objects' AddRef methods to retain them.

通常、MAPI プロバイダーのメッセージ サービスのエントリ ポイント関数を呼び出すは、呼び出しを行うプロバイダーが要求する場合があります。Typically, MAPI makes calls to a provider's message service entry point function, but sometimes a provider is asked to make the call. これは、クライアントが、構成のプロパティ シートを表示するのにはプロバイダーに確認する、プロバイダーのIMAPIStatus::SettingsDialogメソッドを呼び出すときに発生します。This can occur when a client calls a provider's IMAPIStatus::SettingsDialog method to prompt the provider to display its configuration property sheet. SettingsDialogは、メッセージ サービスのエントリ ポイント関数に渡すことができる、構成のサポート オブジェクトを取得するIMAPISupport::GetSvcConfigSupportObjを呼び出す必要があります。SettingsDialog should call IMAPISupport::GetSvcConfigSupportObj to obtain a configuration support object that it can pass to the message service entry point function.

IMAPISupport::GetMemAllocRoutinesメソッドは、MAPI を使用してリンクすることがなくメモリの割り当ておよび割り当て解除関数のアドレスを決定するために使用します。The IMAPISupport::GetMemAllocRoutines method is available for determining the addresses of the memory allocation and deallocation functions without having to link with MAPI. GetMemAllocRoutinesを使用しても簡単にコードのデバッグの割り当て関数の呼び出しを囲むと、メモリ リークを追跡します。Using GetMemAllocRoutines also makes it easier to trace memory leaks by surrounding the allocation function calls with debugging code. 呼び出す場合はGetMemAllocRoutinesを勧め、パラメーターとして割り当て関数のアドレスを必要とする、 CreateIProp関数を呼び出す前にするようにします。If you call GetMemAllocRoutines, as is recommended, do so before calling the CreateIProp function, which requires the allocation function addresses as parameters.

作成する必要がある場合、新しいアドレス帳やメッセージ ストア オブジェクトを作成した、 PR_SEARCH_KEY (PidTagSearchKey) のプロパティで、オブジェクトの検索キーを設定します。When you need to create a new address book or message store object, create and set a search key for the object in its PR_SEARCH_KEY (PidTagSearchKey) property. 検索キーの作成に使用する一意の識別子を取得するのにはIMAPISupport::NewUIDを呼び出します。Call IMAPISupport::NewUID to obtain a unique identifier to use in building a search key. 独自ハード コードされたMAPIUIDを使用しません。Do not use your own hard-coded MAPIUID. プロバイダーのMAPIUIDは、エントリの識別子にのみ使用してください。A provider's MAPIUID should be used only for entry identifiers. 検索キーを作成することに関する詳細については、 MAPI の記録と検索キーを参照してください。For more information about constructing search keys, see MAPI Record and Search Keys.

クライアント アプリケーションは、1 つまたは複数の関連オブジェクトのボタンを押したままオブジェクトを解放することができる場合があります。A client application can sometimes release an object without releasing one or more of its affiliated objects. このような場合、プロバイダーは、解放されていないオブジェクトが使用できなく必要があります。In such a case, a provider may need to render an unreleased object unusable. これを行うには、プロバイダーはすべてのオブジェクトに接続されているリソースを解放し、オブジェクトの vtable を無効にするIMAPISupport::MakeInvalidを呼び出して、します。To do this, the provider frees all of the resources connected with the object and then calls IMAPISupport::MakeInvalid to invalidate the object's vtable. MakeInvalidは、vtable のIUnknownのメソッド (QueryInterfaceAddRef、およびRelease) を標準的な MAPI 実装に置き換えます、MAPI_E_INVALID_OBJECT を取得する他のすべての方法は、します。MakeInvalid replaces the vtable's IUnknown methods (QueryInterface, AddRef, and Release) with standard MAPI implementations and causes all other methods to return MAPI_E_INVALID_OBJECT. MakeInvalidは、vtable 以外のすべてのオブジェクトのメモリも解放されます。MakeInvalid also frees all the object's memory other than the vtable.

関連項目See also

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