状態オブジェクトの実装

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

すべてのサービス プロバイダーは、状態オブジェクトを実装し、そのオブジェクトからセッション状態テーブルにプロパティを提供する必要があります。 制御するリソースの数に応じて、状態テーブルに 1 つ以上の行を含めることができます。 たとえば、トランスポート プロバイダーは、管理する各メッセージ キューの状態テーブルに行を作成する必要があります。 変更が発生した場合は、適切な状態テーブル行を更新する必要があります。 状態オブジェクトは、状態テーブルに含まれる情報と、テーブルに含まれていない追加情報の両方へのアクセスを提供するために実装されます。

状態オブジェクトを実装するには

  1. ログオン オブジェクトの OpenStatusEntry メソッドを実装します。 クライアントが状態オブジェクトを開く場合は、 IMAPISession::OpenEntry を呼び出します。 MAPI は、プロバイダーの OpenStatusEntry メソッドを呼び出してオープン要求を満たし、プロバイダーがその状態オブジェクトを開き、 IMAPIStatus 実装へのポインターをクライアントに返します。 OpenStatusEntry 実装で、次の手順を実行します。

    1. ログオン オブジェクトがまだ状態オブジェクトを作成していない場合は、次のタスクを実行します。

      1. サポート オブジェクトの IMAPISupport::OpenProfileSection メソッドを呼び出して、プロバイダーのプロファイル セクションにアクセスします。

      2. 新しい状態オブジェクトを作成します。

      3. プロバイダーの status オブジェクトに profile セクションへの参照を格納し、プロファイル セクションの IUnknown::AddRef メソッドを呼び出して参照カウントをインクリメントします。

      4. プロバイダーの状態オブジェクトにログオン オブジェクトへの参照を格納し、ログオン オブジェクトの IUnknown::AddRef メソッドを呼び出して参照カウントをインクリメントします。

      5. 状態オブジェクトへの参照をプロバイダーのログオン オブジェクトに格納します。

    2. 状態オブジェクトの IUnknown::AddRef メソッドを呼び出して、ログオン オブジェクトの参照カウントをインクリメントします。

    3. status オブジェクトの PR_OBJECT_TYPE (PidTagObjectType) プロパティを MAPI_STATUS に設定します。

    4. 状態オブジェクトを指すように lppMAPIStatus 出力パラメーターを設定し、 を返します。

    5. ulFlags 入力パラメーターを確認します。 MAPI_MODIFYに設定されていて、プロバイダーがその状態オブジェクトへの読み取り/書き込みアクセスをサポートしている場合は、書き込み可能なオブジェクトを返します。 ただし、プロバイダーが状態オブジェクトへの読み取り/書き込みアクセスをサポートしていない場合は、失敗しないでください。 読み取り専用の状態オブジェクトを返します。 読み取り/書き込み状態オブジェクトを受け取る必要があるクライアントは、変更を行う前に、読み取り/書き込みアクセス許可が付与されていることを確認する必要があります。

  2. 必要なすべての状態オブジェクトと状態テーブルのプロパティを設定します。 状態テーブルの行に含めるプロパティは、MAPI によって計算されるプロパティを除き、状態オブジェクトを使用して使用できる必要があります。 必要なプロパティは次のとおりです。

  3. プロバイダーに適した IMAPIStatus : IMAPIProp メソッドを実装します。 プロバイダーによっては、 IMAPIStatus で 4 つのメソッドをすべて実装する必要はありません。 すべてのプロバイダーは、 IMAPIProp: IUnknown インターフェイスと IMAPIStatus::ValidateState メソッドのメソッドの読み取り専用バージョンを実装する必要があります。

    トランスポート プロバイダーは IMAPIStatus::FlushQueues も実装する必要があり、すべてのプロバイダーが IMAPIStatus::SettingsDialog をサポートする必要があります。 ただし、 IMAPIStatus::ChangePassword のサポートは省略可能です。 パスワードを必要とし、ユーザーがプログラムで変更できるようにするサービス プロバイダーのみが、このメソッドを実装する必要があります。 サポートするすべてのメソッドについて、 PR_RESOURCE_METHODS プロパティで対応するビットを設定します。 たとえば、 ValidateState と SettingsDialog のみをサポートしている場合は、 PR_RESOURCE_METHODS を次のように設定します。

    STATUS_VALIDATE_STATE | STATUS_SETTINGS_DIALOG

    クライアントは、状態オブジェクトの呼び出しを試みる前に、PR_RESOURCE_METHODSの値をチェックする必要があります。 サポートされていないメソッドの呼び出しを処理するには、MAPI_E_NO_SUPPORTを返します。

  4. ログオン中に IMAPISupport::ModifyStatusRow を呼び出して、行または行を状態テーブルに追加します。 行の列情報と ulFlags パラメーターの 0 を含むプロパティ値配列を渡します。 セッションの後でプロバイダーの状態が変わり、列情報を更新する必要がある場合は、STATUSROW_UPDATE フラグを設定して ModifyStatusRow をもう一度呼び出します。

状態オブジェクトの詳細については、「 MAPI 状態オブジェクト」を参照してください。

関連項目