次の方法で共有

WIA エラー処理アーキテクチャ

  • [アーティクル]

WIA エラー処理アーキテクチャは、3 つの部分で構成されます。 オペレーティング システム、ドライバー、アプリケーションです。 エラー処理メカニズムは、ストリームベースのデータ転送に依存します。 この転送モデルは、Windows Vista 以降のオペレーティング システムで使用できます。 WIA ドライバーがこの新しいエラー処理手法をサポートする場合は、ドライバーにこの転送モデルを使用するように記述する必要があります。 同様に、この新しいエラー処理アーキテクチャで使用できるようにするには、ストリーム ベースの転送モデルをサポートするようにアプリケーションにも記述する必要があります。

WIA エラー処理は、システム提供、IHV 提供、ISV 提供のコンポーネントで構成されます。 次の図は、各コンポーネントのサプライヤーを示しています。

diagram illustrating wia error-handling components.

考えられるエラー ハンドラーには、アプリケーション エラー ハンドラー、ドライバー エラー ハンドラー、既定のエラー ハンドラーの 3 つがあります。 これら 3 つのエラー ハンドラーを次の図に示します。

diagram illustrating the three wia error handlers.

この画像には、WIA プロキシ コールバックによってこれら 3 つのエラー ハンドラーが試行される階層も示されています。

ほとんどの点で、これらのハンドラーは同じです。 ただし、若干の違いがあります。 アプリケーション エラー ハンドラーは IWiaAppErrorHandler インターフェイスを実装しますが、ドライバーのエラー拡張機能と既定のエラー ハンドラーは IWiaErrorHandler インターフェイスを実装します。 アプリケーション エラー ハンドラーでは、コールバック オブジェクトに実装する必要がある IWiaTransferCallback も使用されます。

デバイスの状態コードは、IWiaErrorHandler::ReportStatus の hrStatus パラメーターを使用してエラー ハンドラーに渡されます。 これは、ミニドライバーが IWiaTransferCallback::WiaTransferParams メソッドの hrErrorStatus パラメーターに設定した値と同じです。

hrStatus パラメーターが SEVERITY_SUCCESS に設定されている場合は、致命的でない遅延を表します。 つまり、エラー処理 UI は、モードレスの情報ダイアログ ボックスを提供し、転送をキャンセルできるようにするだけです。 次にエラー ハンドラーが別の hrStatus 値を持つメッセージを受信した場合 (エラー ハンドラーがこのメッセージをサポートしているかどうか) は、UI を閉じる必要があります。

注同時に表示できるモードレス エラー ハンドラー ダイアログ ボックスは 1 つだけです。

エラー ハンドラーは、 SEVERITY_ERROR のデバイスの状態メッセージに応じてモーダル UI を表示する必要があります。

WIA エラー処理には、次の 4 つのコンポーネントが関係しています。

WIA ミニドライバー
ミニドライバーは、Windows Vista の新機能である WIA_TRANSFER_MSG_DEVICE_STATUS デバイス状態メッセージを使用して、デバイス レベルで何かが発生したことを示すようになりました。 ドライバーは、このメッセージを送信するときに、IWiaTransferCallback::WiaTransferParams メソッドの hrErrorStatus (および場合によっては lPercentComplete) パラメーターも設定する必要があります。 状態コードは、エラーまたは情報のいずれかになります。 エラー状態コードが発生した場合、エラーから回復するにはユーザーの介入が必要です。エラーは回復可能です。 ドライバーは、WIA_STATUS_WARMING_UP などの定義済みの WIA HRESULT 値に hrErrorStatus を設定するか、独自のカスタム HRESULT を作成できます。

アプリケーション エラー ハンドラー
アプリケーションでエラー処理を有効にするには、IWiaAppErrorHandler インターフェイスを実装する必要があります。 このインターフェイスは、IWiaTransfer::Download メソッドと IWiaTransfer::Upload メソッドに渡されたアプリケーションのコールバック オブジェクトによって実装されます。 このコールバック オブジェクトは、IWiaTransferCallback インターフェイスを実装するために必要です。 IWiaAppErrorHandler を実装することで、アプリケーションは、データ転送中にエラー ハンドラーを呼び出すことを許可していることを示します。

ドライバーのエラー ハンドラー
ドライバーのエラー ハンドラーは、IWiaErrorHandler インターフェイスを実装する必要があるドライバー拡張機能です。 エラー ハンドラーは、任意の状態コードの UI を処理して表示できます。これらの状態コードには、WIA で定義された状態コードと、ドライバーに固有の状態コードが含まれます。

既定のエラー ハンドラー
既定のエラー ハンドラーは WIA によって実装されます。 これは、多数の汎用デバイスの状態メッセージの UI を処理して表示します。 これらのメッセージは、WIA_ERROR_PAPER_JAM や WIA_STATUS_WARMING_UP など、情報メッセージとエラー メッセージの両方になります。

WIA プロキシは、エラー メッセージ自体を処理しません。 代わりに、WIA プロキシは、エラー ハンドラーがデバイスの状態メッセージを処理できるようにします。

エラー ハンドラーは、ユーザーがシステムをデータ転送を続行する、または取り消せる状態にできる UI を提供します。

WIA_TRANSFER_MSG_DEVICE_STATUS メッセージを受信すると、WIA プロキシは最初にアプリケーション エラー ハンドラーの IWiaAppErrorHandler::ReportStatus メソッドを呼び出します。 アプリケーション コールバック ルーチンがデバイスの状態コードを処理しない場合、WIA プロキシはドライバー エラー ハンドラーの IWiaErrorHandler::ReportStatus 実装を呼び出し、最後に WIA プロキシは既定のエラー ハンドラーの IWiaErrorHandler::ReportStatus 実装を呼び出します。 特定のハンドラーが存在しない場合 (たとえば、ドライバーにエラー処理拡張機能が付属していない場合)、またはドライバーのデバイス状態ハンドラーが WIA_STATUS_NOT_HANDLED を返す場合、ドライバーのハンドラーがデバイス コードをサポートしていないことを示しており、チェーンの次のハンドラーに機会が与えられます。 デバイスの状態メッセージが正常に処理される、または処理に失敗すると、WIA プロキシ コールバックが返されます。 そのため、ドライバー エラー ハンドラーの ReportStatus メソッドがすべてのメッセージに対して S_OK を返した場合、既定のエラー ハンドラーはデバイスの状態メッセージを処理する機会を得ることはありません。

SEVERITY_ERROR (エラー メッセージ) を含むデバイスの状態メッセージをサポートするエラー ハンドラーがない場合、WIA プロキシはドライバーに状態エラーを返し、転送を停止する必要があります。 ドライバーは IWiaMiniDrv::d rvAcquireItemData からこの HRESULT 値を返す必要があり、アプリケーションはこの HRESULT を IWiaTransfer::D ownload または IWiaTransfer::Upload から受け取ります。

エラー ハンドラーが SEVERITY_SUCCESS (情報メッセージ) でデバイスの状態メッセージを処理しない場合、WIA プロキシはドライバーに S_OK を返します。

注: アプリケーションのコールバック ルーチン IWiaTransferCallback::TransferCallback は、WIA_TRANSFER_MSG_DEVICE_STATUS に設定されたlMessage を含むメッセージを受信することはありません。 代わりに、これらのメッセージはエラー ハンドラーに送信されます。

IWiaTransferCallback、IWiaAppErrorHandler、および IWiaTransfer インターフェイスについては、Microsoft Windows SDK のドキュメントで説明されています。