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

適用対象: Outlook 2013 | Outlook 2016

MAPI は、 IMAPISupport : IUnknown インターフェイスを実装するオブジェクトであるサポート オブジェクトを、ログオン時のすべてのサービス プロバイダーと構成中のすべてのメッセージ サービスに提供します。

サポート オブジェクトにはクライアントがアクセスできません。MAPI によって実装され、サービス プロバイダーによってのみ呼び出されます。 IMAPISupport インターフェイスは、Mapispi.h ヘッダー ファイルで指定します。 その識別子はIID_IMAPISup、ポインターの種類は LPMAPISUP です。 MAPI プロパティはサポート オブジェクトによって公開されません。

プロバイダーには、MAPI がプロバイダーをログに記録する回数、またはプロバイダーのメッセージ サービス エントリ関数が呼び出された回数に応じて、1 つ以上のサポート オブジェクトを指定できます。 通常、プロバイダーはセッションごとに少なくとも 1 回ログオンします。 アドレス帳とトランスポート プロバイダーは、クライアントが要求するプロファイル エントリを使用してセッションを開始するたびにログオンします。 メッセージ ストア プロバイダーは、クライアントが IMAPISession::OpenMsgStore メソッドを呼び出すたびにログオンします。

セッションで複数のログオンが発生する場合は、各サポート オブジェクトを個別に保持して使用するか、最初のサポート オブジェクトのみを保持して使用するかを選択できます。後続の各サポート オブジェクトは破棄されます。 サポート オブジェクトを保持するには、 その IUnknown::AddRef メソッドを 呼び出します。 セッション全体で保持するサポート オブジェクトに対して AddRef を呼び出すことは非常に重要です。呼び出しが行われなければ、MAPI はサポート オブジェクトを解放し、そのメモリを解放します。

サポート オブジェクトの目的は、プロバイダーによって一般的に使用されるかなり多くのメソッドの実装を提供することです。 各サポート オブジェクトには、プロバイダーが実行されているセッション、プロバイダーが使用しているプロファイル セクション、セッションのエラー情報など、独自のインスタンスに固有のコンテキスト データも含まれています。

サポート オブジェクトには、メジャー プロバイダーの種類 (アドレス帳、メッセージ ストア、トランスポート) ごとに 1 つ、構成サポート用の 4 種類があります。

MAPI は、その使用方法に関連するメソッドの実装を含めることによって、各サポート オブジェクトをカスタマイズします。 IMAPISupport::OpenProfileSection などの一部のメソッドの実装は、すべてのサポート オブジェクトに含まれています。 IMAPISupport::SpoolerNotify などの他のメソッドの実装は、特定のサポート オブジェクトにのみ適用されます。 このメソッドを使用できるのは、メッセージ ストアとトランスポート プロバイダーだけです。アドレス帳プロバイダーまたはメッセージ サービスが呼び出そうとすると、MAPI はMAPI_E_NO_SUPPORTを返します。

サポート オブジェクトは、次のような多くのタスクを実行するために使用できます。

  • プロファイル セクションへのアクセス。

  • フォルダーまたはメッセージのコピー。 詳細については、「 メッセージまたはフォルダーのコピーまたは移動」を参照してください。

  • 他のプロバイダーに属するオブジェクトへのアクセス。 詳細については、「 オブジェクト のアクセスと比較のサポート」を参照してください。

  • イベント通知の処理。 詳細については、「 イベント通知のサポート」を参照してください。

  • メモリの割り当てと解放。

  • 一意識別子の取得。

  • オブジェクトを無効にします。

  • エラーの処理。

  • メッセージ プリプロセッサの登録。

  • メッセージ配信レポートの準備。

ログオン時に、MAPI は各サービス プロバイダーのプロバイダー オブジェクトのログオン メソッドを呼び出します。 アドレス帳プロバイダーの場合、MAPI は IABProvider::Logon を呼び出します。 メッセージ ストア プロバイダーの場合、MAPI は IMSProvider::Logon を呼び出します。 トランスポート プロバイダーの場合、MAPI は IXPProvider::TransportLogon を呼び出します。 MAPI は、パラメーターの 1 つで適切なサポート オブジェクトへのポインターをこのメソッドに渡します。 ログオン メソッドは、ログオン オブジェクトをインスタンス化し、サポート オブジェクト ポインターを渡します。 ログオン オブジェクトは、サポート オブジェクトの IUnknown::AddRef メソッドを呼び出して、必要に応じて保持します。 サービス プロバイダーのログオン プロセスの詳細については、「サービス プロバイダー の開始」を参照してください。

クライアントがログオフすると、MAPI はログオン オブジェクトのログオフ メソッドを呼び出します。 ログオフ メソッドは、サポート オブジェクトの IUnknown::Release メソッドを呼び出して、プロバイダーがサポート メソッドを呼び出す予定がなくなったことを示します。 ログオンと同様に、ログオフ メソッドの名前は少し異なります。 IABLogon インターフェイスと IMSLogon インターフェイスにはログオフ メソッドがあります。IXPLogon インターフェイスには TransportLogoff メソッドがあります。

メッセージ サービス エントリ ポイント関数は、ログオン試行がエラー MAPI_E_UNCONFIGUREDで失敗したとき、またはクライアントが構成要求を開始したときに呼び出されます。 MAPI は、構成サポート オブジェクトをインスタンス化し、構成されていないプロバイダーまたは構成が変更されるプロバイダーのメッセージ サービス エントリ ポイント関数を呼び出します。 他のサポート オブジェクトとは異なり、構成サポート オブジェクトはエントリ ポイント関数が返されるまで有効です。メッセージ サービスは、これらのオブジェクトを保持するために AddRef メソッドを呼び出しません。

通常、MAPI はプロバイダーのメッセージ サービス エントリ ポイント関数を呼び出しますが、プロバイダーが呼び出しを行うように求められる場合があります。 これは、クライアントがプロバイダーの IMAPIStatus::SettingsDialog メソッドを呼び出して、プロバイダーに構成プロパティ シートの表示を求める場合に発生する可能性があります。 SettingsDialogIMAPISupport::GetSvcConfigSupportObj を呼び出して、メッセージ サービス エントリ ポイント関数に渡すことができる構成サポート オブジェクトを取得する必要があります。

IMAPISupport::GetMemAllocRoutines メソッドは、MAPI とリンクすることなく、メモリ割り当ておよび割り当て解除関数のアドレスを決定するために使用できます。 GetMemAllocRoutines を使用すると、割り当て関数呼び出しをデバッグ コードで囲むことで、メモリ リークをトレースしやすくなります。 推奨されるように GetMemAllocRoutines を呼び出す場合は、CreateIProp 関数を呼び出す前に実行します。これには、割り当て関数アドレスをパラメーターとして必要とします。

新しいアドレス帳またはメッセージ ストア オブジェクトを作成する必要がある場合は、 PR_SEARCH_KEY (PidTagSearchKey) プロパティで オブジェクトの検索キーを作成して設定します。 IMAPISupport::NewUID を呼び出して、検索キーの作成に使用する一意の識別子を取得します。 独自のハードコーディングされた MAPIUID を使用しないでください。 プロバイダーの MAPIUID は、エントリ識別子にのみ使用する必要があります。 検索キーの構築の詳細については、「 MAPI レコードと検索キー」を参照してください。

クライアント アプリケーションは、1 つ以上の関連オブジェクトを解放せずにオブジェクトを解放することがあります。 このような場合、プロバイダーは、リリースされていないオブジェクトを使用できない状態でレンダリングする必要があります。 これを行うために、プロバイダーはオブジェクトに接続されているすべてのリソースを解放し、 IMAPISupport::MakeInvalid を呼び出してオブジェクトの vtable を無効にします。 MakeInvalid は、vtable の IUnknown メソッド (QueryInterfaceAddRefRelease) を標準の MAPI 実装に置き換え、他のすべてのメソッドがMAPI_E_INVALID_OBJECTを返します。 MakeInvalid は、vtable 以外のすべてのオブジェクトのメモリも解放します。

関連項目

MAPI サービス プロバイダー