IMAPIStatus::ValidateState

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

MAPI リソースまたはサービス プロバイダーで使用できる外部状態情報を確認します。 このメソッドは、すべての状態オブジェクトでサポートされています。

HRESULT ValidateState(
  ULONG_PTR ulUIParam,
  ULONG ulFlags
);

パラメーター

ulUIParam

[in]このメソッドが表示するダイアログ ボックスまたはウィンドウの親ウィンドウへのハンドル。

ulFlags

[in]検証を制御するフラグのビットマスク。 次のフラグを設定できます。

ABORT_XP_HEADER_OPERATION

ユーザーは、通常、対応するダイアログ ボックスの [キャンセル] ボタンをクリックして、操作を 取り消 しました。 status オブジェクトには、次の 2 つのオプションがあります。

  • 操作の作業を続行します。

  • 操作を停止し、MAPI_E_USER_CANCELEDを返します。

CONFIG_CHANGED

状態オブジェクトの構成プロパティの 1 つ以上が変更されました。 クライアントは、MAPI スプーラーが重要なトランスポート プロバイダーのエラーを動的に修正できるように、このフラグを設定できます。

FORCE_XP_CONNECT

status オブジェクトは接続を実行する必要があります。 このフラグを REFRESH_XP_HEADER_CACHE フラグまたは PROCESS_XP_HEADER_CACHE フラグと共に使用すると、キャッシュなしで接続が発生します。

FORCE_XP_DISCONNECT

status オブジェクトは切断操作を実行する必要があります。 このフラグを REFRESH_XP_HEADER_CACHE フラグまたは PROCESS_XP_HEADER_CACHE フラグと共に使用すると、キャッシュなしで切断が発生します。

PROCESS_XP_HEADER_CACHE

ヘッダー キャッシュ テーブル内のエントリを処理し、MSGSTATUS_REMOTE_DOWNLOAD フラグでマークされているすべてのメッセージをダウンロードし、MSGSTATUS_REMOTE_DELETE フラグでマークされたすべてのメッセージを削除する必要があります。 MSGSTATUS_REMOTE_DOWNLOADとMSGSTATUS_REMOTE_DELETEの両方が設定されているメッセージを移動する必要があります。

REFRESH_XP_HEADER_CACHE

リモート トランスポート プロバイダーの場合は、メッセージ ヘッダーの新しい一覧をダウンロードし、メッセージの状態をマークするすべてのフラグをクリアする必要があります。

SUPPRESS_UI

状態オブジェクトが操作の一部としてユーザー インターフェイスを表示できないようにします。

戻り値

S_OK

検証は成功しました。

MAPI_E_BUSY

別の操作が進行中です。この操作を開始する前に、完了を許可するか、停止する必要があります。

MAPI_E_NO_SUPPORT

status オブジェクトは、PR_RESOURCE_METHODS (PidTagResourceMethods) プロパティにSTATUS_VALIDATE_STATE フラグがない場合に示すように、検証メソッドをサポートしていません。

MAPI_E_USER_CANCEL

ユーザーは通常、ダイアログ ボックスの [キャンセル] ボタンをクリックして、検証操作を 取り消 しました。 この値は、リモート トランスポート プロバイダーによってのみ返されます。

注釈

IMAPIStatus::ValidateState メソッドは、状態オブジェクトに関連付けられているリソースの状態をチェックします。 ValidateState は、すべての状態オブジェクトに必要な IMAPIStatus インターフェイスの唯一のメソッドです。 このメソッドの正確な動作は、実装によって異なります。 次の表では、さまざまな種類の状態オブジェクトの実装について説明します。

Status オブジェクト ValidateState の 実装
MAPI サブシステム
 現在アクティブなサービス プロバイダーとサブシステム自体が所有しているすべてのリソースの状態を検証します。
MAPI スプーラー
 既にログオンされているかどうかに関係なく、すべてのトランスポート プロバイダーのログオンを実行します。
MAPI アドレス帳
 プロファイル セクションのエントリを確認します。
サービス プロバイダー
 実装は、プロバイダーの種類と ulFlags パラメーターに設定されたフラグによって異なります。

実装に関するメモ

リモート クライアント アプリケーションは ValidateState メソッドを呼び出して、さまざまなアクションのリモート処理を開始します。 このメソッドは、実際に作業を行う代わりに、MAPI スプーラーと通信するように状態ビットを設定するために主に存在します。 通常、トランスポート プロバイダーは、クライアントの要求を完了するために開始する必要があるアクションを MAPI スプーラーに示すフラグを状態行に設定します。

クライアントとトランスポートスプーラーの相互作用のこのモデルでは、クライアントによって要求されたアクションは非同期であり、 ValidateState は要求されたアクションが完了する前にを返します。 ただし、必ずしも基になるメッセージング システムに関係しないアクション、またはトランスポート固有のインターフェイスを含むアクションは同期的な操作になります。 クライアント アプリケーションは、次のフラグのビットマスクを渡して、リモート トランスポート プロバイダーが実行する必要があるアクションを指定します。

ABORT_XP_HEADER_OPERATION

可能であれば、リモート トランスポート プロバイダーはヘッダーのダウンロードに関連するすべての操作を取り消す必要があります。 これを行うには、トランスポート プロバイダーがログオン オブジェクトの状態行に次のプロパティ値を設定する必要があります。

  • PR_STATUS_CODE (PidTagStatusCode) プロパティのSTATUS_INBOUND_ENABLEDビットとSTATUS_INBOUND_ACTIVE ビットをクリアして、MAPI スプーラーに、このトランスポート プロバイダーの受信フラッシュ プロセスを停止するように指示します。

  • PR_STATUS_CODE プロパティで STATUS_OFFLINE ビットを設定します。

  • PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) プロパティを TRUE に設定します。

  • PR_STATUS_STRING (PidTagStatusString) プロパティを、トランスポート プロバイダーの状態をユーザーに示す文字列に設定します。

  • S_OK ��Ԃ��܂��B ただし、進行中の操作を取り消すことができない場合、 ValidateState はMAPI_E_BUSYを返す必要があります。

FORCE_XP_CONNECT

リモート トランスポート プロバイダーは、 IXPLogon::FlushQueues メソッドに関連する MAPI スプーラートランスポート操作のコンテキストの外部にある共有リソース (モデムや COM ポートなど) への接続を確立しないでください。 このフラグで ValidateState が呼び出された場合、トランスポート プロバイダーは次の操作を行う必要があります。

  • IXPLogon::FlushQueues メソッドが呼び出されたときにリモート接続を確立する必要があることを示す内部状態フラグを設定します。

  • MAPI スプーラーがキューのフラッシュ プロセスを開始するように、状態テーブルに正しい値を設定します。

  • キューのフラッシュが完了したら、共有リソースを解放します。

  • PR_STATUS_CODE プロパティの STATUS_OFFLINE ビットをクリアします。

  • S_OK ��Ԃ��܂��B

FORCE_XP_DISCONNECT

リモート トランスポート プロバイダーは、メッセージング システム リソースへの接続を解放する必要があります。 これを行った後、PR_STATUS_CODE プロパティにSTATUS_OFFLINE ビットを設定し、 S_OK を返す必要があります。

PROCESS_XP_HEADER_CACHE

リモート トランスポート プロバイダーは、リモート メッセージを処理し、遅延されたメッセージをアップロードする必要があります。 これを行うには、トランスポート プロバイダーがログオン オブジェクトの状態行に次のプロパティ値を設定する必要があります。

  • PR_STATUS_STRING プロパティを、トランスポート プロバイダーの状態をユーザーに示す文字列に設定します。

  • PR_STATUS_CODE プロパティでSTATUS_OUTBOUND_ENABLEDビットと STATUS_OUTBOUND_ACTIVE ビットを設定します。

  • トランスポート プロバイダーの状態行の PR_REMOTE_VALIDATE_OK プロパティを FALSE に設定します。

  • ValidateState が呼び出されたときに別の操作 (ヘッダーのダウンロードなど) が進行中の場合、ValidateState はMAPI_E_BUSYを返す必要があります。

  • microsoft Exchange クライアントの要件を満たすために、REFRESH_XP_HEADER_CACHE フラグを処理するコードも実行します。

REFRESH_XP_HEADER_CACHE

リモート トランスポート プロバイダーは、メッセージング システムから新しいメッセージ ヘッダーを取得する必要があります。 これを行うには、トランスポート プロバイダーで次の操作を行う必要があります。

  • PR_STATUS_STRING プロパティを、トランスポート プロバイダーの状態をユーザーに示す文字列に設定します。

  • PR_STATUS_CODE プロパティでSTATUS_INBOUND_ENABLEDビットと STATUS_INBOUND_ACTIVE ビットを設定します。

  • PR_STATUS_CODE プロパティの STATUS_OFFLINE ビットをクリアします。

  • PR_STATUS_CODE プロパティで STATUS_ONLINE ビットを設定します。

  • トランスポート プロバイダーの状態行の PR_REMOTE_VALIDATE_OK プロパティを FALSE に設定します。

SHOW_XP_SESSION_UI

トランスポート プロバイダーにメッセージ ヘッダーを処理するためのユーザー インターフェイスがある場合 (メッセージのダウンロードを確認するダイアログ ボックスなど)、そのダイアログ ボックスを表示する必要があります。 それ以外の場合、 ValidateState はMAPI_E_NO_SUPPORTを返すことができます。

これらの以外のフラグが渡された場合、 ValidateState はMAPI_E_UNKNOWN_FLAGSを返す必要があります。

トランスポート プロバイダーに対するクライアントの呼び出しは、多くの場合、 IMAPIStatus::ValidateState メソッドに対して行われます。 ValidateState の処理中に、トランスポート プロバイダーは、モデムや COM ポートなど、不足しているシステム リソースを割り当てるアクションを実行しないでください。 これは、MAPI スプーラーが複数のトランスポート プロバイダーでキューをフラッシュする必要がある場合があるためです。 ただし、クライアントは任意のトランスポート プロバイダーの ValidateState メソッドをいつでも呼び出すことができます。 トランスポート プロバイダーが ValidateState の処理中に不足しているリソースを割り当てようとすると、MAPI スプーラーがキューをフラッシュするように指示した別のトランスポート プロバイダーとの競合が原因でエラーが発生する可能性があります。 MAPI スプーラーの指示の下で、不足しているすべてのリソース割り当てが発生することを許可する場合は、このような競合を回避できます。 トランスポート プロバイダーは 、PR_REMOTE_VALIDATE_OK プロパティをサポートする必要があります。これにより、クライアント アプリケーションは、トランスポート プロバイダーがビジー状態であるか、MAPI スプーラーがアクションを開始するのを待機しているときに検出できます。

呼び出し側への注意

このメソッドを使用すると、他の長い呼び出しが行われる可能性があるため、 ValidateState はMAPI_E_BUSYを返して、このメソッドが別の操作の完了を待機していることを通知できます。 保留中の操作が完了するまで待ってから、別のタスクを試行する必要があります。

トランスポート プロバイダーの状態オブジェクトの呼び出しを最も制御できます。 トランスポート プロバイダーの操作に影響を与える 1 つ以上のフラグを ValidateState に渡すことができます。 たとえば、ABORT_XP_HEADER_OPERATION フラグは、ユーザーが検証を取り消したことを示します。 トランスポート プロバイダーは、中止、MAPI_E_USER_CANCELEDの返し、または続行を決定できます。

サービス プロバイダーの状態オブジェクトまたは MAPI スプーラーの呼び出しでCONFIG_CHANGED フラグを設定して、構成オプションが変更されたことを示すことができます。 CONFIG_CHANGEDを使用して、トランスポート プロバイダーを動的に再構成できます。 サービス プロバイダーの状態オブジェクトの呼び出しでCONFIG_CHANGEDを設定すると、プロバイダーは IMAPISupport::SpoolerNotify の呼び出しで応答し、MAPI スプーラーに変更を通知します。 MAPI スプーラーの状態オブジェクトの呼び出しにCONFIG_CHANGEDを設定すると、スプーラーは、アクティブなトランスポート プロバイダーごとに IXPLogon::AddressTypes を呼び出します。 AddressTypes は、 トランスポートでサポートされているアドレスの種類を MAPI スプーラーに通知します。 一部のサービス プロバイダーでは、検証に時間がかかると予想される場合に進行状況インジケーターも表示されます。 進行状況インジケーターの表示は役立ちますが、必須ではありません。

SUPPRESS_UI フラグを設定すると、構成プロパティ シートや進行状況ダイアログ ボックスを表示できません。

関連項目