Arquitetura de tratamento de erros do WIA

A arquitetura de tratamento de erros do WIA é composta por três partes. O sistema operacional, o driver e o aplicativo. O mecanismo de tratamento de erros depende de transferências de dados baseadas em fluxo. Esse modelo de transferência está disponível no Windows Vista e em sistemas operacionais posteriores. Os drivers WIA deverão ser escritos para usar esse modelo de transferência se quiserem dar suporte a essa nova metodologia de tratamento de erros. Da mesma forma, os aplicativos também devem ser gravados para dar suporte ao modelo de transferência baseado em fluxo para poder participar dessa nova arquitetura de tratamento de erros.

O tratamento de erros wia é composto por componentes fornecidos pelo sistema, fornecidos por IHV e fornecidos pelo ISV. O diagrama a seguir ilustra o fornecedor de cada componente.

Há três manipuladores de erros possíveis: o manipulador de erros do aplicativo, o manipulador de erros do driver e o manipulador de erros padrão. Esses três manipuladores de erros são mostrados no diagrama a seguir.

A imagem também mostra a hierarquia na qual esses três manipuladores de erro são tentados pelo retorno de chamada do Proxy WIA.

Na maioria dos aspectos, esses manipuladores são idênticos. No entanto, há algumas diferenças. O manipulador de erros do aplicativo implementa a interface IWiaAppErrorHandler , enquanto a extensão de entrega de erro do driver e o manipulador de erros padrão implementam a interface IWiaErrorHandler . O manipulador de erros do aplicativo também usará IWiaTransferCallback, que deve ser implementado no objeto de retorno de chamada.

O código de status do dispositivo é passado para um manipulador de erros com o parâmetro hrStatus de IWiaErrorHandler::ReportStatus. Esse é o mesmo valor que o minidriver definido no parâmetro hrErrorStatus do método IWiaTransferCallback::WiaTransferParams .

Se o parâmetro hrStatus estiver definido como SEVERITY_SUCCESS, ele representará um atraso não fatal. Isso significa que a interface do usuário de tratamento de erros deve fornecer apenas uma caixa de diálogo sem formação, informativa e uma chance de cancelar a transferência. A interface do usuário deve ser ignorada na próxima vez que o manipulador de erros receber uma mensagem com um valor hrStatus diferente (se o manipulador de erros dá suporte a essa mensagem).

Nota Somente uma caixa de diálogo do manipulador de erros sem formatar pode ser mostrada ao mesmo tempo.

Um manipulador de erros deve exibir a interface do usuário modal em resposta a um dispositivo status mensagem de SEVERITY_ERROR.

Há quatro componentes envolvidos no tratamento de erros do WIA:

O minidriver WIA
O minidriver agora pode usar o novo para Windows Vista WIA_TRANSFER_MSG_DEVICE_STATUS dispositivo status mensagem para indicar que algo aconteceu no nível do dispositivo. Quando o driver envia essa mensagem, ele também deve definir o parâmetro hrErrorStatus (e possivelmente também o lPercentComplete) do método IWiaTransferCallback::WiaTransferParams . O código status pode ser um erro ou informativo. No caso de um erro status código, a intervenção do usuário é necessária para se recuperar do erro, desde que o erro seja recuperável. Um driver pode definir hrErrorStatus como um valor WIA HRESULT predefinido, como WIA_STATUS_WARMING_UP, ou criar seu próprio HRESULT personalizado.

O manipulador de erros do aplicativo
Para que um aplicativo habilite o tratamento de erros, ele deve implementar a interface IWiaAppErrorHandler . Essa interface é implementada pelo objeto de retorno de chamada do aplicativo que ele passou para os métodos IWiaTransfer::D ownload e IWiaTransfer::Upload . Esse objeto de retorno de chamada é necessário para implementar a interface IWiaTransferCallback . Ao implementar IWiaAppErrorHandler, um aplicativo indica que ele permite que manipuladores de erros sejam invocados durante transferências de dados.

Manipulador de erros do driver
O manipulador de erros do driver é uma extensão de driver que deve implementar a interface IWiaErrorHandler. O manipulador de erros pode manipular e exibir a interface do usuário para qualquer código status; esses códigos de status incluem códigos de status definidos por WIA, bem como códigos status específicos para o driver.

O manipulador de erros padrão
O manipulador de erros padrão é implementado pelo WIA. Ele manipula e exibe a interface do usuário para várias mensagens genéricas de status de dispositivo. Essas mensagens podem ser informativas e de erro, por exemplo: WIA_ERROR_PAPER_JAM e WIA_STATUS_WARMING_UP.

O proxy WIA não manipula as mensagens de erro em si. Em vez disso, o proxy wia dá aos manipuladores de erro a chance de lidar com um dispositivo status mensagem.

O manipulador de erros fornece a interface do usuário que permite que o usuário tente colocar o sistema em um estado em que a transferência de dados pode ser continuada ou cancelada.

Ao receber uma mensagem WIA_TRANSFER_MSG_DEVICE_STATUS, o proxy WIA primeiro chama o método IWiaAppErrorHandler::ReportStatus do manipulador de erros do aplicativo. Se a rotina de retorno de chamada do aplicativo não manipular o dispositivo status código, o proxy WIA invocará a implementação IWiaErrorHandler::ReportStatus do manipulador de erros do driver e, por fim, o proxy WIA invocará a implementação IWiaErrorHandler::ReportStatus do manipulador de erros padrão. Se um determinado manipulador não existir (por exemplo, o driver pode não vir com uma extensão de tratamento de erro) ou se o dispositivo do driver status manipulador retornar WIA_STATUS_NOT_HANDLED, indicando que o manipulador do driver não dá suporte ao código do dispositivo, o próximo manipulador na cadeia terá uma chance. Depois que um dispositivo status mensagem for tratada, com êxito ou sem êxito, o retorno de chamada de proxy WIA retornará. Portanto, se o método ReportStatus do manipulador de erros de driver retornar S_OK para cada mensagem, o manipulador de erros padrão nunca terá a chance de lidar com nenhuma das mensagens status dispositivo.

Se nenhum manipulador de erros der suporte a um dispositivo status mensagem com SEVERITY_ERROR (mensagem de erro), o proxy WIA retornará o erro status de volta para o driver, que, por sua vez, deve interromper a transferência. O driver deve retornar esse valor HRESULT de IWiaMiniDrv::d rvAcquireItemData e o aplicativo receberá esse HRESULT de IWiaTransfer::D ownload ou IWiaTransfer::Upload.

Se nenhum manipulador de erros manipular um dispositivo status mensagem com SEVERITY_SUCCESS (mensagem informativa), o proxy WIA retornará S_OK ao driver.

Nota A rotina de retorno de chamada do aplicativo, IWiaTransferCallback::TransferCallback, nunca receberá uma mensagem com lMessage definido como WIA_TRANSFER_MSG_DEVICE_STATUS. Em vez disso, essas mensagens serão enviadas para os manipuladores de erros.

As interfaces IWiaTransferCallback, IWiaAppErrorHandler e IWiaTransfer são descritas na documentação do SDK do Microsoft Windows.